Implementing SOA Governance Using WSO2 Governance Registry


Introduction

In this blog, I’ll briefly describe what SOA Governance is and list the features of a SOA governance toolset. Then, I’ll provide a tutorial on several of the design-time, governance capabilities of WSO2 Governance Registry, a freely available, open source governance toolset.

What is SOA Governance?

SOA governance builds upon IT governance and aims to provide a framework and model to manage SOA applications in relation to managing service lifecycles.

There are three stages of SOA governance:

  • Design-time governance – provides rules and policies for creating, exposing, and consuming services
  • Change-time governance – details how organizations can effect changes in the overall system with the least disruption to the existing business and its policies
  • Run-time governance – governs the behavior of services in production and the performance of the architecture as a whole

SOA Governance Tools

A number of SOA governance tools have cropped up over the years, including WSO2 Governance Registry, an open source tool from WSO2 (Web Services Oxygen). SOA governance tools have one or more of the following components:

  • Service Registry/Repository
    • Service directory with descriptive metadata
    • Service interface storage
  • Service Manager
    • Service lifecycle management
    • Service version management
  • Policy Server
    • Policy management and enforcement
  • Security Gateway
    • Security policy enforcement
    • XML-aware, intrusion protection

WSO2 Governance Registry possesses the first three components. The last component is provided by another WSO2 product named WSO2 Security and Identity Gateway. We’ll focus on the Service Registry/Repository and Service Lifecycle Management components in this blog.

Install Governance Registry

Before installing WSO2 on Windows, make sure you’ve installed the following software:

  • Java SE Development Kit (JDK) – v1.6.0_24 or later
    • Need to set JAVA_HOME environment variable and add bin directory to Windows PATH variable
  • Apache Ant – v1.8.0 or later
    • Need to set ANT_HOME environment variable and add bin directory to Windows PATH variable
  • Apache Maven – v3.0.3 or later
    • Need to set M2_HOME environment variable and add bin directory to Windows PATH variable
  • Web Browser
    • Firefox v15.0 or later
    • Internet Explorer v8 or later

Please refer to the Governance Registry documentation for additional details on installing the above products.

Next download the binary for Governance Registry from the following site. Version 4.5.3 was downloaded for this tutorial.

http://wso2.org/downloads/governance-registry

image

After downloading the binary, extract it to a folder on your hard drive. A wso2 folder (e.g., C:\wso2) will be created. Technically, you’re really not installing Governance Registry in Windows, you’re simply extracting the binary.

Start Up Governance Registry

To start WSO2, open a command prompt, navigate to C:\wso2, and run the following command:

wso2server.bat

image

Note: The online documentation has you run wso2server.bat –run, but when I tried this, I got the following error message:

The system cannot find the batch label specified – commandLifecycle

I examined the script and discovered that if you input the argument –run, the script is supposed to go to a label called commandLifecycle. However, that label no longer exists in the script, which is why I saw the above error message. I suspect at one point the script did have you use –run.

A bunch of system log messages are displayed showing the startup progress. Eventually, a message indicating the underlying WSO2 Carbon server is started will appear. Also, a message containing the URL of the Management Console will appear. The Management Console is a web-based, Java application which can be used to administer Governance Registry.

image

Open the Management Console

Open a web browser and navigate to the Management Console URL:

https://<IP_ADDRESS>:9443/carbon/

clip_image003

In the Sign-In section of the landing page, enter admin for the username and password and click Sign-in. You’ll be brought to the home page.

clip_image004

Register a Service

Governance Registry stores service information in a service registry. This includes WSDLs, XML Schemas, and WS-Policy policies. When registering a service, you can do so in one of two ways. You can either add a new service or add a new WSDL. The easier way to do so is to add a new WSDL.

In the navigation panel on the left, click the WSDL option underneath the Add group.

clip_image005

In the Add New WSDL panel on the right, specify the location of the WSDL. By default, Governance Registry prompts for a WSDL URL. Instead, we’re going to import the WSDL from an archive (specifically a zip file). Note that a copy of the archive has been provided with the blog (see link below). To do so, select Upload WSDL from a file from the drop-down. Then, specify the location of the WSDL/Zip file. Finally, click the Add button.

clip_image006

Note:If you need to upload a WSDL file from the file system and that WSDL imports other WSDL files or schemas, then you need to upload an archive file, not a single WSDL file. If you need to upload a WSDL file from the file system that imports other WSDL files or schemas, then you need to upload an archive file, not a single WSDL file. Otherwise, WSO2 will give you an error message saying an invalid WSDL definition was found. This is because of the fact that WSO2 only allows you to upload a single resource at a time. Hence, if the WSDL file has any references to any other files, they won’t be resolved and an error will occur. By uploading an archive file, Governance Registry can easily access the other files inside the zip file.Note that if instead, you import the WSDL file using a URL (default option), this is a non-issue.

A WSDL List will be displayed showing the uploaded WSDL file.

clip_image008

The WSDL file and any imported files (in this case, an XML schema), were uploaded and stored inside the service registry. In addition, a Service entry was created in the registry. Also, when uploading the WSDL, Governance Registry will validate the file, including any imported files.

Note: Behind the scenes, Governance Registry stores service metadata inside an internal database. By default, it uses an H2 database, but you can configure another database instead (e.g., DB2, MS SQL, Oracle). Please refer to the documentation for more details on how to do so.

Examine and Update the Service Resource

Let’s examine the results. In the navigation panel on the left, click the Services link under List.

Notice that a service definition named MovieService appears. This was added automatically, since the WSDL file contained a service element. It was also automatically versioned (i.e., 1.0.0-SNAPSHOT).

clip_image010

Click on the 1.0.0-SNAPSHOT link to display the service details.

Notice that some of the fields in the Overview section are pre-populated, including the name, namespace, and version. The name and namespace were derived from the WSDL file you uploaded.

Enter a description of the service.

clip_image011

Notice that the Dependencies section contains a reference to the WSDL file that you uploaded. This is an example of an inferred dependency.

clip_image012

Note: Behind the scenes, Governance Registry stores service metadata inside an internal database. By default, it uses an H2 database, but you can configure another database instead (e.g., DB2, MS SQL, Oracle). Please refer to the documentation for more details on how to do so.

 

Note: ep-www-example-org is an Apache Synapse endpoint file, which was automatically created when you uploaded the WSDL file.

In addition, let’s fill out the Interface section, although it’s not required to do so. Select HTTP for the transport protocol, SOAP 1.1 for the message format, and Request Response for the message exchange pattern.

clip_image013

Since security is not being employed, leave the default setting of None for all the security related fields.

clip_image014

Note: The fields listed can be customized. Refer to the documentation for more details.

Scroll down and notice that a single endpoint is defined, based on the service endpoint defined inside the WSDL. You can optionally choose to specify the environment that the endpoint corresponds with (e.g., Dev, Test, Stag, Prod), since the endpoint tends to vary based on the environment.

clip_image015

Finally, click the Save Service button at the bottom of the page to persist your changes to the repository.

Examine the WSDL Resource

In the navigation panel on the left, click the WSDLs link under List. Notice the same page is displayed as after you uploaded the WSDL. Click the movie_service.wsdl link.

First off, notice that just like for the service resource, there is a list of dependencies displayed. In this case, movie.xsd, which is imported by the WSDL, is listed.

clip_image016

In the Content panel, a summary of the WSDL file is displayed, including the service element information, the port type information, the binding information, and the schema import.

clip_image017

Click the Standard view link. Now click the Display as text button to display the actual contents of the WSDL file.

clip_image018

Click the Cancel button to not save any changes.

Note that you can also manually edit the WSDL file from here using the Edit as text button. More likely, the WSDL file would be updated externally by a developer. If so, you can upload the new version of the WSDL to the registry using the Upload button. You can also download a copy of the WSDL for further inspection using the Download button.

Finally, click the Visualize button to show a visual representation of the WSDL.

clip_image020

Click the X button in the upper right corner of the dialog to close the visual view.

Examine the Schema Resource

In the navigation panel on the left, click the Schemas link under List.

A single schema labeled movie.xsd will be listed, which was imported by the WSDL file you uploaded. Click the movie.xsd link.

clip_image021

Notice that instead of having a Dependencies panel on the right, there is an Association panel. This shows that the schema is “used by” the WSDL you uploaded.

Note: Just like for dependencies, associations can be manually created.

clip_image022

Next, observe that the Content panel contains a summary of the schema, including its target namespace, its elements, and its attributes. Also, there are links that allow you to view edit, download, or visualize the schema, just like for the WSDL file.

clip_image023

Add a Lifecycle to a Service

Thus far, we’ve examined the service registry component of Governance Registry. Let’s now examine its Lifecycle Management component.

Each resource stored inside the registry can have a lifecycle attached to it. A lifecycle essentially acts as a state machine. The service management tool manages the state transitions of a service. For example, a service can be in a “modeled”, “assembled”, “deployed”, or “retired” state.

Right now the movie service we’ve registered doesn’t have a lifecycle associated with it. Next, we’ll add one to it.

Click the Services link under List. Click the 1.0.0-SNAPSHOT link.

In the Lifecycle section on the right, click the + button.

Click the Add Lifecycle button that appears.

By default, the only lifecycle provided by Governance Registry is the one labeled ServiceLifeCycle. It consists of 4 states: Development, Testing, Production, and Published to API Store.

clip_image024

Note: You can customize the ServiceLifeCycle lifecycle. You can also create entirely new lifecycles to better suit your needs. Please refer to the documentation for more details.

Click the Add button to add a lifecycle to the service.

clip_image025

The initial state listed is Development. Governance Repository allows you to transition to the next state (i.e., Testing) via promotion. It also allows you to revert to the previous state using demotion.

In addition to state transitions, Governance Repository employs checklist items to indicate activities you’re supposed to perform during a certain lifecycle state.

Check the boxes next to all three items and click the Promote button. Note that you would normally check these off over time, as each development activity is completed.

In the table that appears beneath the checklist, enter 1.0.0 for the version numbers for the WSDL, schema, service, and endpoint (ep) resources. Then click Proceed.

clip_image026

A success message should be displayed. Click OK.

The Service List will be displayed and should now contain another entry for the service. Note that this one is in the Testing state, which is the next lifecycle state.

clip_image028

Click the 1.0.0 link. Notice that the state is now Testing. Also notice there is a new checklist listed. Check all 3 boxes and click the Promote button.

clip_image029

Again, type 1.0.0 in the version fields for all 4 resources. Then click Proceed.

A success message should be displayed. Click OK.

Once again, the Service List will be displayed and should now contain a third entry for the service. Note that this one is in the Production state.

clip_image031

If you go through the process one more time, you’ll reach the final state, which is Published to APIStore.

clip_image033

There is also a Lifecycle History section in the service page, which allows you to view the lifecycle states the resource went through and how long the resource was in each state. If you click the + button inside the section, Governance Registry will display the service’s lifecycle history.

clip_image034

Note that Governance Registry also allows you to configure notifications (e.g., email notifications) that will be sent to one or more individuals when a resource changes state (e.g., checkbox checked, checkbox unchecked, etc.). Please refer to the documentation for details on how to configure this feature.

Shut Down Governance Registry

Click the Sign-out link in the upper right corner of the Management Console.

Back in the command prompt, press Ctrl-C to stop Governance Registry. Enter Y for yes when asked whether or not you want to terminate the batch job.

Summary

In summary, WSO2 Governance Registry is a sophisticated governance toolset that supports both design-time governance and runtime-governance. We focused on the design-time governance features. To take advantage of the runtime-governance features, you need to integrate WSO2 Governance Registry with WSO2 Business Activity Monitor.

For more information on Governance Registry, please refer to:

http://docs.wso2.org/wiki/governance-registry-documentation

For more information on SOA Governance, check out our SOA Governance course (WA1508 Implementing SOA Governance):

http://www.webagesolutions.com/webapp/wcs/stores/servlet/Product_10001_10051_10622_-1_10518,10519,11001_main_implementing-soa-governance-training

Download the WSDL file used in this blog from the following link:

http://www.webagesolutionsfiles.com/upload/blogs/ws02/movie.zip

  1. #1 by Furqan on December 26, 2013 - 6:28 am

    Please send us the link of movies.zip. You are referring to the wsdl but the link to download it seems to be missing.

  2. #2 by Stuart Smith on January 10, 2014 - 12:45 pm

    This has been fixed. You should now see a link to the file at the bottom of the post.

    Remember that this file is just some sample WSDL files used to demonstrate the tool. It might be useful to use WSDL files of web services you have developed or manage to see the features of the tool and how it might be used to implement governance of your own web services.

  3. #3 by Mariom Hubble on July 10, 2015 - 2:22 pm

    Matthew – is isn’t often that I find an article this well written … step by step, with pictures. Thanks for making it simple!!!

(will not be published)

*