Quick Start Guide

The WSO2 Governance Registry (G-Reg) is an SOA-integrated registry-repository for storing and managing data or metadata related to services and other artifacts. It consists of two Web-based interfaces: the G-Reg Publisher and G-Reg Store. The Publisher is used to create and manage assets while the Store is used to search for and subscribe to assets.

Let's take a look at the basic use cases of the G-Reg using a sample scenario. 

Introducing the sample

BuyMore is a fictitious supermarket chain with more than 200 retail branches. Given below is a snapshot of the existing services of BuyMore with their lifecycle states:

Let's go through the main features of WSO2 G-Reg using BuyMore's services as an example.

Deploying the sample to create assets

Assets are registry resources or collections of resources that store metadata and information regarding governance-related entities. Developers create assets and manage their lifecycles and dependencies using the G-Reg Publisher.

For the sake of simplicity, instead of creating assets from scratch using the G-Reg Publisher, let's deploy a sample that comes with the WSO2 G-Reg distribution. It creates different types of assets in the G-Reg. WSO2 G-Reg supports REST, JSON, SOAP, and Thrift, although we only work with REST services in this guide.

1. Make sure you have the G-Reg server started as instructed in the "Before you begin" help tip above.

2. Using the command line or terminal, navigate to the <G-REG_HOME>/samples/getting_started/ directory and execute the following command. It deploys the assets in the server: 

   ant

   Let's log in to the G-Reg Store and check whether the assets were created successfully.

3. Go to the G-Reg Store using the URL https://localhost:9443/store/.
4. Type "buymore" in the search field, click the search icon, and note that no search results appear. This is because all assets related to BuyMore are made private and are not visible to anonymous users.
   
5. Let's log in to the G-Reg Store. Click the Sign In link in the top right-hand corner of the console and enter admin/admin as the credentials in the login screen.
   
6. Note that the results of your previous search now appear in the Store.
   

You now have sample services and other artifacts related to BuyMore along with two users (a developer called Smith and a DevOps engineer called Mark) deployed in the G-Reg. Next, let's log in to the G-Reg Store as Smith and subscribe to an asset. 

Subscribing to an asset

Smith is a developer at BuyMore. Smith comes to the G-Reg Store to find an asset that will calculate bill values of the products being purchased at BuyMore. Smith searches for the asset and subscribes to it in order to receive notifications regarding any changes that happen to the asset later. 

1. Log in to the G-Reg Store (https://localhost:9443/store/) as Smith. Smith's credentials are smith/smith@bm.

2. Once logged in, search for an asset to help you calculate bill values by typing "calculate" or similar in the search field and clicking the search icon. Then, note that the two services that we mentioned at the beginning of this guide (i.e., BuyMoreBillCalculateRESTAPI version 1.0.0 and 2.0.0) appear in the search results. 

   
   Smith clicks both assets to read their details and notices that version 1.0.0 is in the Production state and ready for use, whereas version 2.0.0 is still in the Testing state. Therefore, Smith decides to use version 1.0.0.
   

   Tip: The G-Reg Store displays assets in all lifecycle states by default, but can customize this behavior so that only assets of a lifecycle state/s of your choice are displayed in the Store.

3. Click version 1.0.0 of the asset to open it.
   

4. The asset opens. Scroll down to see the following links:

   • Swagger UI: Opens a Swagger console where you can invoke the REST asset.
   • Download: Downloads the Swagger definition of the REST asset to a given location in your machine.
   • Copy URL: Gives you the option to copy the URL of the Swagger definition. 

   

   Smith has now discovered a REST asset that can be called from other applications to calculate bill values. Next, Smith subscribes to receive notifications for this asset. A notification is an alert that you get via email and/or the G-Reg Store regarding an asset's lifecycle and/or information change. 

5. Click the ->OPTIONS button in the top right-hand corner of the screen to expand the notification settings.
   
   You can subscribe to receive notifications through emails or through the G-Reg Store.You can also opt to receive notifications when an asset is changed and/or when it goes through a lifecycle state change. 

6. Enable the option to receive notifications related to lifecycle state changes via the G-Reg Store.
   

Smith (developer) is now using BuyMoreBillCalculateRESTAPI version 1 for development work. 

Changing the lifecycle states of assets

BuyMore wants to introduce BuyMoreBillCalculateRESTAPI version 2, which implements the company's new loyalty scheme. As its testing is completed, BuyMore wants developers to use the new version of the asset in their applications. Mark, who is a DevOps engineer of BuyMore, logs in to the G-Reg Publisher and changes the lifecycle state of BuyMoreBillCalculateRESTAPI version 2 from TESTING to PRODUCTION. 

1. Log in to the G-Reg Publisher (https://localhost:9443/publisher/) as Mark. Mark's credentials are mark/mark@bm.

2. Use the following text to search for the service to be promoted to production, and then click the asset to open it.
   name:BuyMoreBillCalculateRESTAPI version:2.0.0

   

3. Once the asset opens in the Store, go to its LIFECYCLE tab, add a comment to explain why you are changing its lifecycle state, and then click Promote. 
   

4. Note that the lifecycle state of the service is changed from TESTING to PRODUCTION, and the comment you added appears under history. Any user who goes to the LIFECYCLE tab of this service can see the comments history.
   Now that a new version of the asset is in production, Mark deprecates the older version (i.e., version 1). This triggers an alert to Smith, who is subscribed to it to receive notifications.

5. Click the GOVERNANCE CENTER - PUBLISHER label at the top of the console to go to the publisher's Homepage, search for the term "BuyMoreBillCalculateRESTAPI", and click version 1.0.0 of the asset to open it.  
   

6. Once the asset is opened, go to its LIFECYCLE tab and click Deprecate.
   

7. Note that the lifecycle state of the asset is updated successfully.
   

Mark has now published the company's new loyalty scheme and deprecated the old one. 

Receiving notifications

In the previous section, Mark deprecated the asset BuyMoreBillCalculateRESTAPI version 1.0.0. Smith, who is a developer at BuyMore, has subscribed to receive notifications regarding lifecycle state changes of this asset through the G-Reg Store. Therefore, Mark's activity triggers a notification for Smith in the G-Reg Store.

1. Sign in to the G-Reg Store (https://localhost:9443/store/) as Smith (smith/smith@bm).
2. Click any one of the menus (such as REST Services) and note the new notification icon in the upper right-hand corner of the G-Reg Store.
   
3. Click the icon to expand and read the notification.
   
   Upon seeing the notification, Smith searches for a new version of the asset.
4. In the G-Reg Store, click the BuyMore tag under the Tags section.
   Alternatively, you can search for an asset using the search facility or by going to a related category using the All Categories drop-down list at the top of the console.
   
5. All the assets that have been tagged as BuyMore get listed on the console. Click version 2.0.0 of the asset BuyMoreBillCalculateRESTAPI to open it.
   

Comparing versions of the asset

After discovering BuyMoreBillCalculateRESTAPI Version 2.0.0 earlier, Smith now proceeds to compare it with version 1.0.0 to identify their differences.

1. Sign in to the G-Reg Store (https://localhost:9443/store/) as Smith (smith/smith@bm).
2. Go to the asset's homepage, and click the link of the underlying source of the asset under Associations > dependencies.
   

3. As this is a Swagger-based REST API, the Swagger definition of the asset opens. Click Compare with 1.0.0 in the homepage of the Swagger file that opens. 

   Tip: As you have only two versions of this asset, you get the button labelled with the other available version. However, if you have more than two versions of an asset, you need to first click the Compare With button, and then select the version.

   

4. Compare the differences of the two asset versions.
   

Reviewing the new version of the asset

In the previous step, Smith compared BuyMoreBillCalculateRESTAPI Version 2.0.0 with its first version in the G-Reg Store. Smith then proceeds to review the new version.

1. Go to the User Reviews tab of the asset and add a rating (such as 5). Also add a review comment (such as "This version of the asset is recommended as it implements the company's new loyalty scheme"), and then click Post Review. 
   
2. Note that the review that Smith just added appears on the console, under the NEWEST category. You can filter reviews according to popularity and the date added.
   

Now that the new version of the asset is in production and the developers are actively using it, BuyMore decides to discontinue version 1.0.0. Mark, who is the DevOps engineer, logs in to the G-Reg Publisher and checks the dependencies that version 1.0.0 has with other assets before making it obsolete.

Viewing the dependencies of the asset

1. Log in to the G-Reg Publisher (https://localhost:9443/publisher/) as Mark (credentials: mark/mark@bm).

2. Search for the term "BuyMoreBillCalculateRESTAPI" and click version 1.0.0 of the asset to open it.  
   

3. Click Show Dependencies to view the asset's dependency graph and the policies. 
   

4. The dependency graph opens. Note that you can click the icons to view more information about them.

   For more information on viewing dependencies of an asset, go to Dependency Visualization with WSO2 Governance Registry.

   As this asset has no dependencies with other assets, Mark continues to make it obsolete.

5. Go to the asset's LIFECYCLE tab and click Obsolete.
   
6. Note that the lifecycle state of version 1.0.0 is now OBSOLETE.
   

Smith (developer) subscribed to receive notifications about the lifecycle state changes of version 1.0.0 of the asset earlier in this guide. Therefore, this lifecycle state change triggers a notification to Smith in the G-Reg Store. Upon receiving the notification, Smith makes a backup of the asset. 

Making a backup of the asset

1. Log in to the G-Reg Store (https://localhost:9443/store/) as Smith if you haven't done so already (credentials: smith/smith@bm).
2. Click any one of the menus (such as the REST Services menu) and note that you now have two notifications in the upper right-hand corner of the G-Reg Store.
   
   Smith reads the notification and notices that version 1.0.0 of the asset has been discontinued by BuyMore. Smith proceeds to make a backup of the asset. 
3. Search for "BuyMoreBillCalculateRESTAPI" in the G-Reg Store and click version 1.0.0 to open it.
   

4. The Swagger-based REST asset opens in the Store. Scroll down and click the Download button to download the content of the Swagger file.
   

Smith now has a local copy of the asset that BuyMore has discontinued.

In this Quick Start Guide, you have gone through some of the key functionality of WSO2 G-Reg. For an in-depth understanding of the G-Reg, see the User Guide.