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:

Following configurations are only valid for generic RXTs and not for the content RXTs such as WSDL, WADL, XSD, Policy etc.

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.

The subheading element is not mandatory inside a table element.

<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 option-text field contains a drop-down list with a text field.

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>

The label is the text that appears on the browser UI, whereas the name is the actual name of what is being stored on the repository, in XML format.
The label is optional. If it is not defined, the name is used instead.

The label can have characters such as spaces, parentheses, uppercase letters etc. whereas the name cannot have those.

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.

This does not support defining required fields and regular expression-based validations.

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}.

You cannot have the (~!@#;%^*()+={}|\<>"',) characters in the value of the unique fields that are defined in the storagePath element in the RXT. Hence, you need to add a validation for the field definitions of those fields. For example, consider the following storage path.

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

The validations required for the following storage path are as follows:

...............
<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>
........................

When choosing attributes for the storagePath of an RXT, choose attributes, which have unique and static values. Also, mark those fields as read-only since you should not change the values of them after creating the asset.

Example:

<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 < 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.

Governance Artifacts Configuration Model Elements

The table Element

The subheading Element

The field Element

The name Element as a child of field

A field element to create a text field

Definition of an "options" input field

Declaring a mandatory field

Defining default values to a field

The maxoccurs Element

maxoccurs in table:

Declaring maxoccurs="unbounded" option-text fields

The artifactType Element

The artifactKey Element

The storagePath Element

The nameAttribute Element

The namespaceAttribute Element

The lifecycle Element

The ui Element

The relationships Element

The content Element

The text Element

The path, url and startsWith Attributes

The readonly Attribute

The text-area Value of the type Attribute

The date Value of the type Attribute

The options Value of the type Attribute

The option-text Value of the type Attribute