[Article] WSO2 Governance Registry: Governance Framework Extension Points

Contents

1. Introduction
2. Configurable governance artifacts
   • Model elements in configurable governance artifact
   • Adding configurable governance artifacts
   • Configurable artifact CRUD operations
3. Relationship between an artifact and its lifecycle
   • Lifecycle checkList
   • Lifecycle transition permission
   • Lifecycle transition tpproval
   • Lifecycle transition validator
   • Lifecycle transition executor
4. Summary

Introduction

Governance is central to an effective enterprise SOA. It transforms the business policies into metadata based rules and assists in automating the validation and enforcement of policy compliance in both design-time and runtime environments. By having the right governance model in place, we can can mitigate this risk and maximize business performance.

WSO2 Governance Registry (WSO2 GReg) is a fully open source product for governing SOA deployments, which provides many extension points to ensure your business policies. This article will discuss governance framework based extension points provided by WSO2 GReg.

Configurable governance artifacts

Configurable governance artifacts, also known as registry extension types (RXTs), are one of many well-defined extension points supported by the WSO2 GReg. It allows you to define your own metadata models, apart from the default one that is shipped with the product. This supports modeling any type of asset according to the user requirements.

When deploying configurable governance artifacts in WSO2 GReg, a web service that supports CRUD (create, retrieve, update, delete) operations is created. By using external web services, client application users can then consume them.

Model elements in configurable governance artifact

Below are the main elements in the RXT configuration:

• artifactType element
• artifactKey element
• storagePath element
• nameAttribute element
• namespaceAttribute element
• menu element
• ui element
• relationships element

Using the above basic model, you can create or modify RXTs based on your requirement. Let’s go through a sample RXT file and understand the requirements of each element. For an example, consider a scenario where we need to store user contact information. We will need to capture and store information such as first name, last name, birthday, address, organization, department, email address and mobile number among other things.

Below is an RXT representation that we can create to capture and store the above mentioned information;

  
<?xml version="1.0" encoding="UTF-8"?>
<artifactType type="application/vnd.wso2-contact+xml" shortName="contacts" singularLabel="Contact" pluralLabel="Contacts" hasNamespace="false" iconSet="9">
   <storagePath>/contacts/@{name}/@{overview_lastName}</storagePath>
   <nameAttribute>overview_name</nameAttribute>
   <ui>
  	<list>
     	<column name="First Name">
        	<data type="path" value="overview_name" href="/contacts/@{name}" />
     	</column>
     	<column name="Last Name">
        	<data type="path" value="overview_lastName" href="@{storagePath}" />
     	</column>
  	</list>
   </ui>
   <relationships>
  	<association type="isConsumedBy" source="@{assets_entry:value}" />
   </relationships>
   <content>
  	<table name="Overview">
     	<field type="text" required="true">
        	<name>Name</name>
     	</field>
     	<field type="text" required="true">
        	<name>LastName</name>
     	</field>
  	</table>
  	<table name="PersonalInformation">
     	<field type="text" required="true">
        	<name>Birth Day</name>
     	</field>
     	<field type="text-area" required="true">
        	<name>Address</name>
     	</field>
  	</table>
  	<table name="OtherInformation">
     	<field type="options" required="true">
        	<name>Department</name>
        	<values>
           	<value>Development</value>
           	<value>QA</value>
           	<value>TechContent</value>
        	</values>
     	</field>
     	<field type="text" required="true">
        	<name>Email</name>
     	</field>
     	<field type="text" required="true">
        	<name>Mobile</name>
     	</field>
  	</table>
   </content>
</artifactType>

Now let’s go through the main XML elements in the above sample.

artifactType element

The root element of the RXT configuration is artifactType. It has a few attributes that need to be defined. These include

• type - defines the media type of the artifact
• shortName - short name for the artifact
• singularLabel - singular label of the artifact: this is shown in the UI to display the link to add new artifacts
• pluralLabel - plural label of the artifact: this is used when listing artifacts
• hasNamespace - defines whether the artifact has a namespace (boolean)
• iconSet - icon set number is used for artifact icons (from 1 to 30)

storagePath element

This element is used to define the storage path of the artifact. Users can customize the storage path based on the information available. They can use some fixed attributes such as @{name}, @{namespace} and other attributes such as @{overview_version}. The name and namespace attributes need to be mapped using nameAttribute and namespaceAttribute.

nameAttribute element

This is the identifier for the name attribute used in storage path.

namespaceAttribute element

This is the identifier for the namespace attribute used in storage path.

lifecycle element

This element is used to define the default lifecycle of the given artifact. When creating an artifact, this lifecycle will be automatically assigned to resources.

ui element

This element is used to define the list view of the artifact. Using the UI element, the list view is automatically generated.

relationships element

Using the relationship element we can define the association between artifacts.

content element

This is the data model of the new artifact. With the information available in this element, the artifact add view will be automatically generated.

Adding configurable governance artifacts

For this, follow the steps on deploying an extension file here.

Configurable artifact CRUD operations

Once you have added an RXT, it will generate an HTML based list and add view. Also it will be deployed as an Axis2 based service with CRUD operations. For example, when you upload contact.rxt, there will be a contact service exposed with CRUD operations. Using the provided CRUD operations, external client applications (php, .net, etc) can perform registry operations.

Below is an example CRUD operation provided for contact RXT, which we previously created:

• addContact - create an artifact in the type Contact
• getContact - retrieve an artifact in the type Contact
• updateContact - update an artifact in the type Contact
• deleteContact - delete an artifact in the type Contact
• getContactArtifactIDs - get all the IDs of artifacts in the type Contact

To retrieve WSDL of the above service, we need to disable HideAdminServiceWSDLs in the carbon.xml file. After that, you need to restart the WSO2 GReg server. Then Contract (WSDL) will be exposed as shown in the service client example here

Relationship between an artifact and its lifecycle

Lifecycle management is focused on various state changes in a given artifact through different phases. This governance framework helps model, assemble, deploy and manage artifacts through different states. The lifecycle helps to build the flow of an artifact correctly and validate and enforce organizational requirements correctly. Further, it ensures continuous alignment and guidance of the artifacts. For example, when developing a service we can ensure availability of the documentation using a lifecycle. It also increases the manageability of artifacts. This lifecycle management is not limited to the services. It can be applied to APIs, documentation, contact, endpoint and so on.

For example, let’s consider a SOAP service. There can be different lifecycle states such as development, testing, staging, production and retired state to this service (the state can be changed based on your organization requirement and policies). Using the initial lifecycle state, we can capture basic information about the service such as ownership and implementation related details.

In WSO2 GReg, there are multiple extension points available. In each lifecycle state, information that needs to be captured and verified are different. Checklist, transition permission, transition approval, transition validator and transition executor are some of the governance points provided in WSO2 GReg.

Lifecycle checklist

Using checklists, we can gain more control over lifecycle states. It’s similar to a precondition check before the lifecycle is moved to the next state. Check items allow you to define a list of items and includes permissions for each check item (you can restrict actions for a set of roles) and custom validations.

Below is a sample checklist configuration. Each checklist item can have a forEvent that associates a lifecycle transition with a check item. For example, if the forEvent is set to Promote, this check item must be clicked in order to proceed with the promote operation for that state. Until the “Code Completed" check item is checked, the promote action will not be shown.

You can define a set of user roles in the checklist item stating who has permission to perform an action on that checklist. In the below sample, only users who are in wso2.eng and admin roles are allowed to check that item.

<data name="checkItems">
  <item name="Code Completed" forEvent="Promote">
    <permissions>
       <permission roles="wso2.eng,admin"/>
    </permissions>
    <!--<validations>
      <validation forEvent="" class="">
        <parameter name="" value=""/>
      </validation>
    </validations>-->
  </item>
  <item name="WSDL, Schema Created" forEvent="">
  </item>
  <item name="QoS Created" forEvent="">
  </item>
</data>

Lifecycle transition permission

This is where a role based permission model defines the lifecycle transition. For example, a lifecycle transition from staging to production is only allowed for users who are in the admin role.

<data name="transitionPermission">
    <permission forEvent="Promote" roles="admin"/>
    <permission forEvent="Demote" roles="admin"/>
</data>

Lifecycle transition approval

This is where a vote based approval process defines the lifecycle transitions. For example, in order to perform a lifecycle transition from testing to staging, we need to have three votes from users who are in the QA role.

<data name="transitionApproval">
  <approval forEvent="Promote" roles="QA" votes="3"/>
</data>

Lifecycle transition validator

Using the transitionValidation element users can define a custom validation logic for a lifecycle transition. For example, before promoting the service to the testing stage, certain information needs to be validated. That validation is done with the lifecycle transition validation. Note that this validation can be defined with checklist items as well.

The custom validator java class needs to implement the CustomValidations interface that is provided by WSO2 GReg. You can also find existing validators under governance registry extension components.

In your custom validator java class, two methods that are available in the CustomValidations interface need to be overridden. They are the init method and validate method. The init method is where parameters are defined. The validate method contains your custom validation related logic. In the example validation shown below, some RXT fields are taken and their values are validated before the lifecycle transition.

If the validate method returns false, it will break the lifecycle transition operation. If you want to show a custom error messages to the end user, the you need to throw GovernanceExceptions with the custom error message.

<validation forEvent="Promote" class="org.wso2.carbon.governance.registry.extensions.validators.AttributeExistenceValidator">
    <parameter name="attributes" value="overview_version,overview_description"/>
</validation>

Add a custom validator to a lifecycle

1. Compile the class and create a jar file out of it
2. If the jar file is an OSGI bundle add it to GREG_HOME/repository/components/dropins folder. If the jar file is not an OSGI bundle then add it to GREG_HOME/repository/components/lib folder. This adds the executor implementation to the classpath of the WSO2 GReg server
3. Add the executor to the lifecycle configuration. You need to update the lifecycle file with transitionValidation and define the class name as a fully qualified class name

Lifecycle transition executor

Using the transitionValidation element, users can perform custom actions when lifecycle transitions happen. For example, when one service is promoted into the production state you can create an API in WSO2 API Manager. You can also copy resources using this executor. Using this, you can basically perform any resource related operation when the lifecycle transition happens.

Custom executor java class needs to implement the Execution interface that is provided by WSO2 GReg. You can find existing executor implementations under the governance registry extension components.

When creating a custom executor, you need to override two methods available in the Execution interface. They are init method and execute method. The init method is where parameters are defined. The execute method contains your custom execution related logic.

In the sample scenario below, we will add a log message when the lifecycle transition happen. Here, a log message has been added inside the execute method. When the lifecycle transition happens we can see this log message.

You can write your own custom logic that needs to be invoked when the lifecycle transition happens. For example, you can create an API in WSO2 API Manager when a promotion happens and delete the API when a demotion happens.

Add a custom executor to a lifecycle

1. Compile the class and create a jar file
2. If the jar file is an OSGI bundle add it to GREG_HOME/repository/components/dropins folder. If the jar file is not an OSGI bundle then add it to GREG_HOME/repository/components/lib folder. This adds the executor implementation to the classpath of the GReg server
3. Add the executor to the lifecycle configuration

  <data name="transitionExecution">
    <execution forEvent="Promote" class="org.wso2.carbon.governance.registry.extensions.executors.ServiceVersionExecutor">
      <parameter name="attributes" value="InputValue"/>
    </execution>
  </data>

Summary

WSO2 Governance Registry provides many extension points that can be used to achieve custom requirements. Using these extension points, you can ensure that better governing principles are applied to resources when they follow your lifecycle process.

Sample Source: Link