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
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
| 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.
Open the Management Console
Open a web browser and navigate to the Management Console URL:
https://<IP_ADDRESS>:9443/carbon/
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.
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.
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.
| 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.
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).
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.
Notice that the Dependencies section contains a reference to the WSDL file that you uploaded. This is an example of an inferred dependency.
| 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.
Since security is not being employed, leave the default setting of None for all the security related fields.
| 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.
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.
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.
Click the Standard view link. Now click the Display as text button to display the actual contents of the WSDL file.
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.
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.
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. |
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.
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.
| 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.
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.
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.
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.
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.
If you go through the process one more time, you’ll reach the final state, which is Published to APIStore.
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.
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):
https://www.webagesolutions.com/courses/WA1508-implementing-soa-governance
