Hi Everybody today I'm going to explain How to write an RXT from scratch and new features we have included in GReg 5.2.0 RXTs. This article will help you to write an RXT from scratch and modify the out of the box RXTs for your needs. You can find the full RXT I'm explaining below from here. In the end of the document, I will explain how to upload this rxt to WSO2 GReg.
For this example, I will be creating an rxt fields using actual use-case. First, let's defined the header of the rxt. For that, I'm using following parameters.
mediaType : application/vnd.dp-restservice+xml
shortName : dprestservice
<artifactType type="application/vnd.dp-restservice+xml" shortName="dprestservice" singularLabel="DP REST Service" pluralLabel="DP REST Services" hasNamespace="false" iconSet="20">
We can name type(mediaType) and shartName as the most important parameters. therefore please keep those in mind all the time. You can't change shortName once you defined it(saved the artifact type) but you can change this by reapplying the whole rxt with the new shartName. You can change mediaType later on but we are not recommending it since there is a risk of loosing all the assets If you want to change the mediaType you have to change the mideaType for all the assets that already in the GReg.
Next big thing is to create the storage path. This path is used to store the metadata type rxt. In the example, I'm using /trunk/dprestservices/@{overview_version}/@{overview_name} to store the assets creating using this rxt. @ denotes the dynamic data that users going to input. aoverview is a table name that we are going to include name and version data of all the asset that will create using DP REST service.
<storagePath>/trunk/dprestservices/@{overview_version}/@{overview_name}</storagePath>
For example if we create a asset using overview_name=testdp and overview_version=1.0.0 then the storage path for that asset would be /trunk/dprestservices/1.0.0/testdp. The name attribute is specially used to denote asset name.
<nameAttribute>overview_name</nameAttribute>
likewise you can add namespaceAttribute to denote the namespace if and only you uses namespace,
<namespaceAttribute>overview_namespace</namespaceAttribute>
Defining nameAttribute and namespaceAttribute is not necessary if your using something other than default rxt table values. Default rxt table values will be overview_name and overview_namespace.
If you want to attach a lifecycle in the asset creation you have to add below tag with the lifecycle name. for this example, I'm using ServiceLifeCycle which is also available out of the box with GReg 5.2.0.
<lifecycle>ServiceLifeCycle</lifecycle>
Now we are done with the upper section of the rxt definition. Let's start creating the asset listing page. This section is specially created to list the assets in management console(https://localhost:9443/carbon). Creating the listing page is straight forward. If you want to display name and version in the list page simply add below lines,
<ui>
<list>
<column name="Name">
<data type="path" value="overview_name" href="@{storagePath}"/>
</column>
<column name="Version">
<data type="path" value="overview_version" href="/trunk/dprestservices/@{overview_version}"/>
</column>
</list>
</ui>
There are two types of data which are path and text. path is a clickable hyperlink, It will direct you to the point which is mentioned by href and text is not clickable, it will just be a label. As per the above example if you click on the name you will be directed to metadata file, If you click on the version you will be directed to the collection(directory). Let's add an another column call namespace and set the type as text.
<column name="Service Namespace">
<data type="text" value="overview_namespace"/>
</column>
Add above tag somewhere within the list tag.
Well now we have come half way through and its time to create the form to get the user data. Let's start with the overview table.
The overview is the table name that we have used in this example to store name, version, and namespace(additional). Likewise, you can use any table name that you preferred. However, if you're using something other than overview we recommended you to create publisher and store extension accordingly. I will be creating another article on this in the near future.
Let's create the content
<content>
<table name="Overview">
<field type="text" required="true" readonly="true">
<name label="Name">name</name>
</field>
<field type="text" required="true" validate="\/[A-Za-z0-9]*">
<name>context</name>
</field>
<field type="text" url="true">
<name label="URL">url</name>
</field>
<field type="text" required="true" default="1.0.0">
<name label="version">version</name>
</field>
</table>
</content>
let's start from the simplest explanation and move to the more complex once later.
Firstly talk about default attribute, This attribute initialized the values for a specific field with the given value. In this example, version field will get the initial value of 1.0.0 which editable any time.
The value defined in name tag is the reference name of a specific field. The user has to omit spaces is this value and use of camel case is preferred. In WSO2 GReg reference name is created using concatenation of table name and value in name tag, Therefore reference names for above 3 fields will be overview_name, overview_context and overview_version.
Validate attribute is an inline regex validation for the field, in this case, it is context. Likewise, you can add any regex you want.
the label name is the display name for the field. Therefore the user can use any kind of characters and sentences in here.
readonly means once you save it for the first time users are not allowed to change it.
Make the field a mandatory or not.
There are 6 different field types available in GReg 5.2.0, Kindly find all the types with an example.
type="text"
type="options"
<field type="options">
<name label="Transport Protocols">transportProtocols</name>
<values>
<value>None</value>
<value>HTTPS</value>
<value>HTTP</value>
<value>SMTP</value>
<value>TCP</value>
<value>XMPP</value>
<value>JMS</value>
<value>SFTP</value>
<value>ODBC</value>
</values>
</field>
type="text-area"
<field type="text-area">
<name>Description</name>
</field>
type="checkbox"
<field type="checkbox">
<name label="BasicAuth">BasicAuth</name>
</field>
type="date"
<field type="date">
<name label="From Date">FromDate</name>
</field>
type="option-text"
<subheading>
<heading>Contact Type</heading>
<heading>Contact Name/Organization Name/Email Address</heading>
</subheading>
<field type="option-text" maxoccurs="unbounded">
<name label="Contact">Contact</name>
<values>
<value>None</value>
<value>Technical Owner</value>
<value>Technical Owner Email</value>
<value>Business Owner</value>
<value>Business Owner Email</value>
</values>
</field>
maxoccurs="unbounded" makes the field infinite. let's say if you want to make a set of different field types unbounded like this you can use this attribute in a table like below and achieve that task.
<table name="Doc Links" columns="3" maxoccurs="unbounded">
<subheading>
<heading>Document Type</heading>
<heading>URL</heading>
<heading>Comment</heading>
</subheading>
<field type="options">
<name label="Document Type">documentType</name>
<values>
<value>Unknown</value>
<value>Development</value>
<value>Testing</value>
<value>QA</value>
<value>Staging</value>
<value>Production</value>
</values>
</field>
<field type="text" url="true" validate="(https?:\/\/([-\w\.]+)+(:\d+)?(\/([\w/_\.]*(\?\S+)?)?)?)">
<name label="URL">url</name>
</field>
<field type="text-area">
<name label="Document Comment">documentComment</name>
</field>
</table>
How to load dynamic content to a filed.
<field type="options" >
<name label="WADL">wadl</name>
<values class="org.wso2.sample.rxt.WSDLPopulator"/>
</field>
For that please refer this blog post.
To deploy this in GReg please follow below steps.
5. Finally as per a best practice make sure to upload dprestservice.rxt to <GREG_HOME>/repository/resources/rxts/ directory as well.
Please add a comment if you have any clarifications regarding this.
For this example, I will be creating an rxt fields using actual use-case. First, let's defined the header of the rxt. For that, I'm using following parameters.
mediaType : application/vnd.dp-restservice+xml
shortName : dprestservice
<artifactType type="application/vnd.dp-restservice+xml" shortName="dprestservice" singularLabel="DP REST Service" pluralLabel="DP REST Services" hasNamespace="false" iconSet="20">
- 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).
- shortName - Short name for the artifact
- 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
We can name type(mediaType) and shartName as the most important parameters. therefore please keep those in mind all the time. You can't change shortName once you defined it(saved the artifact type) but you can change this by reapplying the whole rxt with the new shartName. You can change mediaType later on but we are not recommending it since there is a risk of loosing all the assets If you want to change the mediaType you have to change the mideaType for all the assets that already in the GReg.
Next big thing is to create the storage path. This path is used to store the metadata type rxt. In the example, I'm using /trunk/dprestservices/@{overview_version}/@{overview_name} to store the assets creating using this rxt. @ denotes the dynamic data that users going to input. aoverview is a table name that we are going to include name and version data of all the asset that will create using DP REST service.
<storagePath>/trunk/dprestservices/@{overview_version}/@{overview_name}</storagePath>
For example if we create a asset using overview_name=testdp and overview_version=1.0.0 then the storage path for that asset would be /trunk/dprestservices/1.0.0/testdp. The name attribute is specially used to denote asset name.
<nameAttribute>overview_name</nameAttribute>
likewise you can add namespaceAttribute to denote the namespace if and only you uses namespace,
<namespaceAttribute>overview_namespace</namespaceAttribute>
Defining nameAttribute and namespaceAttribute is not necessary if your using something other than default rxt table values. Default rxt table values will be overview_name and overview_namespace.
If you want to attach a lifecycle in the asset creation you have to add below tag with the lifecycle name. for this example, I'm using ServiceLifeCycle which is also available out of the box with GReg 5.2.0.
<lifecycle>ServiceLifeCycle</lifecycle>
Now we are done with the upper section of the rxt definition. Let's start creating the asset listing page. This section is specially created to list the assets in management console(https://localhost:9443/carbon). Creating the listing page is straight forward. If you want to display name and version in the list page simply add below lines,
<ui>
<list>
<column name="Name">
<data type="path" value="overview_name" href="@{storagePath}"/>
</column>
<column name="Version">
<data type="path" value="overview_version" href="/trunk/dprestservices/@{overview_version}"/>
</column>
</list>
</ui>
There are two types of data which are path and text. path is a clickable hyperlink, It will direct you to the point which is mentioned by href and text is not clickable, it will just be a label. As per the above example if you click on the name you will be directed to metadata file, If you click on the version you will be directed to the collection(directory). Let's add an another column call namespace and set the type as text.
<column name="Service Namespace">
<data type="text" value="overview_namespace"/>
</column>
Add above tag somewhere within the list tag.
Well now we have come half way through and its time to create the form to get the user data. Let's start with the overview table.
The overview is the table name that we have used in this example to store name, version, and namespace(additional). Likewise, you can use any table name that you preferred. However, if you're using something other than overview we recommended you to create publisher and store extension accordingly. I will be creating another article on this in the near future.
Let's create the content
<content>
<table name="Overview">
<field type="text" required="true" readonly="true">
<name label="Name">name</name>
</field>
<field type="text" required="true" validate="\/[A-Za-z0-9]*">
<name>context</name>
</field>
<field type="text" url="true">
<name label="URL">url</name>
</field>
<field type="text" required="true" default="1.0.0">
<name label="version">version</name>
</field>
</table>
</content>
let's start from the simplest explanation and move to the more complex once later.
- default="1.0.0"
Firstly talk about default attribute, This attribute initialized the values for a specific field with the given value. In this example, version field will get the initial value of 1.0.0 which editable any time.
- url="true"
This will wrap it as a clickable link. Users can link another asset simply by storing asset ID. Paste below bolted value of another asset and users can make simple links.
Example : https://localhost:9443/publisher/assets/dprestservice/details/50631a7c-646e-4156-88af-dad46be2f428
- <name>context</name>
The value defined in name tag is the reference name of a specific field. The user has to omit spaces is this value and use of camel case is preferred. In WSO2 GReg reference name is created using concatenation of table name and value in name tag, Therefore reference names for above 3 fields will be overview_name, overview_context and overview_version.
- validate="\/[A-Za-z0-9]*"
Validate attribute is an inline regex validation for the field, in this case, it is context. Likewise, you can add any regex you want.
- label="Name"
the label name is the display name for the field. Therefore the user can use any kind of characters and sentences in here.
- readonly="true"
readonly means once you save it for the first time users are not allowed to change it.
- required="true"
Make the field a mandatory or not.
- name="Overview"
This denotes the table name for set of fields inside of it.
- type
There are 6 different field types available in GReg 5.2.0, Kindly find all the types with an example.
type="text"
<field type="text" url="true">
<name label="URL">url</name>
</field>
<name label="URL">url</name>
</field>
type="options"
<field type="options">
<name label="Transport Protocols">transportProtocols</name>
<values>
<value>None</value>
<value>HTTPS</value>
<value>HTTP</value>
<value>SMTP</value>
<value>TCP</value>
<value>XMPP</value>
<value>JMS</value>
<value>SFTP</value>
<value>ODBC</value>
</values>
</field>
type="text-area"
<field type="text-area">
<name>Description</name>
</field>
type="checkbox"
<field type="checkbox">
<name label="BasicAuth">BasicAuth</name>
</field>
type="date"
<field type="date">
<name label="From Date">FromDate</name>
</field>
type="option-text"
<subheading>
<heading>Contact Type</heading>
<heading>Contact Name/Organization Name/Email Address</heading>
</subheading>
<field type="option-text" maxoccurs="unbounded">
<name label="Contact">Contact</name>
<values>
<value>None</value>
<value>Technical Owner</value>
<value>Technical Owner Email</value>
<value>Business Owner</value>
<value>Business Owner Email</value>
</values>
</field>
maxoccurs="unbounded" makes the field infinite. let's say if you want to make a set of different field types unbounded like this you can use this attribute in a table like below and achieve that task.
<table name="Doc Links" columns="3" maxoccurs="unbounded">
<subheading>
<heading>Document Type</heading>
<heading>URL</heading>
<heading>Comment</heading>
</subheading>
<field type="options">
<name label="Document Type">documentType</name>
<values>
<value>Unknown</value>
<value>Development</value>
<value>Testing</value>
<value>QA</value>
<value>Staging</value>
<value>Production</value>
</values>
</field>
<field type="text" url="true" validate="(https?:\/\/([-\w\.]+)+(:\d+)?(\/([\w/_\.]*(\?\S+)?)?)?)">
<name label="URL">url</name>
</field>
<field type="text-area">
<name label="Document Comment">documentComment</name>
</field>
</table>
How to load dynamic content to a filed.
<field type="options" >
<name label="WADL">wadl</name>
<values class="org.wso2.sample.rxt.WSDLPopulator"/>
</field>
For that please refer this blog post.
To deploy this in GReg please follow below steps.
1. Login to the carbon console: https://localhost:9443/carbon/
2 .Find Extensions from the left vertical bar and click it.
3. Click on add new extension.
5. Finally as per a best practice make sure to upload dprestservice.rxt to <GREG_HOME>/repository/resources/rxts/ directory as well.
Please add a comment if you have any clarifications regarding this.
Hello I tried to edit existing element soapservice and removed readonly atribute in name,namespace but I am unable to rename existing soap service. I tried even to create new one and still doesn't work, how can I do that - rename existing service?
ReplyDeleteThanks
Pavol