The properties element

The properties element is a container for property elements, which define the user interface of the plug-in step.

Each plug-in step has a properties element. A properties element can contain any number of property child elements.

Additionally, property elements can be grouped under property-group elements. The property-group element can be used for mapping. The property-group element supports these attributes:
  • name
  • title
  • description
  • type
The type attribute must be set to mappingBox.
A <property> tag has a mandatory name attribute and a child property-ui element, which is defined in the following table. A property tag can also have an optional depends attribute, which identifies when a field depends on the values of other fields. If a field depends on the values of other fields, the field is not displayed until all the prerequisite fields are set. For example, the following text shows a depends attribute:
depends="oslcSecret,oslcKey,oslcUrl"
Table 1. The <property> element
<property> Child elements Description
<property-ui> Defines how the property is presented to users in IBM® UrbanCode™ Release. This element has several attributes:

  • label

    Identifies the property.

  • description

    Text that is displayed to users in the associated hover help box.

  • default-value

    Default property value.

  • type

    Identifies the type of widget that is displayed to users. Possible values include the following types:

    • textBox

      Enables users to enter an arbitrary amount of text, limited to 4064 characters.

    • textAreaBox

      Enables users to enter an arbitrary amount of text (larger input area than textBox), limited to 4064 characters.

    • secureBox

      Used for passwords. The behavior is similar to textBox except that values are redacted.

    • checkBox

      Displays a check box. If selected, a value of true is used; otherwise, the property is not set.

    • checkedMultiSelectBox

      Requires a list of one or more values, which are displayed in a list.

    • button

      Displays a push button.

    • httpSelectBox

      Displays a list of options, which are retrieved from an external URL or IBM UrbanCode Release REST endpoint. This type requires an http-prop-info element in the same property element. More information on the http-prop-info element is available in the following section.

    • httpMultiSelectBox

      Displays a list of options, which are retrieved from an external URL or IBM UrbanCode Release REST endpoint. This type requires a http-prop-info element in the same property element. More information on the http-prop-info element is available in the following section.

    • httpCheckedMultiSelectBox

      Displays a list of options, which are retrieved from an external URL or IBM UrbanCode Release REST endpoint. This type requires an http-prop-info element in the same property element. More information on the http-prop-info element is available in the following section. This element can be used only as part of a group.

    • scriptedSelectBox

      Displays a list of options that are retrieved from a step that is defined in the same plugin.xml file.

    • scriptedCheckedMultiSelectBox

      Displays a list of options that are retrieved from a step that is defined in the same plugin.xml file.

    • paragraph

      Displays text in the user interface.
<value> Used to specify values for a checkedMultiSelectBox type. Each value has a mandatory label attribute, which is displayed to users, and a value that is used by the property when it is selected. Values are displayed in the order that they are defined.

A sample <property> definition follows:

<property name="oslcUrl" >
        <property-ui type="textBox" label="OSLC server URL"  description="An OSLC server URL" />
    </property>

A sample <property-group> definition follows. The parent attributes of the child properties must match the name attribute of the parent <property-group> element.

<property-group depends="oslcUrl,oslcKey,oslcSecret,projectArea,query" name="mappingRelease" title="Release Mapping" description="Select a release and planned-for items" type="mappingBox" >
            <property parent="mappingRelease" name="timelines">
                <property-ui description="Timelines from Rational Team Concert"  label="Timelines" type="scriptedCheckedMultiSelectBox"/>            
                <scripted-prop-info source="Timelines" labelPath="label" valuePath="value" basePath="" dataFormat="JSON" dataSourceType="COMMAND" />
            </property>
            <property parent="mappingRelease" name="releases">
                <property-ui description="UrbanCode Releases"  label="Releases" type="httpCheckedMultiSelectBox"/>
                <http-prop-info username="${releaseUser}" password="${releasePassword}" url="${releaseUrl}/releases?format=list" labelPath="name" valuePath="id" basePath="" dataFormat="JSON" />
            </property>
        </property-group>

The http-prop-info element

The http-prop-info element defines the information that is required to connect to the REST endpoint and to parse the response in order to build the list of options. For example, the following text is a sample http-prop-info element: 
<http-prop-info username="${oslcKey}" password="${oslcSecret}"
        url="${oslcUrl}oslc/types/${projectArea}" labelPath="dc:title" valuePath="dc:title"
        basePath="/oslc_cm:Collection/rtc_cm:Type" dataFormat="XML" authType="OAUTH" />

The user name and password are required for authentication with the REST endpoint. The URL is the address of the REST endpoint. The authType can be BASIC, which is the default type, or OAUTH. The basepath attribute is used to determine the list of values in the XML or JSON response. For XML responses, use an XPath string; for example, //xml/node. For JSON responses, use a dot-notation path to an array that contains each element; for example, json.nodes.