This post discuses another topic regarding Open IGC — the new “extensibility” API that allows you to define your own objects inside the Information Server repository, and then govern them with Stewardship, Business Terms, or detailed lineage reporting.
First post in this series:
Previous post in this series:
So…….you have decided that you want to extend the Information Server repository, and have decided that you want to create your own custom objects with their own icons and their own internal relationships. Now what?
Your first goal is to model what you want or need to represent. What objects do you want to govern? What kinds of lineage do you want to display? See the prior posts in this series for some ideas of what this might mean. Also, be sure to look at the documentation, and play with the real examples for extensibility that are included. [formal documentation for the Open IGC is here: http://www-01.ibm.com/support/docview.wss?uid=swg21699130 ].
Work it out first on paper, or on a whiteboard. What objects do you want a user to be able to click on, and request lineage? What levels in your database schemas do you want to show as connected objects in a lineage graph? If you are illustrating a process, one that has sub-processes and even additional sub-sub-processes, at what level do you want to provide a drill down or “expand” capability to the user for additional detail?
These specifications for your new object types are outlined in a “bundle”. The bundle represents each of the new object types and their icons that you will be defining. The bundle describes the relationships between the objects (parent/child or other “containment” definition) and also captures all of the individual properties (and their data types) for those objects. It establishes formal property names for their use in your code and in the user interface.
The bundle is defined using XML. A well documented xml schema is provided with the Open IGC, and is fairly easy to follow, even if you don’t spend much time with XML. Here is a snippet of the bundle I used for the prior post, to define my “Messaging” environment:
Specifically note the class element at the top, named “queue”, and its various properties such as default_persistence towards the bottom. It’s parent is “queue_manager” (defined earlier in the xml). Note also the “header section”. These properties will appear towards the top of the detail page when a user is reviewing this object, and also will be shown in the unique “hover” view that is available throughout all of IGC. Properties can be defined as simple strings, integers, float, etc. and also with enumerated types, as illustrated here. When using an enumerated type, the pre-defined list of values is automatically provided in a drop-down selection for any Steward who might edit this object. The values are also validated when objects are entered via API into the system.
The bundle xml, known as the “asset descriptor” is arranged alongside two special folders for language conventions (not yet fully supported) and custom matching icons:
Your matching icons are placed into an “icon” folder, following a naming convention for their class and size. As documented, the supported icon sizes are 32×32 (big) and 16×16 (small). These different icons will then appear in various places in IGC, depending on the context and what the user is doing.
Ultimately, the asset_descriptor.xml and the two folders are zipped together into a single archive:
A good practice to follow is to name the .zip file by the name of your bundle.
This is the file that is sent to Information Server to formally “register” your new objects (go to https://:/ibm/iis/igc-rest-explorer ). This can be done programmatically, of course, but the igc-rest-explorer page makes this very convenient, especially when you are first getting started, or if you haven’t done much with REST apis and their invocation as an HTTP based web service. In a later post, I will discuss various ways of making these calls in an automated fashion. Here is a screen shot of how this looks:
Click on “bundle” when you first get to the igc-rest-explorer page, and then POST for registering a new bundle. A convenient “browse” button allows you to select your bundle zip file and then just click “Try it Out!”. It is very simple to get started! Error checking is very thorough — if you mess up your bundle, the IGC registration will let you know. Here I have made a very simple error, trying to re-register the same bundle:
…it also picks up other subtle errors that you might make when defining your new objects.
When the registration works, you will get a clean confirmation, and can then immediately go and see the results of your creative thinking and design efforts! I like to immediately check the “browse all assets” list, to see what new icons and bundle “section” I have:
I also like to immediately select one of my objects in the IGC Query tool, and check to see that my special Open IGC custom properties are showing up as I expect:
If you need to make updates to your bundle, such as add new object types or properties or make mild changes to the labels or names shown in the user interface, or add/change icons, there is REST call (also available at the igc-rest-explorer page) to “Update a previously registered asset bundle”. You cannot make radical structural changes, or alter datatypes or the formal names of registered objects, but simple changes and additions are permitted. If you make changes to your icons, or add new ones, be sure to clear your browser cache to ensure that they are visible the next time you return to and refresh the browse page.
That’s it! Now I am ready to start adding real instances of my new objects to the repository and start governing!!!
Next post in this series:
Uploading New Assets!