A.4. Defining Variables

Engineering Knowledge Manager

User's Guide | Appendix A. Defining a Process Template Using XML |

A.3. Defining an EKM Process Template XML File |  | A.5. Defining Nodes
Prev |  | Next

## A.4. Defining Variables

The definition of a variable is similar to the definition of a property in a custom type file and consists of the following required attributes. Some examples are provided below. Refer to the chapter on Defining Custom Types in the Administration Guide for more details on defining custom types.

- `name`: can be used to display the variable in the user interface. As with property names, variable names cannot contain the following special characters:`/ \ : [ ] % * ' " |`

- `description`: can be used to provide a detailed description of the variable in the user interface. This allows users to understand the meaning of the variable and the value it contains.

- `type`: can be used to specify the type of the variable. Valid values are: `Boolean`, `Date`, `Double`, `Long`, `Reference`, or `String`. These values are same as property types in a custom type definition. See the Defining Custom Types chapter in the Administration Guide for details on these types.

A variable definition may also contain the following optional attributes:

- `id`: can be used to reference the variable in an expression. It can consist of any letter, digit, or the underscore (_) character. You only need to specify an id if the name of the variable contains any character which is not a letter, digit or underscore, for example: -, ?, space character, and so on. Otherwise the name of the variable is automatically assigned as the ID of the variable.

- `multivalued`: can be used to specify whether the variable can have a single value or multiple values. Its value can be either `true` or `false`. If it is unspecified, the value is assumed to be false.

- `default:` can be used to specify the default value of the variable. For multi-valued properties, you can specify the default as a comma-delimited string (for example, `value-1`, `value-2`). If you specify a default value, then you must make sure that the value is correctly specified for the variable type.

  - `Boolean` types can only contain `true` or `false` as valid values. If it is unspecified, then the default value for a `Boolean` type is set to `false`.

  - `Date` types must have default values in either ISO-8601 format or a format that depends on the locale of the EKM server.

    - For ISO-8601, the format is: `YYYY-MM-DDThh:mm:ss.sTZD`, where `hh` is two hour digits (00 through 23) and `TZD` is the time zone designator (Z or +hh:mm or -hh:mm)

      `2007-11-04T18:30-05:00` for Nov. 4, 2007 at 6.30 PM in US Eastern Standard Time

    - For the English locale, the format is: `month/day/year hour:min AM/PM`

      Example: `11/4/07 6:30 PM` for Nov 4, 2007 at 6.30 PM

      `2/21/2008 8:0 AM` for Feb. 21, 2008 at 8:00 AM

      If unspecified, the default value is the current time on the server.

  - `Double` types can contain any valid real number such as `0.0`, `123.456`. You can also use scientific notation such as `1.235E6` or `1.235E-6`. If it is unspecified, the default value for a Double type is set to `0.0`.

  - `Long` types can only contain numbers such as `0`,`5`, `-5` as values. If it is unspecified, the default value for a Long type is set to `0`.

  - `Reference` types can contain the full path to an existing object in EKM as a default value.

    Example: `/Data/Shared Data/my-folder/my-file.txt`

    If it is unspecified, the default value for a Reference type is an empty string `“ ”` that denotes a null reference.

  - `String` can contain any arbitrary text as a value. If it is unspecified, the default value for a String type is an empty string `“ ”`.

A variable definition may also contain the following optional child elements:

- `enumeration`: can be used when you want to choose a variable value from a list of options in the user interface. This list specifies one or more values that a variable can have (depending on whether it is single or multi-valued). For example, a single valued variable (Multi-valued = `false`) named `Solver Version` may take only one of these values [‘v160', 'v161', 'v162', ‘v170’] as its value. In this case, you can specify an enumeration list for the values. A multi-valued variable may take more than one value, but it only be selected from the enumeration list that you specify. Enumerations can be specified for any variable type (for example, Double, Integer, String) except Boolean.

- `constraints`: can be used to add constraints to variable values. Constraints are validated whenever a user provides variable values through the user interface. A validation error message is displayed if a constraint is violated. A constraint element has a `name` and a `value` attribute. A constraints `name` must be one of the following:

  - `min`: can be used to specify the minimum value for a Double or Long type. The value for this constraint denotes the minimum value for the variable.

  - `max`: can be used to specify the maximum value for a Double or Long type. The value for this constraint denotes the maximum value for the variable.

  - `quantity`: can be used for specifying the unit quantity for a Double type. The value for this constraint denotes one of the quantities specified in the /Administration/Configuration/Units.xml file (for example, length, volume, and so on). See the Units: Defining and Configuring Using XML chapter in the Administration Guide for more details on specifying units.

  - `unit`: can be used for specifying the unit for a Double type. The value for this constraint denotes one of the units specified in the /Administration/Configuration/Units.xml file for the quantity specified above. This constraint should only be used if the quantity constraint has been used. For example, if the quantity is length, the acceptable unit values are `m`, `cm`, `ft`, and so on. If a quantity is specified but a unit is not specified, then the chosen unit for this property will be the default unit of the users preferred unit system. For example, if the users preferred unit system is `SI`, the unit will be `m`, and if it is British it will be `ft`. Thus you should specify the unit constraint only if you want to force the property to always be viewed in the specified unit for all users. See the Units: Defining and Configuring Using XML chapter in the Administration Guide for more details on specifying units.

  - `baseType`: can be used to specify the base type for a Reference type. The value for this constraint denotes the base type of the referenced object. For example, you can use it to ensure that a reference always points to an object of type File.

  - `rows`. Can be used to permit multi-line values for a String type. If the number of rows is greater than 1, a text area with the specified number of rows will be rendered instead of a single-line text box. For example, specifying a value of `5` permits the input of 5 lines of text in a text box.

- `displayStyle`: can be used to specify the CSS style to a component that will be rendered for this variable. It can be specified in a similar way in which HTML is specified. For example: "border:2px solid green"

- `updateOnChange`: can be used when you want the value of one variable to change when the value of a corresponding variable is changed. The value of the variable is a comma-separated list of component IDs that must be re-rendered when the corresponding component value changes.

- `readOnly`: can be used to specify whether a variable must be rendered as read-only or requiring user input. When `readOnly` is set to `true`, the variable will be rendered as a label for all variable types except `Reference`. For `Reference`, it will be rendered as a command link.

Important: Object type labels that are displayed in the EKM user interface are localized labels. You must use the non-localized names when referring to built-in types in configuration files. The non-localized labels are shown in parenthesis next to localized labels in the built-in type description in Appendix B: Built-in Types - Reference in the EKM Administration Guide.

### Variable Definition Examples

The following variable definitions are shown below.

- Mesh Name

- Dimension

- Mesh Quality

- Disciplines

- Project

Example 1: Mesh Name Variable defines a variable named `Mesh Name` of type `String`. Because the name contains the space character, an ID `meshName` is also specified. The default value of the variable is `mesh.msh`.

Example 1: Mesh Name Variable

    <variable name="Mesh Name" id="meshName" type="String" default="mesh.msh" description=""/>

Example 2: Dimension Variable defines a variable named `Dimension 1` of type `Double` and id `dim1`. A description is also provided. The default value for this variable is `6.5`. Furthermore this variable has `min` and `max` constraints which specify that the value for this variable should lie between `2.0` and `10.0`.

Example 2: Dimension Variable

    <variable name="Dimension 1" id="dim1" type="Double"
          description="Dimension 1 of the component" default="6.5">
          <constraint name="min" value="2" />
          <constraint name="max" value="10" />
    </variable>

Example 3: Mesh Quality Variable defines a variable named `Mesh Quality` of type `String` and id `quality`. Because enumerations are specified, the value for this variable can only be one of the specified enumerations: `Fine`, `Medium` or `Coarse`.

Example 3: Mesh Quality Variable

    <variable name="Mesh Quality" id="quality" type="String"
          description="Quality of mesh desired">
          <enumeration>Fine</enumeration>
          <enumeration>Medium</enumeration>
          <enumeration>Coarse</enumeration>
    </variable>

Example 4: Disciplines Variable defines a variable named `Disciplines` of type `String`. Because the name does not contain any special characters, no id is specified for this variable. The ID will be automatically assigned using the name of the variable. Because the multi-valued attribute is set to `true` and enumerations are specified, the value can be 0 or more of the specified enumerations: `Stress`, `Thermal`, `Flow`, and `Electromagnetic`.

Example 4: Disciplines Variable

    <variable name="Disciplines" type="String" multivalued="true"
          description="Simulation disciplines">
          <enumeration>Stress</enumeration>
          <enumeration>Thermal</enumeration>
          <enumeration>Flow</enumeration>
          <enumeration>Electromagnetic</enumeration>
    </variable>

Example 5: Project Variable defines a variable named `Project` of type `Reference`. Because the `baseType` constraint is specified, the referenced object should be of the same type as or a subtype of `Project`.

Example 5: Project Variable

    <variable name="Project" type="Reference" description="Project">
          <constraint name="baseType" value="Project" />
    </variable>

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

Release 18.2 - © ANSYS, Inc. All rights reserved.