Skip to end of metadata
Go to start of metadata

The following governance concepts are described below.

SOA Governance

In modern enterprises, Service-Oriented Architecture (SOA) should properly "steer" its enterprise IT system. This process is called "SOA Governance". Governance is derived from the Latin term for steering. It is hard to find a concrete definition for SOA Governance, as the term heavily depends on a multitude of factors. People tend to define SOA Governance differently.

In simple terms, SOA governance is a set of processes, responsibilities and tools that reinforces good behavior and help avoid bad behaviors. It is all about control. If you design a service for a specific purpose and for a set of consumers, you will want to have assurance that it will only be used for that purpose and by that set of consumers. You also want the service to be available, performing as it was intended for, and secured. Transactions must have integrity, at least to the degree that you originally specified. Most Importantly, you need to make sure defined processes and responsibilities are followed properly. For this you need to adapt proper measurement techniques (to measure effectiveness on the actions taken) in your SOA.

SOA Governance can be divided to two distinct phases:

  • Namely design-time governance
  • Run-time governance

Design-time governance spans over the entire service development cycle. For example, let's say a requirement analyst is gathering information to create a new service. Design-time governance makes the analyst's job easier by providing all related information on the requirement. Furthermore, it avoids service duplication, providing enough information on existing services and promoting service reuse. Upon properly defining service level agreements, the service will be properly tested and documented.

Runtime governance comes into play, soon after the service is deployed. It monitors operational aspects of a service (service performance bottle necks, who is accessing more, etc.). Unlike design-time governance, most runtime governance functions are automated. Reports generated in this phase are important feedback, for the next service design and development iteration.

For more information on SOA Governance, see Registry Life-cycles and Forrester's Major SOA Requirements.

Registries and Repositories

To enable SOA governance, software industry responded with two different categories of tools:

  • Registries 
  • Repositories

A registry is a tool that keeps a list of services with their locations. On the other hand a repository functions as a tool that keeps information on how the services are used, how they interact, who is using the services and why they are used. These tools are considered as key enablers of SOA Governance. Usually these two technologies come together as an "Integrated" Registry-Repository, thus avoiding the need of duplicated data entry and the need to synchronize information. Additionally, it decreases the risk of inconsistencies that may exist between a registry and repository.

In a registry-repository, you can publish information on services that you already use, planning to use and those services that you need to be aware of. Information related to both internal and external services (to you/your organization) can be stored in this way.

Service reuse is the heart of SOA. Before implementing a new service, you can search in the registry-repository for existing implementations. This helps you to use an existing service either as it is or by developing a new service associating the existing service. Furthermore, registry-repositories help you discover associations among services. This helps you to get a better idea of any impacts on changing a particular service.

In SOA Governance, it is important to enforce organizational and domain specific business rules (policies) to validate artifacts before they are published on a registry-repository. Usually most of these policies can be described in (machine-readable) documents such as XML documents. Registry-repository can read such documents to interpret rules found in them to validate against artifacts as needed. Such validations can easily go beyond simple syntax validations. For example, there can be a policy enforced so that WSDL artifacts must only be using "Document/Literal" style for communication. Validation usually improves overall quality of artifacts stored in a registry-repository.

Typically, artifacts in a registry-repository undergoes lifecycle states of create, test, deploy and deprecate. A registry-repository performs the following functions:

  • Enforces policies during transitions of the states of create, test, deploy and deprecate.
  • Defines "who can access what?" of services. Access to certain services may differ depending on the user, user group or state of the service lifecycle.
  • Sends notifications to relevant users once a change to a service artifact has been made.

As more and more services are introduces and reused, it is necessary to keep track of dependencies of each service in an organization. SOA registry-repository makes life easier by in this context, keeping inter-service dependency information as relationships among service information artifacts. For example, such relationships includes but not limited to Contains, Implements, Uses, Depends, etc. A registry-repository should allow defining custom relationships to cater organization-specific requirements.

Service artifacts evolve over time due to reasons such as fulfilling new requirements, yielding to different versions of the same service. A registry-repository should provide versioning capabilities that can enable automatic version control of artifacts stored. Additionally, a registry-repository also should keep older versions of artifacts to allow users migrate smoothly from one version to another.

A SOA registry-repository also need to seamlessly integrate its services with those in other SOA deployments. In other words, a registry-repository should federate with other SOA registries-repositories using open standards, and possibly appear as a single virtual registry-repository.

To implement SOA Governance in service run-time, a SOA registry-repository should provide a software development toolkit (SDK) to develop custom registry client applications and services. In this case the registry-repository acts as a source of operational and configuration data during runtime.

In summary, a registry-repository should provide the following features:

  • Record information on services
  • Search for an existing service for reuse
  • Discover associations and dependencies of a service
  • Enforce policies throughout the service lifecycle
  • User access control
  • Automatic version control
  • An SDK for registry-repository extensibility


WSO2 Governance Registry stores governance metadata and information on governance related entities. Registry resources storing this information and/or metadata are known as assets. Asset is a representation of any physical or digital entity that belongs to an organization, which needs to be governed. In WSO2 Governance Registry, a set of predefined attributes compose an asset.

WSO2 Governance Registry provides an XML-based semantic structure called RXT (Registry Extension Types), to define the structure of a given asset type. There are two RXT categories as follows:

  • Content RXTs : These are used to represent and maintain assets that have file content as their main attribute. (E.g. WSDLs, WADLs, Swagger files etc.). 
  • Generic RXTs: These are used to represent assets that are a combination of different types of attributes. (E.g. representation of SOAP services, REST APIs, Project, Enterprise Applications etc.)

WSO2 Governance Registry provides out of the box access to WSDL, WADL, Swagger, WS-Policy and XSD Schema Content RXTs, and SOAP service, REST service Generic RXTs, via WOS2 G-Reg Publisher. Also, you can define your own RXTs as required, and make them available for operations facilitated by the WSO2 G-Reg Publisher and Store interfaces.

For more information on these assets, see Managing Assets.


Resources and Collections

In the Registry level, an asset is transformed into one or more Resources, to store it in the configured database. Resource is a concept defined in the Registry.

Resources and Collections (analogous to files and folders on a file-system), are stored in the Repository of WSO2 Governance Registry. A Collection is modeled as a special type of Resource, inside which, you can represent other Resources and Collections. The Resources-layer of the WSO2 Governance Registry provides functionalities such as conducting validations on the storing process, storing associations among Resources, and catering management of the properties of Resources. Resource validations are done through Registry Handlers associated with a particular Resource media type. For more information on this, see Handler Sample and Managing Properties.

Categorizing assets

There are two broad categories of artifacts found in the WSO2 Governance Registry as follows. 

  • Resources:  A resource is any artifact from WSDL files to XML, Word/Excel documents, JPEG Images, etc. Every resource in the WSO2 Governance Registry becomes a center for social activity.

  • Collections: A collection is a group of resources that falls under a logical entity, and are stored within WSO2 Governance Registry. 

Publishing assets 

The WSO2 Governance Registry allows you to add services through its Web-based user interface. User can choose either to enter service details manually  or to import service information using a WSDL url. For more information see Governance Artifact Configurations.

It is also possible to validate a resource's compliance with standards such as WSDL, XSD and Web Services Interoperability (WS-I). Validation capabilities help improve the quality of resources. Validation tools are also an important aspect of policy enforcement, where you can enforce resources validation at specific points of a resource life cycle. See also Properties.

Discovering assets 

The WSO2 Governance Registry offers configurations options such as tags, comments, properties, ratings and descriptions for a resource. It is important to plan the use of these configurations, to allow them help in discovering services and enabling correct SOA Governance.

Resources for service discovering tremendously help in service reuse. In fact, it is one of the major functions of a registry-repository product. The WSO2 Governance Registry provides enhanced search capabilities to facilitate search based on tags and other advanced criteria. See also Resources. 

Asset lifecycle management

Typically many resources in your Registry, such as service descriptions, should progress through a series of "lifecycle stages". For instance, a service may start off as "created", then after quality assurance has confirmed that the service works as expected should be moved to "tested" stage. Upon testing, the service can then move to a "deployed" stage at which point it is released to production. Eventually, the service will be taken down or replaced with another as it moves to a "deprecated" state. Furthermore, registry allows users to define a checklist for stage transitions.

The WSO2 Governance Registry makes using and managing state-based lifecycle easy. Out of the box, the Registry comes with a default lifecycle that implements the state transitions explained earlier. You can define your own custom lifecycles with conditional state transitions, in order to match you/your organization's very specific requirements. See also Lifecycles.

Policy management

The WSO2 Governance Registry offers user authentication and authorization capabilities over all resources stored in the Registry. Easily configurable role based user management allows define, "who can accessing what?" within the Registry. Furthermore, the Registry provides activity logs that shows user activities over resources. You can apply filters on the top of activity logs to extract customized data to suite your information needs. See also Role Permissions.

Impact analysis

The Registry supports configuring of dependencies and associations for resources. It automatically detects certain dependencies when you publish a resource. For example, a WSDL might use an external XSD that can be automatically detected and imported to the Registry. In addition to dependencies, the Registry provide a way to configure associations among resources. You are free to specify the type of association such as "contains" or "uses" during association configuration. These associations help figure out the possible relationships that may exist among resources and also in analyzing the impact on changing a resource. See also Dependencies and Associations.

API management

Services (SOAP or REST) in WSO2 G-Reg are implemented as configurable governance artifacts (RXT files)which you create using the G-Reg Publisher. Usually, in WSO2 APIM service publication is done using the APIM Publisher Web interface. Instead, you can integrate WSO2 APIM with WSO2 G-Reg, to directly publish APIs to APIM Publisher using the services deployed in the WSO2 Governance Registry. For more information on API management, see Integrating with WSO2 API Manager.

Subscriptions and notifications

The notifications feature can be used to generate notifications for events that occur as a result of performing operations. To receive notifications, create a subscription to a particular event along with a specified notification method (e-mail alert or G-Reg Publisher/Store notification). For more information on subscriptions and notifications, see Adding Notification Subscriptions in Publisher and Store.


The WSO2 Governance Registry provides three extension points that provide a flexible, plug-in approach to link resources and to allow you to encode your own governance rules and policies. These include:

  • Handlers: To implement custom behaviors to be applied to resources.
  • FiltersTo intercept standard behaviors to make room for custom behaviors; Filters determine which Handlers are to be engaged on a resource.
  • AspectsTo associate custom behaviors with resources; Aspects differ form handlers, in that handlers are automatically applied to a resource, whereas, aspects are needed to be invoked manually through user action (for example, by clicking a button in the user interface). 

There are the three key Registry features that exist at the top of the Repository. You can use these to provide your own customization on top of the base product. Handlers are plug-able components that contain the custom processing logic for handling resources. Handler implementations provide alternative behavior for basic resource-related operations, by overwriting one or more methods in the Handler class.

 Each Handler is associated with a Filter. Filters provide the criteria to engage with Handlers. The WSO2 Governance Registry always evaluates the associated Filter before invoking a Handler. If the Filter evaluates to true, it invokes its associated Handler.

Similar to Handlers, Aspects are used to associate custom behaviors with Resources. The difference between Aspects and Handlers is that, you automatically apply Handlers to a resource, whereas, you need to invoke Aspects manually through a user action (e.g. by clicking a button on the UI).

Additionally, with the enhanced WSO2 Governance Registry API, you can embed the Registry in a runtime system (e.g. in the Enterprise Service Bus), and support automated run-time governance. For more information, see also Extensions.

Operational modes of the Registry

The WSO2 Governance Registry is designed, having in mind the ability to tailor it according to various business requirements. The WSO2 Governance Registry can be used in two modes of operation:


The WSO2 Carbon Server has been designed with the provision of multiple instances of similar servers to make use of a single configuration base. An ideal example is a cluster of WSO2 Enterprise Service Buses (ESBs). Here, we can define one node as the master of the cluster which has the ability to read and write configuration data, while the others can only read. The single-writer multiple-reader deployment scenario solves concurrency problems. The <G-REG_HOME>/registry.xml file can be used to define whether the embedded (or remote) instance of the Registry in-use is writeable or not. This is controlled by the readOnly parameter.


To run the registry in the read-only mode, set the readOnly element to true. Setting the read-only mode allows you to run an immutable instance of registry repository.

Configuring Registry as Root

The WSO2 Governance Registry also supports the notion of using a single repository shared among multiple servers based on the WSO2 Carbon Server platform. This is analogous to different users sharing the same file system. Each server (like each user) will be given a chroot'ed environment to work upon, with its apparent root being a child of the root of the shared repository.

The following registryRoot parameter in the <G-REG_HOME>/registry.xml file is used to define the apparent root of the running instance of the server.


 In the event of multiple servers running against a single repository, the WSO2 Carbon Server can be configured in three different ways. Without loss of generality, let's take two servers A and B, sharing the same repository.Then the three configuration options are as follows:

  • A is B's sibling - A and B have the same registry root (/, or /myroot).
  • A is B's parent - A has registry root / or /myroot while B has registry root /child or /myroot/child.
  • A and B are isolated - A has registry root /a and B has registry root /b.

The above configuration options facilitate a number of grid and clustered deployments. When configuring root, you can specify the absolute path of the collection, which you wish to use as the root of this registry instance.

Enabling Registry caching

To enable registry caching, set the enableCache element to true in the <G-REG_HOME>/registry.xml file. Once caching is enabled, repetitive read operations will be executed against the cache instead of the database. The default registry caching expiry time is 15 minutes.


Newly added resources have to be indexed before they appear in Content Search results. This automatic indexing process happens in the background and therefore newly added resources might not be immediately available for Content Search. Indexing frequency and initial startup delay for indexing can be configured in the <indexingConfiguration> element in the <G-REG_HOME>/repository/conf/registry.xml file as shown below. The indexers that implement the indexer interface for a relevant media type and new indexers are also configured in this configuration. 

For indexing to work across multiple nodes, they should either be sharing a common database for the config and governance sub-collections of the /_system collection. This will happen by default for JDBC mounts. For other types of mounts, if the database is not shared, appropriate replication of the REG_LOG table needs to happen between the nodes for indexing to work.

WSO2 G-Reg uses Apache Solr to support the Registry search feature. The logic of extracting content of the resource varies from resource type. Therefore, Apache Solr provides an extension point to write your own custom logic to create an index document for each resource. For information on creating a custom indexer, see Creating a Custom Indexer.

Creating organizations/domains

WSO2 Governance Registry supports role-based access control which can also be used to authorize users belonging to multiple organizations. This is two fold.

  1. The support for multitenancy allows running repositories belonging to one or more organizations or domains in parallel.
  2. A similar permission model can be established using a Corporate Directory installation spanning across multiple organizational units.

In most setups, you might also find the need to store various organization-specific assets in the repository. Such asset models can easily be constructed using the support for Configurable Governance Artifacts (RXT) and aligned with access control mechanisms.

For more information on how to create organization-specific asset models, please have a look at the People Model sample.

  • No labels