The Hitchhiker’s Guide to interfacing with Registry Services – Part 1: Registration

Body

Business partners and internal development teams often commend the simplicity of the OSLC integration model adopted in Jazz for Service Management, which is based on well-established open web standards.

The openness guarantees that the knowledge is reusable in other implementations, and that vendor neutrality will ensure the stability of APIs and the simplicity of integration with other applications. At the same time, those standards do carry a handful of concepts and models on their backs, but do not panic, they are mostly harmless.

The general feedback I hear from developers is that they could use some directed guidance through those concepts and APIs.

This is the short, and ordered, introduction I share with developers who ask where to start when writing a client for Registry Services. Note that the Jazz for Service Management InfoCenter remains the authoritative source of information on all RDF classes, Registry Services concepts and programming models.

The focus here is on the mechanics of how you would create a client, not on the reasons why you would create one. For the latter, I suggest the enlightening executive introduction written by John Kogel or the excellent selection of Pulse 2013 videos posted by Chris Lazzaro a few weeks ago.

Before getting into it, I assume anyone looking for more information on interfacing with Registry Services may already be aware that there are two key portions of the Registry Services functionality, that is of a Service Provider registry where applications register themselves or their sub-components; and the Resource Registry portion, where a service provider creates system management resources, such as computers, databases, and services instances.


Register your application first…

1. Get some REST. I know, you just got started, but all programming interfaces for Registry Services follow the REST programming model and are paired with the HTTP protocol. In other words, all requests to create, update, retrieve or delete a record from Registry Services are invoked through HTTP requests of type POST, PUT, GET or DELETE, respectively.
   
   The request to register your application, or any request to register anything in Registry Services, starts with the URI of a collection. This InfoCenter page (http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/oslc/web/rs_t_locate_resource_registry_access_point.html) explains how to obtain the URIs for all collections in Registry Services.
   
   In particular, the Service Provider collection is considered the bootstrap URI for your Registry Services installation, so you will simply get it from your Jazz for Service Manager administrator. It should be something like http://server:16310/oslc/pr/collection.
   
   At this point your next question is likely to be: “Ok, I can write a web client to issue an HTTP POST operation, plenty of toolkits out there…what does the data look like?”
   
   They look like XML or JSON payloads, what else? But before getting there, and I apologize in advance, I must inflict readers with an abstraction first.
    
2. All data sent to or retrieved from Registry Services is represented as an RDF model, that is, either a single RDF resource or a collection of RDF resources.
   
   RDF stands for Resource Description Framework (http://www.w3.org/RDF/), less formally known as “linked data”, and is a conceptual data representation model where things have properties and references to other things. The previous simplification may be the cause of my disappearance in a dark alley, probably at the hands of a couple of people over here who actually participate in standards bodies, but it is really that simple and a powerful concept which we use everyday while browsing the web.
   
   Your next question may be “This is just too abstract, I am developer. Can I see some real artifacts? How do I map these abstract RDF models to something like an XML or JSON payload?”. In that case, you can try the brute force approach of reading through something like the RDF/XML Syntax Specification (http://www.w3.org/TR/REC-rdf-syntax/) or the more sensible approach of finding an RDF library for your programming language of choice, which is the subject of one my upcoming blog posts (If you can’t wait and you are using Java, Apache Jena is a great choice).
   
   Your other next question is likely to be “Great, RDF models. I just read a little about it, they are generic data structures. How do I know the types and properties used to register my application with Registry Services?”, which leads us to the next topic: the OSLC Core Specification.
    
3. Open Services for Lifecycle Collaboration (http://open-services.net/) , or OSLC, is an open community promoting open specifications covering integration of lifecycle tools. The specification for integration and lifecycle tools right now cover anywhere from task management systems to systems management.
   
   The basic RDF type accepted by the Service Provider portion of Registry Services is a “ServiceProvider”, which is covered in the OSLC Core Specification (http://open-services.net/bin/view/Main/OslcCoreSpecification) . With your abstract knowledge of OSLC ServiceProvider structures in hand, you may be ready for more detailed instructions and references to register a Service Provider, which you can find directly in the Jazz for Service Management InfoCenter at: http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/oslc/web/rs_t_create_srvc_provider_rec.html . While at it, you may want to read about registering resources in batches for significant performance improvements on all sides.
   
   Your next question is likely to be “Great, I know the kind of data structure I need to register my application, and I can read more in the InfoCenter on the exact payloads I need to send to Registry Services. Now how do I know which types of system management resources my own application can create in Registry Services?”
    

…then your resources
 

1. Jazz for Service Management Registry Services Vocabulary (http://jazz.net/ns/ism/registry#) defines the base RDF types for the Resource Registry portion of Registry Services. The two key types are RegistrationRecord and ResourceRecord. A RegistrationRecord is what a an application exchanges with Registry Services, such as a computer or a service instance. The ResourceRecord class defines a managed resource in the reconciled view created by Registry Services based on the registration records across all service providers.
   
   In another oversimplification: Your application manages registration records. Registry Services manages resource records, which are a unified view of registration records from all applications.
   
   “Ok, my application is mapped to a Service Provider in the Service Provider registry, and I know my application has to create registration records, but now I have computers and software servers that I want to create in Registry Services. Is there a structure and properties for those?”.
   
   The answer is “yes”, there is a structure expected by all clients interfacing with Registry Services, otherwise it would be impossible for Registry Services to build a consolidated view of all registration records. Whereas there is a set of common definitions out-of-the-box in Registry Services (see the next point) , it is entirely possible for applications to create new definitions and make them visible to other applications at runtime (see the subsequent point on Resource Shapes)
    
2. Reconciliation Specification (http://open-services.net/wiki/reconciliation/OSLC-Reconciliation-Specification-Version-2.0/) and Common IT Resource Type Vocabulary (http://open-services.net/wiki/reconciliation/Common-IT-Resource-Type-Vocabulary-Version-2.0/) , or CITRTV (err…maybe that acronym is trickier than the spelled out version) . These two two specifications further define the registration and resource records managed inside Resource Registry: CITRTV defines the RDF types, such as computer systems, databases, and server instances; whereas the reconciliation spec defines the details for each type.
   
   Registry Services is shipped with the definitions in the CITRTV 2.0 specification, but consider those pre-canned definitions more of a starting point when designing your application. In Registry Services, the effective list of resource definitions can be changed administratively, through addition of new resource definitions or even modifications to already existing definitions, which may lead you to your next question:
   
   “I understand why there is an initial set of resource definitions, but my application needs to register ATM machines. Where do I start?”.
    
3. OSLC Resource Shapes (http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#oslc_ResourceShape_Resource) . A Resource Shape is an OSLC mechanism for describing the data you would exchange with an service based on OSLC specifications. An RDF vocabulary document can do the same, but think of a resource shape as being able to convey a bit of extra metadata and being better integrated with other OSLC specs. As one example, a property in a Resource Shape can contain, amongst other attributes, a title, a default value, or a maximum size.
   
   To answer your hypothetical question in the previous point, you would create an resource shape to represent ATM machines, then use the Registry Services command-line interface to add that resource shape to the list of resource shapes used by the Registry Services runtime.
   
   You can read more about how to query the list of all resource shapes available for client applications in the Jazz for Service Management InfoCenter, directly in this page: http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/oslc/web/rs_c_resource_shape.html.
   
   You can also read more about how to use the Registry Services command-line interface to create, update, and delete resource shapes at http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/cli/rs_c_cli_operations.html

Resource reconciliation, you say?

Yes, reconciliation is the primary function for Registry Services.

As a simple example, let’s say three different applications create each a registration record to represent a computer they observe on the network. If later Registry Services determines that these three computers happen to be the same, Registry Services will expose a single resource record to represent that computer.

The determination that the underlying managed resource behind a registration record is the same as the underlying managed resource behind a different registration record is based on the identification rules for that type of managed resource. These identification rules are a bit hidden in the Reconciliation Specification, under the “Additional Requirements” section for each type definition. Each bulleted element contains a set of properties that define an identification rule. For instance, for a crtv:ComputerSystem element, one of the bulleted elements has “crtv:hostid, crtv:vmid”, which means two computers from two different service providers sharing the same value for those two attributes will be deemed to be the same computer by Registry Services.

As mentioned before, the type definitions (represented in the form of OSLC Resource Shapes) inside Registry Services can be changed administratively, so that although you can infer the default identification rules from the reconciliation specification, your best bet to find out the identification rules for a given resource type in Registry Services is to query the corresponding OSLC Resource Shape and inspect its list of identification rules. Note here that identification rules are not defined by the OSLC Core Specification, but rather as an extension in the Reconciliation Specification. The details on the structure of identification rules in a Resource Shape, as well as the mechanism for querying them, is explained in detail here: http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/oslc/web/rs_c_resource_shape.html

In keeping with the purpose of this blog entry, this was just a snippet to give you the basics on how the reconciliation function works and why there are two types of records in Registry Services (registration records and resource records) .

The detailed explanation of how the reconciliation algorithm works is documented here: http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/rs_original/oslc/web/rs_r_resource_rec_reconciliation.html.

---

I hope this entry can get you started in the right direction and in the right sequence. We would love to hear about clients you may be writing and the kinds of experiences and feedback you may have.