Governance Artifacts Configuration Model Elements

Once you have learnt how to create a registry extension file and content, see the list of the Governance Artifacts main element descriptions below:

The table Element

This element defines a group of input fields. All input fields should be defined inside a table element. In the generated UI, each table element generates a corresponding HTML table segment.

<table name="Overview">
  <field type="text" required="true"> <name>Name</name> </field>
  <field type="text" required="true"> <name>Namespace</name> </field>
  <field type="text"> <name>Version</name> </field>
  <field type="text-area"> <name>Description</name> </field>
</table>

The generated HTML UI of the table element appears as follows.

This element has a mandatory attribute name which is displayed as the heading of the generated HTML table.

<table name="Overview"></table>

By default, a table has 2 (two) columns. However, a user can specify any number of columns using the columns attribute.

<table name="Doc Links" columns="3">

The subheading Element

This element specifies the headings for a table. Therefore, it is always a child element of a table element. The number of heading elements within a subheading element must equal the number of columns in the corresponding table.

<table name="Contacts">
  <subheading>
    <heading>Contact Type</heading> <heading>Contact Name/Organization Name</heading>
  </subheading>
</table>

OR

<table name="Doc Links" columns=3>
  <subheading>
    <heading>Document Type</heading> <heading>URL</heading> <heading>Comment</heading>
  </subheading>
</table>

In the above example, it can be seen that the column number is set to 3 (three). This creates 3 (three) columns, and subheadings are added as specified. If more than 2 (two) columns are used, a field name is not printed in front of the input field.

<table name="Doc Links" columns="3">
  <subheading> <heading>Document Type</heading> <heading>URL</heading> <heading>Comment</heading> </subheading>
  <field type="text"> <name>Document Type</name> </field> <field type="text"> <name>URL</name> </field> <field type="text-area"> <name>Document Comment</name> </field>
  <field type="text"> <name>Document Type1</name> </field> <field type="text"> <name>URL1</name> </field> <field type="text"> <name>Document Comment 1</name> </field>
</table>

The field Element

This element defines an input field. It can be a text field, drop-down list, text area, check-box, or an option-text.

The field element can have a couple of attributes, including a mandatory attribute type. The type attribute specifies the field type, which can be text, option, text-area, option-text, date or checkbox.

Some types of fields can have optional attributes. The text-area field accepts url as an optional attribute. Setting url="true" displays the text as a URL instead of as a plain text box.

The name Element as a child of field

In addition to having a mandatory type attribute, the field element should have another child element named name to specify the name and to display as the caption of the input field. Inside a single table element, the same name cannot be used for more than one field of the same type.

A field element to create a text field

<field type="text"> <name>Name</name> </field>

When the option or option-text type is used, the set of values to be included in the drop-down list must be specified. The values element is used for this purpose.

Definition of an "options" input field

<field type="options"> <name>states</name> <values> <value>Created</value> <value>Tested</value> <value>Deployed</value> <value>Deprecated</value> </values> </field>

Mandatory input fields can be declared by setting the mandatory attribute to true. The default value of this attribute is false if it is not specified in the field element. The HTML form shows an error message during submission if a mandatory field is not filled in.

The options field can be used to select a lifecycle for the artifact instance. This displays a list of the existing lifecycles, from which you can choose one that is associated with the instance. It is also possible to not associate a lifecycle for the artifact instance. This can be accomplished by adding the following field.

<field type="options">
     <name label="Lifecycle Name">lifecycle_name</name>
</field>

Declaring a mandatory field

<field type="text" required=true> <name>Name</name> </field>

Defining default values to a field

You can define a default value to a field to make it appear when creating the artifact in both the Management Console and Publisher. For this, add the default property to the corresponding <field> element in the RXT definition of the artifact as shown in the example below.

<field type="text" required="true" default="Soap Service">
<name label="Name">Name</name>
</field>

The maxoccurs Element

The maxoccurs element can be used in two different ways, i.e., it can define maxoccurs as attribute of table or option-text.

maxoccurs in table:

This feature is useful when there is a requirement to add multiple field types except option-text. Users are able to add those fields dynamically by clicking on the Add icon. 

Declaring maxoccurs="unbounded" table

<table name="Doc Links" columns="3"  maxoccurs="unbounded">
    <subheading>
        <heading>Document Type</heading>
        <heading>URL</heading>
        <heading>Comment</heading>
    </subheading>
    <field type="text">
        <name label="Document Type">Document Type</name>
    </field>
    <field type="text" url="true">
        <name label="URL">URL</name>
    </field>
    <field type="text-area">
        <name label="Document Comment">Document Comment</name>
   </field>
</table>

The following image depicts how the screen looks after saving information in an unbounded table.

maxoccurs in option-text field:

maxoccurs can be used only with the field type option-text. This feature is useful when there is a requirement to add a variable number of fields (option-text). Users are able to add those fields dynamically by clicking Add Link. When a particular option-text field is declared with maxoccurs=unbounded, a link is displayed to add new input fields as required.

Declaring maxoccurs="unbounded" option-text fields

<table name="EndPoints">
<subheading> <heading>Environments</heading> <heading>URL</heading> </subheading>
<field type="option-text" maxoccurs="unbounded"> <name>EndPoint</name> <values> <value>Unknown</value> <value>Dev</value> <value>QA</value> <value>Test</value> </values> </field>
</table>

With this configuration, the following link is initially displayed in the UI.

Users can click on the "Add Endpoint" link and add the required number of endpoints. The sub-headers are printed after the "Add Endpoint" link. When more than two sub-headers are specified, the maxoccurs attribute cannot be set to unbounded.

This attribute also enables you to store multiple entries under the same field.

    <field maxoccurs="unbounded" type="option-text">
     <name label="Contact">Contact</name>
     <values>
      <value>Titans</value><value>Legions</value><value>Cloud Bots</value><value>Wild Boars</value>
     </values>
    </field>

The following image depicts how the screen looks after saving multiple values.

Since the maximum occurrence is unbounded, it can keep unlimited entries. If you want to limit the number of entries, you can define maxoccurs for the bounded value.

The artifactType Element

<artifactType hasNamespace="false" iconset="9" pluralLabel="Events" shortName="events"
singularLabel="Event" type="application/vnd.wso2-events+xml">
    </artifactType>

This is the root element of the new artifact which is being defined. It has several attributes:

• type - Defines the media type of the artifact. The type format should be application/vnd.[SOMENAME]+xml. SOMENAME can contain any alphanumeric character, "-" (hyphen), or "." (period).

   Use the following pattern when defining the media type of custom RXTs: application/[a-zA-Z0-9.+-]+

• shortName - Short name of the artifact. Only lower case characters are allowed in the short name. This value cannot be modified once the RXT is added into the WSO2 Governance Registry.
• singularLabel - Singular label of the artifact
• pluralLabel - Plural label of the artifact
• hasNamespace - Defines whether the artifact has a namespace (boolean)
• iconSet - Icon set number used for the artifact icons

The artifactKey Element

<artifactKey>event</artifactKey>

This element defines the unique key which can be used to identify the artifact. This key is used when fetching configurations and loading customized UIs.

The storagePath Element

<storagePath>/consumers/@{namespace}/@{name} </storagePath>

This is the path where the instance data of the artifact is stored. When you evaluate this expression, it automatically replaces @{name} with the name of the artifact and @{namespace} with the namespace of the artifact. In addition to the name and namespace, you can also specify any other attribute in the format @{ATTRIBUTE_NAME}, e.g., /trunk/processes/@{business_domain}/@{overview_version}.

<storagePath>/gadgets/@
{overview_provider}
/@
{overview_name}
/@
{overview_version}
</storagePath>

...............
<content>
<table name="Overview">
<field type="text" required="true">
<name>Provider</name>
</field>
<field type="text" required="true" validate="^([a-zA-Z0-9_\s\-]*)$">
<name>Name</name>
</field>
........................

<field type="text" required="true" readonly="true">
<name>Provider</name>
</field>
<field type="text" required="true" readonly="true" validate="^([a-zA-Z0-9_\s\-]*)$">
<name>Name</name>
</field>

The nameAttribute Element

<nameAttribute>details_name</nameAttribute>

This is the main element which defines the name of the artifact. It must have the following format:

{$table}_{$base-column}

The namespaceAttribute Element

<namespaceAttribute>http://www.wso2.com/rxt/event </namespaceAttribute>

This element defines the namespace of the artifact. Some types of artifacts do not need a namespace, and therefore, this element is optional. Namespaces are found in artifacts related to Web Services, but they are not common to others, such as Policy and SLA.

The lifecycle Element

<lifecycle>ServiceLifeCycle</lifecycle>

This optional element defines the default lifecycle name of the artifact type. If the lifecycle element is defined with a lifecycle name which is in the registry, the lifecycle is automatically associated to the artifact during artifact creation. 

The ui Element

    <ui>
        <list>
            <column name="Name">
                <data href="/processes/@%7Bname%7D" type="path" value="overview_name"/>
            </column>
            <column name="Version">
                <data href="@%7BstoragePath%7D" type="path" value="overview_version"/>
            </column>
        </list>
    </ui>

This element defines the view of the data instances when browsing for that data type. It can include the list of data types which are in the content of the artifact. This element has a sub-element list which can include one or more columns. These columns appear on the List page of the corresponding artifact. Columns must have a name. The content of each column is defined by the data element which has three main types of attributes

• type - The type of data displayed, which is one of text or path. A path corresponds to a registry path.
• href - The hyperlink to which the path points to.
• value - The value displayed on the UI either as plain text or as a clickable link, depending on the type.

The relationships Element

<relationships>
        <association source="@{assets_entry:value}" type="isConsumedBy"/>
        <association source="@{partners_entry:value}" type="uses"/>
        <association target="@{partners_entry:value}" type="usedBy"/>
</relationships>

The <relationships> element defines the relationships between the newly created artifact and other artifacts. We can find three types here.

• isConsumedBy - Artifact which consumes the newly created artifact
• uses - Artifact which uses the newly created artifact
• usedBy - Artifact used by the newly created artifact

The content Element

    <content>
        <table name="Details">
            <field required="true" type="text">
                <name>Name</name>
            </field>
            <field required="true" type="text">
                <name>Date</name>
            </field>
            <field required="true" type="text">
                <name>Venue</name>
            </field>
        </table>
        <table name="Rules">
            <field type="options">
                <name>Gender</name>
                <values>
                    <value>male</value>
                    <value>female</value>
                </values>
            </field>
            <field type="text-area">
                <name>Description</name>
            </field>
            <field type="text" path="true" startsWith="/_system/governance/trunk/people">
                <name>Auther</name>
            </field>
        </table>
        <table name="Participants">
            <subheading>
                <heading>House</heading><heading>Name</heading>
            </subheading>
            <field maxoccurs="unbounded" type="option-text">
                <name label="Contact">Contact</name>
                <values>
                    <value>Titans</value><value>Legions</value><value>Cloud Bots</value><value>Wild Boars</value>
                </values>
            </field>
        </table>
        <table name="Service Lifecycle">
            <field type="options">
                <name label="Lifecycle Name">Lifecycle Name</name>
                <values class="org.wso2.carbon.governance.services.ui.utils.LifecycleListPopulator">
            </values></field>
        </table>
        <table name="SLA" columns="3">
            <subheading>
                <heading>Document Type</heading><heading>URL</heading><heading>Comment</heading>
            </subheading>
            <field path="true" type="text" url="true">
                <name>SLA</name>
            </field>
            <field path="true" type="text" url="true">
                <name>SLA1</name>
            </field>
            <field path="true" type="text" url="true">
                <name>SLA2</name>
            </field>
        </table>
    </content>

This element defines the data model of the new artifact. It is also used to auto-generate the UI of instantiate artifacts.

The text Element

Defines a text field.

<field type="text">
     <name>Name</name>
    </field>

The path, url and startsWith Attributes

    <field path="true" type="text" url="true" startsWith="/_system/governance/trunk/venues">
     <name>Venue</name>
    </field>

• The path attribute is set when the input is expected to be a path. Enabling this attribute also gives you the option of browsing within the repository. You can type the path as well.
• The url attribute is set when the input is expected to be a URL.
• The startsWith attribute is a optional attribute coupled with the path attribute which describes the registry collection you should start browsing for a path. If you do not declare this attribute, browsing starts with the registry root collection.

The readonly Attribute

    <field type="text" readonly="true">
     <name>Date</name>
    </field>

• The readonly attribute is set when users are not expected to change the value of a text (or text-area) field once an artifact has already been created.

The text-area Value of the type Attribute

Defines a text area field.

    <field type="text-area">
     <name>Description</name>
    </field>

The date Value of the type Attribute

Defines a date field and it validates given input for a date. 

    <field type="date">
     <name>From Date</name>
    </field>

The options Value of the type Attribute

Defines a field with a combo-box containing the given values.

    <field type="options">
     <name>Gender</name>
     <values>
      <value>male</value>
      <value>female</value>
     </values>
    </field>

The option-text Value of the type Attribute

Defines a composite field with an options field and a text field. Values of the options field need to be defined as child elements of the field.

    <field type="option-text">
     <name label="Contact">Contact</name>
     <values>
      <value>Titans</value><value>Legions</value><value>Cloud Bots</value><value>Wild Boars</value>
     </values>
    </field>

Multi-type Attributes

required Attribute

The required attribute makes a field required in order to create an artifact instance. Here, the required attribute is used for text type, but it can be used with other types also. Required fields are indicated using a red star in the UI configuration.

    <field required="true" type="text">
     <name>Name</name>
    </field>

validate Attribute

The validate attribute can be used to give a regular expression to validate the user input with any field except checkboxes. 

    <field type="text" validate="^\d+$">
     <name>Age</name>
    </field>

Note: If you want to have characters like '<' in regular expression you have to put corresponding XML codes like &lt; as RXT configuration is an XML document

tooltip Attribute

The tooltip attribute can be used to enable a tooltip to be shown with any type of field. 

<field type="text" tooltip="Employee's age goes here"> <name>Age</name></field>

Table Attributes Columns Attribute

The columns attribute is used to set the number of fields in each row. The following fields are put into the table in the order of their appearance. The number of heading child elements in the subheading element needs to be the same as the number of columns. 

<table name="External Links" columns="3"> 
	<subheading>
 		<heading>Document Type</heading><heading>URL</heading><heading>Comment</heading>
    </subheading> 
		<field type="text" url="true">
 			<name>URL</name>
   		</field> 
		<field type="text" url="true"> 				
			<name>URL1</name>
     	</field> 
		<field type="text" url="true">
 			<name>URL2</name>
     	</field>
</table>

Also see Configuring Service Template to learn how to deal with Governance Artifacts using UI.