Open IGC: Defining a new bundle!

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:
https://dsrealtime.wordpress.com/2015/07/29/open-igc-is-here/

Previous post in this series:
https://dsrealtime.wordpress.com/2015/08/07/open-igc-a-simple-messaging-system-use-case/

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:

bundleSnippet

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:

bundleFolderStructure

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.

iconList

Ultimately, the asset_descriptor.xml and the two folders are zipped together into a single archive:

bundleZip

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:

register

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:

registrationError

…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:

MessagingIcons

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:

igcQueryWithProperties

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!

Ernie

Advertisements

6 Responses to “Open IGC: Defining a new bundle!”

  1. HomerSlow Says:

    Hi Ernie,

    Is it possible to specify a built-in asset class as the root class somehow. In the messaging example it would be the Host-class (Database, Data File Folder and Transformation Project classes have Host as the root class)?

    I tried to specify it in the asset_type_descriptor.xml it didn’t work (perhaps obviously). I tried to reference my custom top asset class to a host in asset publishing operation but it didn’t work either. Maybe I am doing something wrong but none of the available examples demonstrates something similar.

    Kind regards
    OS

    • dsrealtime Says:

      mmm. Cool idea. I wish we could use Open IGC to extend existing classes, but right now, it is only for creating entirely new bundles of classes.

      Ernie

  2. HomerSlow Says:

    Thx for the answer:)

    Btw, we still have to use istool to create built-in classes instances programmatically, like database, schemas, tables and columns?

    Kind regards
    OS

  3. Dorothy Says:

    Hi Ernie,

    I tried to create a new bundle but I am receiving the error:
    “No asset descriptor file found.”
    The bundles zip folder has the asset_type_descriptor.xml file defined as well the properties file and icons folder. Can I get help on this?

    Regards,
    Dorothy

    • dsrealtime Says:

      hmm. At the moment I am not sure what it is…unzip your zip file to check carefully….. how are you doing the zip? Be sure that the asset_type_descriptor.xml is at the right level. It should be in the parent of the other two prior to zipping. I like to keep my three “parts” in their own OVERALL subdirectory, but I don’t zip at that level. Go “into” that parent and then (if you are using windows), highlight all three things….the icons subdir, the language subdir, and the xml, and then “send to compressed (zip) file”….. –ernie

      • Dorothy Says:

        Thanks Ernie….I could successfully import a new asset type. I now want to create a relationship between the newly created asset type and a Database table or column. How can I create this relationship in the XML file?


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: