An Sys Workbench External Connection Add in Guide

ANSYS Workbench External Connection Add-In

Guide

Release 14.0ANSYS, Inc.

November 2011Southpointe

275 Technology Drive

Canonsburg, PA 15317 ANSYS, Inc. is

certified to ISO

9001:[email protected]

http://www.ansys.com

(T) 724-746-3304

(F) 724-514-9494

Copyright and Trademark Information

© 2011 SAS IP, Inc. All rights reserved. Unauthorized use, distribution or duplication is prohibited.

ANSYS, ANSYS Workbench, Ansoft, AUTODYN, EKM, Engineering Knowledge Manager, CFX, FLUENT, HFSS and any

and all ANSYS, Inc. brand, product, service and feature names, logos and slogans are registered trademarks or

trademarks of ANSYS, Inc. or its subsidiaries in the United States or other countries. ICEM CFD is a trademark used

by ANSYS, Inc. under license. CFX is a trademark of Sony Corporation in Japan. All other brand, product, service

and feature names or trademarks are the property of their respective owners.

Disclaimer Notice

THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-

ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products

and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement

that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting

laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products

and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions

of that software license agreement.

ANSYS, Inc. is certified to ISO 9001:2008.

U.S. Government Rights

For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,

duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.

software license agreement and FAR 12.212 (for non-DOD licenses).

Third-Party Software

See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software

and third-party software. If you are unable to access the Legal Notice, please contact ANSYS, Inc.

Published in the U.S.A.

Table of Contents

External Connection Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Introduction ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

General Functionality .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Custom GUI Operation and Properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Custom Toolbar and Menu Entries ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

External Process Responsibilities .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Process Configuration XML File Details .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Configuration Node ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Instructions Node ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Format ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Attributes ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

GuiOperations Node ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Format ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Attributes ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Properties Node ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Format ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Attributes ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

DataEntity ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

DataObject ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

iiiRelease 14.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information

of ANSYS, Inc. and its subsidiaries and affiliates.

External Connection Add-in

Introduction

The purpose of the External Connection add-in is to allow external applications (that are not data integ-

rated with Workbench) to participate in the workflow defined through the project schematic. The

workflow participation is achieved by allowing external applications to define input and output para-

meters that are to be exposed in Workbench. The parameters defined through the External Connection

add-in can be manipulated in the same way as any other parameters—for example, in terms of design

point creation, update, and state. Specifically, the External Connection add-in allows the design explor-

ation capabilities provided by the Design Exploration application to be used with any external application.

The External Connection add-in also provides customization functionality outside of the interaction

with the project schematic. It is possible to define custom entries for buttons to be shown in the toolbar

or as entries in custom menus. The definition of the custom entries includes the definition of scripts to

be executed for the additional entries.

General Functionality

The add-in provides an External Connection system template in the Component Systems toolbox.

The system contains a single External Connection cell/component that acts as a proxy for the external

application.

A GUI operation called Read Configuration is exposed on the context menu of the cell. The command

associated with this GUI operation reads a process configuration XML file, which contains all the inform-

ation that the external application wants to provide to Workbench (see the section “Process Configuration

XML File Details,” below, for more information on the file). At minimum, the configuration file should

contain the following elements:

• The definition of input and output parameters, including the parsing rules for reading the values from

a file.

• An OS executable or a Python script to be executed during the update command. Python scripts are

executed within the Workbench Python interpreter and give full access to the scriptable Workbench

functionality.

The add-in reads the configuration file and stores all the information provided in the file. The information

provided through the configuration file can be accessed through the GUI operation Edit Configuration.

The Configuration settings should be modified only in response to a corresponding change in the ex-

ternal application.

When the update command provided by the cell is executed, the add-in:

1. Writes the current values of the input parameters in the file specified in the configuration

2. Launches the external application

Upon the completion of the external application, the add-in:

1Release 14.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information


1. Verifies the successful execution (and sends an error message if the execution was not successful)

2. Reads the current values of the output parameters provided by the external application in the file

location specified in the configuration

Once a Configuration file has been read, the GUI operation Read Configuration is no longer available.

The Reset operation, also available on the context menu of the cell, can be used to discard the imported

data. A new configuration file can be read after Reset.

Custom GUI Operation and Properties

The functionality of the External Connection is enriched by the ability to define the following in the

configuration file:

1. GUI operations for the context menu of the cell, which can execute custom code or scripts.

2. Properties that can be accessed through the custom functionality executed the by addin. The properties

can be visualized and changed through the Edit Configuration Operation.

Custom Toolbar and Menu Entries

The creation of custom toolbar and menu entries is achieved by providing a configuration file which is

read-in during the add-in load process in a directory located in the installation area or in a location

specific to a given user. Providing the custom files in the installation areas results in additional entries

to be shown for every user who has access to the installation. On the other side, files located in the

user specific area will result into additional entries that appear only for the specific user. The content

of the user specific custom files takes precedence over the custom installation files. The area for user

specific files is examined first. If custom files are also present in the installation area, they are read after-

wards. Entries that are found in the installation file that are also present in the user file are ignored.

Custom files for the installation area should be placed in the ExternalConnection directory under

v140/Addins (for example C:\Program Files\Ansys Inc\V140\Addins\ExternalCon-nection). The location for user-specific custom files depends upon the operating system:

• for Windows machines, a directory named ExternalConnection should be created under %APP-DATA%\Ansys\v140

• for Linux machines, a directory named ExternalConnection should be created under

$HOME/.config/Ansys/v140

For both the custom installation and user-specific case, a directory named Customization should be

created under ExternalConnection. The configuration file (which contains the information about the

custom entries) should be placed under this directory and named CustomToolbarConfiguration.xml.

Additional folders named Images and Scripts should be created under the Customization directory in

order to provide images or scripts defined in the configuration file.

The format of the configuration file for the creation of custom toolbar and menu entries is the same as

the configuration file defined for custom functionality of the ExternalConnection cell. However, only

the GUI operation section is relevant. The content of other sections, if present, is ignored. Some of the

attributes of the GUI operations sections are specific to creation of menu toolbar entries. The usage

details are provided in the section that described the XML file.

External Process Responsibilities

The minimum responsibilities of the external process are as follows:

Release 14.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential informationof ANSYS, Inc. and its subsidiaries and affiliates.2


• Provide a configuration file that contains two elements:

– The definitions of the input/output parameters to be processed

– The name of the update script to be executed

• Read the input parameters from the input file

• Execute a solve/update of the external process

• Write the computed values of the output parameters in the output file

Process Configuration XML File Details

The process configuration XML file contains an <Instructions> XML node, where the information needed

for parameter initialization and for the update of the cell is provided. In addition to the instructions, it

is possible to define the following elements in the configuration file:

• GUI operations that can be executed from the context menu of the cell or from a custom toolbar or

menu entry. Each GUI operation can either define inline C# code or specify a Python script.

• One or more set of data entities with properties. These properties can be accessed from the Python

scripts invoked for update or custom GUI operations.

Detailed documentation of the configuration file is provided in the following section.

Configuration Node

The <Configuration> node contains the <Instructions> , <GUIOperations> and <Properties> nodes.

<Configuration>

</Configuration>

The configuration node allows to specify the following optional attributes:

• SystemName - This is the user-visible string that is assigned to the system

• CellName - This is the user-visible string that is assigned to the cell

• Version - Specifies a version associated with the configuration file

• ShowEditConfiguration - Specifies whether it should be possible to view and modify the entries provided

in the configuration file

Instructions Node

The information related to initialization (including parameters definition) and update is provided inside

the global <Instructions> XML node. A WorkingDirectory is defined inside the Instructions node as de-

scribed below:

<Instructions WorkingDirectory="[ Directory Name ]">

</Instructions>

• [ Directory Name ] — The path of the working directory, with or without the trailing slash. This attribute

is optional. If the working directory is not specified, the default working directory determined by

Workbench will be used. The working directory is also used to search for files defined in other sections

of the configuration file if a full path to the file is not provided.




Format

<Instruction Type="[ Instruction Type ]">

<Name>[ Plug-In Name ]</Name>

<ExePath>[ Executable Path ]</ExePath>

<ErrorFile>[ Error File ] </ErrorFile>

<CheckOnError>[ Error String ] </CheckOnError>

<Args>[ Args ] </Args>

<Script>[ Script ] </Script>

<InterruptScript>[ Interrupt Script ] </InterruptScript>

<StopScript>[ Stop Script ] </StopScript>

<ParameterParsingRules>

<[ Node Name ] Name="[ Parameter Name ]" Type="[Type]">

<[ Rule Name ] Type="[ Rule Type ]">[Value]</[ Rule Name ]>-->

</[ Node Name ]>-->

</ParameterParsingRules>

</Instruction>

Attributes

• [ Instruction Type ] - The type determines where the instruction will be executed.

• Init - The parameter will be executed when the configuration is read

• Update - The parameter will be executed when the project is updated

• [ Plug-In Name ] - The user-defined name of the generic plug-in. This name must be unique throughout

the instruction file. It defines a way for the Workbench environment to identify this instance of the

Generic Plug-In, because it is possible to have several instances (several third party applications or codes)

of the third party Plug-In in the process sequence.

• [ Executable Path ] - The location of the executable file with which the third-party Plug-In will interact.

This can be either the full path or the relative path of the executable with respect to the Working Dir-

ectory for the instruction file.

• [ Error File ] - A file used to communicate that the execution of the external application was not suc-

cessful. The error file needs to be removed by the external application upon completion. If still present,

Workbench will send an error message and stop the update. The content of the error message can

specified through the attribute CheckOnError (see below). A generic message is displayed if CheckOn-

Error is not specified.

• [ Error String ] - If an error file is specified, its content will be scanned for lines that contain the specified

error string. All lines that contain the string will be displayed as error messages (with the error string



stripped from the message). An error string named file will cause the whole content of the file to be

displayed.

• [ Args ] - The command line arguments passed to the executable when run.

• [ Script ] - The Python script to be interpreted within the Workbench framework on execution of this

instruction if the ExePath is not defined. The Python script has access to the following variables:

– container - A string that can be passed to any command or query that requires a data container

reference as argument

– configurationObject - The configuration object can be used in order to access some of the information

specified in the configuration file (for example, working directory or error file). The query GetEnti-

tyProperties(Entity=configurationObject) returns a dictionary which contains all the available inform-

ation.

• [ Interrupt Script ] - An optional Python script that is invoked when the computation in interrupted. In

the WorkBench terminology, the Interrupt operation closes the external application cleanly, allowing

access to data. The Interrupt operation is visible only if the Interrupt script is provided.

• [ Stop Script ] - An optional Python script that is invoked when the computation in stopped. In the

WorkBench terminology, the Stop operation abruptly closes the external application, possibly resulting

in the loss of data. The Stop operation is visible only if the Stop script is provided. The same script can

be used for Stop and Interrupt . Both scripts have access to a variable to the same information (strings

container and configurationObject strings ) that is passed to update script

• [ Node Name ] - A name given to the XML node that defines the parsing information for a single

parameter. This name does not have to be unique but must only adhere to the naming rules for XML

nodes (for example, no spaces or special characters).

• [ Parameter Name ] - A unique name that represents a single parameter in the Workbench environment.

This is the name that will be used to identify the parameter throughout the UI.

• [ Type ] - The general type of the parameter. It must be one of two possible values:

– Input - The parameter will be treated as an input parameter, exactly as input parameters are handled

in the Workbench environment.

– Output - The parameter will be treated as an output or response parameter in the Workbench envir-

onment. When chaining generic Plug-Ins together, each instance of the generic Plug-In can contain

input and output parameters.

• [ Rule Name ] - A name given to the XML node that represents a single parsing rule for the parameter

defined by the rule's parent node. This name does not have to be unique, but only adhere to the

naming rules for XML nodes (for example, no spaces or special characters). Multiple rules can (and in

most cases must) be defined for each parameter. The only restriction is that only one rule of each type

(detailed below) can exist for each parameter.

• [ Rule Type ] - The type of the rule defined. This can be one of the following values.

– File - The file rule defines the text file that contains the parameter value. This file can be the full

path to the file, or the relative path to the file with respect to the Working Directory. Files containing

"Input" type parameters must exist when reading the configuration file.

– StartLine - The line number in the text file that the code will begin parsing. For example, if the first

500 lines of a file contain only comments, begin parsing the file at line 501 to avoid wasting system

resources. The start line is 1 based. Therefore a value of 0 or 1 will be treated in the same way.




– PreString - The text that immediately precedes the actual parameter value in the file. For example,

if the file defines a parameter as "Cf = 12.555" the "PreString" for the parameter would be "Cf =".

This text does not need to include any white space immediately preceding the parameter value.

– DataType - Describes the type of data that represents the parameter. Must be one of the following

values.

1. float: The value of the parameter is a floating point (decimal) number. This is used for continuous

variables.

2. double: The value of the parameter is a double.

3. quantity: The value of the unit is a quantity containing a numeric value with units in the form

“value [unit]” (for example, “20 [m s^-1]”)

– SkipOccurrences - The number of occurrences of "PreString" to skip before parsing begins.

• [ Value ] - The value of the rule. No quotes are needed to delimit this value, as per the XML parsing

rules. For example, a "SkipOccurrences" node would look like

<Rule Type="SkipOccurrences">3</Rule> where "3" is the [Value] for the rule, signifying that 3

lines should be skipped in the file before searching for the parameter.

GuiOperations Node

Custom GUI operations can be added to the context menu of the External Connection system. They

can also be added as custom toolbar buttons or entries in a custom menu. The custom operations allow

the definition of a script or C# code that is executed upon invoking the operation.

<GuiOperations> </GuiOperations>

Format

<GuiOperation Name="[ Operation Name ]" Priority="[ Priority ]" SourceType="[ SourceType ]" Type="[

Type ]" Entry="[ Entry ]" ScriptFile="[ Script ]" Image="[ Image ]"> Tooltip="[ Tooltip ]">

<Code>[ Code ]</Code>

</GuiOperation>

Attributes

• [ Operation Name ] - The name shown in the context menu.

• [ Priority ] - The weighted value determining the location within the context menu, the toolbar or the

menu where the GUI operation is defined.

• [ SourceType ] - The type of code being used to define what is being executed when the operation is

executed.

– Csharp - The code will be written in C#

– Python - The code will be written in Python.

• [ Type ] - The type specifies where the GUI operation should be placed in the User interface. The allowed

types are:

– ContextMenuEntry - This is the default type and should be specified in order to define GUI operations

that are shown upon selection of the cell of the ExternalConnection system. ContextMenu should



NOT be specified for operations defined in configuration files located in the installation area or in

the user specific area since it is not possible to associate them with a specific cell.

– ToolbarButton - The type ToolbarButton should be used for creating custom entries in the toolbar.

This type should NOT be specified for GUI operations defined on the configuration file for a cell. It

is reserved for configuration files that are processed at add-in load from the installation or user

specific areas.

– MenuEntry - The type MenuEntry should be used for creating custom entries in Menu. The newly

created Menu Entry is specified via the attribute Entry defined below. This type should NOT be

specified for GUI operations defined on the configuration file for a cell. It is reserved for configuration

files that are processed at add-in load from the installation or user specific areas.

• [ Entry ] - The Entry attribute is relevant only in conjunction with a specified Type=MenuEntry. It defines

the name of a new Menu Entry where the GUI operation is shown. It is also possible to defined sub-

menus of a given menu as comma separated values. For example, specifying Entry as "NewMenu, Sub-

Menu1" will result in the GUI operation appearing from a sub-menu "SubMenu1" of a Menu Entry

"NewMenu"

• [ Code ] - This allows code to be executed to be defined inside the configuration file, rather than a

separate file:

<GuiOperations>

<! - Code can either be loaded from a file with the "ScriptFile" attribute, or be included in a "Code" tag

- >

<GuiOperation Name="Enter Something" Priority="2" SourceType="CSharp">

<Code>

<![CDATA[

Ansys.UI.Toolkit.MessageBox.Show("This is a test");

]]>

</Code>

• [ Script ] - This specifies the path to a Python script to be run on execution of the operation. Specific-

ation of the script cannot be combined with execution of custom code. Therefore a script should not

be included if code is defined inside the tags of the GuiOperation. Scripts invoked from a GUI operation

defined on the ContextMenu of the cell have access to the following variables:

– container - A string that can be passed to any command or query that requires as argument the

reference to the data container associated with the cell

– configurationObject - The configuration object can be used in order to access some of the information

specified in the configuration file (for example, a working directory or error file). The query

GetEntityProperties(Entity=configurationObject) returns a dictionary which contains all the available

information.

When the GUI operation invokes a script, the invocation of the script is wrapped in a command. It is

possible to specify scripts to be executed in order to interrupt or cancel the execution of the command.

It is also possible to specify an error file to provide messages when the command execution fails, with

the same control on the error display that is provided for the update. A detailed description of the at-

tributes is given below:




1. InterruptScript=[string] An optional Python script that is invoked when the computation in interrupted.

In the WorkBench terminology, the Interrupt operation closes the external application cleanly, allowing

access to data. The Interrupt operation is visible only if the Interrupt script is provided.

2. StopScript=[string] An optional Python script that is invoked when the computation in stopped. In the

WorkBench terminology, the Stop operation abrubtly closes the external application, possibly resulting

in the loss of data. The Stop operation is visible only if the Stop script is provided. The same script can

be used for Stop and Interrupt . The script has access to the same information (strings container

and configuarionObject ) that is passed to executing script.

3. ErrorFile=[string] A file used to communicate that the execution of the external application was not

successful. The error file needs to be removed by the external application upon completion. If it is still

present, Workbench will send an error message. The content of the error message can specified through

the attribute CheckOnError (see below). A generic message is displayed if CheckOnError is not specified.

4. CheckOnError=[string] If an error file is specified, its content will be scanned for lines that contain the

specified error string. All lines that contain the string will be displayed as error messages (with the

error string stripped from the message). An error string named file will cause the whole content of

the file to be displayed.

5. UseUpdateConfiguration=[boolean] This variable can be specified as a shortcut, in order to use for the

custom GUI operation the same files specified in the Update instructions for stop/interrupt and for

controlling the error message display. If the attribute is True and the attributes above are not specified,

the code will use the ones provided for the first update instruction, if specified.

• [ Image ] - The image is the name (without extension) of a file containing an image to be used for the

GUI operation. Files with common extension for images are searched under the Images directory under

ExternalConnection add-in. If a Customization directory is provided under the installation or user specific

area, the corresponding Images directories are also searched for the specified file.

• • [ Tooltip ] – A string to be displayed as Tooltip for operation of type ToolbarButton. The string has no

effect for other operation types.

Properties Node

Custom properties can be defined in the <Properties> XML node.

Properties are used to create dynamic data objects in Workbench; therefore, their definitions reflect the

internal organization of the WorkBench data model. Properties should be assigned a DataEntity and an

ObjectName . The DataEntity is a string that defines high level grouping for the properties. One or more

objects can be created for a given DataEntity .

A DataObject “ObjectName” (as defined by its DataEntity and properties) is added to the container as-

sociated with the cell from which the configuration is read. If different ExternalConnection systems are

present, each has a separate container.

Format

<Properties>

<DataEntity Name= “[Data Entity Name ]” Label = “[Data Entity Label ]” >

<Object Name= “[Data Object Name ]” >

<Property Name= “[ Property Name ]” Label= “[ Property Label ]” DataType= “[ Data Type ]” Value=

“[Value]”



Label= “[ Property Label ]” Group = “[ Group ]” IsReadOnly = “[ IsReadOnly ]” IsExtrinsic = “[ IsExtrinsic ]”

IsVisible = “[ IsVisible ]” Min = “[ Min ]” Max = “[ Max ]” OptionLabels = “[ Option Labels ]”/>

</Object>

</DataEntity>

</Properties>

Attributes

DataEntity

• [ Data Entity Name ] -The internal (immutable) name assigned to the Data Entity. If this attribute is

not specified, a default name is assigned internally. However, specification of a name allows for

the retrieval of the properties associated with objects of the Data Entity (see below). A special name

“CellProperties” is reserved for the DataEntity whose properties should be displayed in the User

Interface from the context menu of the associated cell.

• [ Data Entity Label ] -The display name (user changeable) assigned to the Data Entity in the User

Interface.

DataObject

[ Data Entity Name ] - The internal (immutable) name assigned to the Data Object. If this attribute is

not specified, a default name is assigned internally. However, specification of a name allows for the re-

trieval of the properties associated with the given object (see below).

Properties

Mandatory attributes for the definition of a property are:

• [Property Name] - The name to be assigned to the property, unique for that DataEntity

• [Type] - The type of data which the properties defined. Currently supported types include:

– int

– double

– string

– quantity

– bool

– option

– DataReference

• [Value] - A string representing the value to be assigned to the property, which is parsed by the

code according to the type.

– The bool type can assume the values of “True” or “False”

– A quantity type should be specified by providing a string of type “double [ unit ]” (for example,

“23 [ms^-1]” )

– The options type is used for mutually exclusive choices, that should be specified by comma

separated strings without blanks (for example, “[Option1,Option2]”)

– The DataReference type should be specified by a string of type DataEntityType:ObjectName




Optional attributes are:

• [Property Label] - This is the user visible string that can be assigned to the property (default is the

property name)

• [Group] - This can be used for further grouping (for UI purpose only)

• [IsReadOnly] (“True”/”False”) - Specifies that the property cannot be edited. Default is "False"

• [IsExtrinsic] - (“True”/”False”) Specifies that the property is not relevant for the computation of the

state of the cell. Default is "False"

• [IsVisible] (“True”/”False”) - Specifies whether the property should be shown in the UI. Default is

"True"

• [Min] - Specifies the lowest range for the property Value

• [Max] - Specifies the highest range for the property Value

• [OptionLabels] (for option type only) - Specifies the visible names for the options, to be used in the

User Interface, specified by comma separated strings without blanks (for example “[Background,Fore-

ground]”)

The value for each property can be accessed from any Python script used with Workbench via the

Workbench query GetEntityProperty, as described below

dataReference = “/” + container + “/” + DataEntityName = “:” + ObjectName

propertyVal = GetEntityProperty(Entity=dataReference, Name=PropertyName)

where

• container is the name of the container associated with the cell. This information is typically available

in the function where the Python script is called from (for example, the update script for a cell or

the script invoked from a GUI operation selected on a given cell)

• DataEntityName is the name specified in the configuration file. For example: <DataEntity

Name="MyDataEntity">

• ObjectName is the name specified in the configuration file. For example: <Object Name= "MyOb-

jectName">

• PropertyName is the name of the property specified in the configuration file.

It is also possible to change the value of the properties that are not marked as read-only using the

Workbench SetEntityProperty command:

SetEntityProperty(Entity=dataReference,Name=PropertyName, Value=value)

Where value is the appropriate type for the property being modified. For example, a property of type

quantity named “InletVelocity” defined for an object AnsSettingsObject and DataEntity type Settings-

DataEntity can be queried and set as follows:

dataReference = “/” + container + “/” + “SettingsDataEntity”+ “:” + “AnsSettingsObject” value = GetEntityProp-

erty(Entity=dataReference, Name = “InletVelocity”) SetEntityProperty(Entity= dataReference, Name = “InletVe-

locity”, Value=”10 [m s^-1]”)



An Sys Workbench External Connection Add in Guide

Documents

Transcript of An Sys Workbench External Connection Add in Guide