7.4.2. Defining Properties Using XML

Engineering Knowledge Manager

Administration Guide | Chapter 7: Defining Custom Types | 7.4. Defining Custom Types Using XML |

7.4.1. Schema Definition for Custom Types |  | 7.4.3. Defining Actions Using XML
Prev |  | Next

### 7.4.2. Defining Properties Using XML

This section describes how to define properties for a custom type and includes examples of property definitions.

Property definitions are used to define the metadata that are associated with a custom type. To define a property, you need to specify the `name` and `type` of the property. Property names cannot contain the following special characters: `/ \ : [ ] % * ' " |`

You can also assign a `label` to a property. The `label` can contain any character and is used to display the property in the user interface. The `type` of the property must be defined as one of the following: `Boolean`, `Date`, `Double`, `Long`, `Reference` or `String`. The `Boolean` type is used for properties whose value can be either `true` or `false`. `Date` is used for dates. `Double` is used for real numbers and `Long` for integers. `Reference` can be used for properties whose values reference another object in EKM. For example, a simulation file can have a reference property called `geomFile` that is a reference to a geometry file used in a simulation. `String` can be used to define strings.

Properties have the following optional attributes:

- `specifiedBy`: The valid values are `user` and `extractor`. If `extractor` is specified, then the value for this property will be automatically extracted using a metadata extractor application. If `user` is specified, then the value for this property will be manually entered by the user. If this attribute is not given, its value is assumed to be `user`. Only properties whose `specifiedBy` attribute is set to `user` can be modified by a user in the Edit Properties dialog box in the EKM user interface.

- `label`: The label used for the property in the interface. If not specified, the property `name` will be used.

- `multivalued`: The valid values for this attribute are `true` or `false`. If the value is `true`, then the value for the property can be a list of values instead of a single value. If this attribute is not specified, its value is assumed to be `false`.

  Note: If a date is defined as having a multi-valued property, dates are input separated by commas:

      1/12/1953 3:32 AM, 3/23/1996 12:00 AM

  If a single date is input with an internal comma, an error is generated. This is an example of a date format that is incorrect for a multi-valued field:

      Feb. 12, 2013 11:08

- `required`: The valid values for this attribute are `true` or `false`. This attribute is used only when the value for the `specifiedBy` attribute is set to `user`. If the value is `true` then the user will be prompted to enter a value for this property whenever an object of the type containing this property is created. For example, if you define metadata for a new file format with the `specifiedBy` attribute set to user and the required attribute set to `true`, then whenever a file of that format is uploaded, users will be asked to enter values for all the user-defined properties. If the value is `false`, then users will not be prompted to enter values when the object is created or the file is uploaded. However, values can still be modified in the user interface using the Edit Properties dialog box. If this attribute is not specified, its value is assumed to be `false`.

- `category`: Set the value of this attribute to `Hidden Properties` to specify that the property will not appear in the properties display when a user is viewing or editing object properties (on the Details tab or in the Edit Properties dialog box). This means that users cannot specify the property's value, even if the `disableDataExtraction` attribute is set to `false`.

- `displayOrder`: This value is set when you want the property to appear in a particular order in the Properties display or in a dialog box when user input is required. Dialog boxes include: Edit Properties, Edit Type, New Folder, and New Object. This value can be any valid integer. Properties with lower order are displayed first. If unspecified, the default value is `0`, which will display the property alphabetically by name.

Properties can also have the following child elements:

- `defaultValue`: This element is used for specifying the default value for the property. For multi-valued properties you can specify more than one default value. If you specify a default value you will need to ensure that the value is correctly specified for the property type.

  - `Boolean` types can only have `true` or `false` as valid values. If unspecified, the default value is `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` type values can be any valid real number.

    Examples: `0.0`, `123.456`

    You can also use scientific notation such as `1.235E6` or `1.235E-6`. If unspecified, the default value is `0.0`.

    Note: `Double` type is referred to as “`Real Number`” in the Custom Type dialog in EKM.

  - `Long` types can contain only numbers such as `0`, `5`, `-5` and so on as values. If unspecified the default value is `0`.

    Note: `Long` type is referred to as “`Integer`” in the Custom Type dialog in EKM.

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

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

    If unspecified, the default value is an empty string `“”`, which denotes a null reference.

  - `String` can have any arbitrary text as the value. If unspecified, the default value is an empty string `“”`.

- `enumeration`: Sometimes you may want users to choose a property value from a list of options. These options can be specified as an `enumeration` (that is, an enumerated list) for the property. You can specify an enumeration for any property type (`Double`, `Integer`, `String`, and so on) except `Boolean`. While specifying enumerations, follow the value syntax for the various property types that were described above.

- `constraint`: This element can be used to put constraints on property values. Constraints are validated when a user provides property values, and a validation error message is generated if a constraint is violated. A constraint element has a `name` and a `value` attribute. The constraint `name` must be one of the following:

  - `min`: Used for specifying the minimum value for a `Double` or `Long` type. The value for this `constraint` denotes the minimum value for the property.

  - `max`: Used for specifying the maximum value for a `Double` or `Long` type. The value for this `constraint` denotes the maximum value for the property.

  - `quantity`: 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 Units: Defining and Configuring Using XML for more details on specifying units.

  - `unit`: 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`, 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 Units: Defining and Configuring Using XML for more details on specifying units.

  - `baseType`: Used for specifying 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 this constraint to ensure that a reference always points to an object of type `File`.

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

#### Examples - Property Definitions

This section contains five examples of property definitions in EKM.

- `version`

- `dimension`

- `revisionStatus`

- `physicalModels`

- `inputFile`

Example 7.1: version Property defines a property named `version` of type `String`. Because the `specifiedBy` value is `extractor`, this property will be extracted from the file by the metadata extraction application. Because a `label` is specified, the property will appear in the user interface as Version.

Example 7.1: version Property

    <property name="version" type="String" specifiedBy="extractor" label="Version" />

Example 7.2: dimension Property defines a property named `dimension` of type `Double`. Because the `specifiedBy` attribute is not specified, it is assumed that the value will be specified by the user. Because the `required` attribute is set to `true`, users will be prompted to enter the value for this property when they create the object or upload a file containing this property. A default value of `15.0` is also specified. This property also has `min` and `max` constraints specified. This means that the value for this property should be between the specified range of `10.0` and `20.0`.

Example 7.2: dimension Property

    <property name="dimension" type="Double" required="true">
           <defaultValue>15.0</defaultValue>
           <constraint name="min" value="10.0" />
           <constraint name="max" value="20.0" />
    </property>

Example 7.3: revisionStatus Property defines a property named `revisionStatus` of type `String` that will appear in the user interface as Revision Status. It is a required property that will be specified by users. This property also has `enumerations` specified, so users can select only one of these values: `Draft`, `Released` or `Obsolete`. This property will appear in dialog boxes as a select menu (or drop-down list).

Example 7.3: revisionStatus Property

    <property name="revisionStatus" label="Revision Status" type="String" required="true">
            <enumeration>Draft</enumeration>
            <enumeration>Released</enumeration>
            <enumeration>Obsolete</enumeration>
    </property>

Example 7.4: physicalModels Property defines a property named `physicalModels` of type `String` that will appear in the user interface as Physical Models. The property value will be automatically extracted. Because the `multivalued` attribute is set to `true`, the property can accept more than one value. `Enumerations` are specified, and the values must be equal to one of the enumerations.

Example 7.4: physicalModels Property

    <property name="physicalModels" label="Physical Models" type="String"
    specifiedBy="extractor" multivalued="true">
           <enumeration>Stress</enumeration>
           <enumeration>Thermal</enumeration>
           <enumeration>Vibration</enumeration>
           <enumeration>Magnetostatic</enumeration>
    </property>

Example 7.5: inputFile Property defines a property named `inputFile` of type `Reference`. It is a `required` property that will be specified by the users. Because the `baseType` `constraint` is specified, the referenced object should be of the same type (or a subtype) of `CaeModelFile`.

Example 7.5: inputFile Property

    <property name="inputFile" type="Reference" required="true">
            <constraint name="baseType" value="CaeModelFile" />
    </property>

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.