Discovery is the name for the method to locate the entry points for the OSLC API in EWM and other ELM tools. The mechanism is the same for all applications but there are differences in the details. This post aims to help understanding the discovery process with a focus on EWM and work items. Ultimately we want to be able to create a new work item and need to get all that is required to do that.
Context of the blog post is the series
This is the series of planned posts I intent to publish over time. Most of the examples will be EWM based, but quite a lot of the content applies to more ELM applications. The examples where performed with versions 6.0.6.1 and 7.0.x.
- Using the EWM REST and OSLC APIs
- ELM Authentication
- EWM Discovery – this post
- EWM Work Item OSLC CM API
- EWM OSLC Query API
- EWM REST API to access existing Work Item Queries
- EWM Reportable REST API
External Links
- Here is another interesting article about discovery.
Rootservices
The main entry point into EWM and other Jazz applications is the rootservices document. The document is an XML document that is based on RDF. The document can be accessed using a HTTP GET on the rootservices in the context root of the ccm and other applications. For example:
GET https://elm.example.com:9443/ccm/rootservicesThe document is not password protected and does not require special headers to be accessed. It is only available as RDF XML document, there is no other way or format to get it. It is possible to use the URI for the rootservices document directly in the browser to display it.
The rootservices document contains information about all the resources and services provided by the Jazz Server.
Service Provider Catalog
To create a work item we need to find the Work Item Service Provider Catalog. We are interested in the rdf:resource entry of the element oslc_cm:cmServiceProviders.
There are certainly many ways to achieve this. The best way to achieve this is to use RDF. RDF support exists in various languages. I am not the best person for the job to explain RDF. My summary would be that RDF defines subject, predicate, object relationships in a Graph based on XML. Once the graph is created, it can be queried. For example, if one has the subject and the predicate it is possible to locate the objects.
The trick is to understand what the subject, predicate and object could be. I have always struggled to figure that out on my own, just looking at the RDF XML document. I have found two possible solutions, that work for me.
- Serialize the graph as N-Triples and look into these
- Even better, serialize the graph as Turtle format and look into that
Here is a part of the rootservices document, that was parsed as RDF XML serialized into Turtle.
In this document, line 19 shows the subject. Please also note line 17 that shows a prefix definition we are interested in. The next part of the document of interest is shown below.
Line 100 shows the object we are after, the URI
https://elm.example.com:9443/ccm/oslc/workitems/catalogThe predicate to locate the object is
oslc_cm1:cmServiceProvidersWith Line 17 above the predicate has the following namespace prefix
@prefix oslc_cm1: <http://open-services.net/xmlns/cm/1.0/>The lines 104 to the end of the file show additional subjects and their predicates and objects.
In Python, it is possible to use the library rdflib to work on RDF XML. A core communication support library that I have developed for this define the URIs and namespaces for the used domains. Also see the blog post Using the EWM REST and OSLC APIs for more information about this. The documentation for rdflib can be found here.
The image below shows an example for defining the namespace used above.
The image below shows the import statements used for rdflib in my communication library that has all the RDF support infrastructure.
The image shows the code that is used to serialize the rootservices document and the function to get the service provider catalog. The last argument is the predicate that locates the work item service provider catalog we are interested in. In this example the predicate is
comm.oslc_xml_cm1_ns.cmServiceProviders
Which translates to
http://open-services.net/xmlns/cm/1.0/cmServiceProviders
or
oslc_cm1:cmServiceProvidersused here to search for the service providers.
The function below composes the subject and then gets the objects selected by the subject and the predicate.
The function creates the RDF graph. This binds all the namespace definitions and aliases.
Then the rootservice document is parsed based on this RDF definition to create the graphs content. The code creates the URI for the rootservices document that represents the subject – it is basically the URI of the rootservices document. Finally the code gets all objects selected by the subject and predicate, and creates an array of these URIs.
The code segment shows how the work item service provider URI is then taken out of the result array. Please note that all these activities did not require a login, username, password or anything in addition to the rootservices document.
The image below shows how the RDF graph is created and the desired aliases and namespaces are bound to the graph.
Work Item Service
We just discovered the work item service provider catalog shown in the GET command below. The next step in the discovery chain is to look up the work item services for the project areas. This is done using the service provider catalog that was discovered above.
GET https://elm.example.com:9443/ccm/oslc/workitems/catalogand the listed OSLC request headers.
Accept application/rdf+xml; charset=utf-8
OSLC-Core-Version 2.0Note that this request is for a protected resource. The server will redirect to the authentication. The details are explained in the previous post ELM Authentication.
The resulting RDF XML document contains the information we are interested in. The image below shows the Turtle serialization of the service provider catalog. It shows a structure similar to below.
The section with the predicate oslc:ServiceProviderCatalog shows the project areas services documents. For some purposes this might be enough. It is possible to iterate all the service provider catalogs to get more information for each one performing a GET on the URI. However, the response we already got contains more information that can be used.
By searching for the objects that have the predicate oslc:ServiceProvider instead, it is possible to access the URI for the service provider, as well as additional information such as the project areas name using the dcterms:title. This can help reducing the number of subsequent calls to get these details.
The code below shows how to get that information from the serialized document. It builds arrays of project area names and URIs which is later used. E.g. find the index for a project area name and then get the related URI. There are likely better ways to store the information in Python.
The first step is to look up the subject for the predicate oslc:ServiceProvider. The resulting URI is the service provider for the project area. For example
https://elm.example.com:9443/ccm/oslc/contexts/_8e5qfFpmEeukW7cqqDjAuA/workitems/services.xmlAs explained above, the code uses the found subject to get the project area URI in the oslc_cm1:details and the project area name in the dcterms:title attribute.
Project Area OSLC Services
In EWM, work item services are project area specific. The reason is that each project area can have a different process and the process defines the work item types, attributes, workflows and all that. The next steps in the discovery process would be to get the project areas services.xml.
GET https://elm.example.com:9443/ccm/oslc/contexts/_8e5qfFpmEeukW7cqqDjAuA/workitems/services.xmlThis requires the OSLC headers:
Accept application/rdf+xml; charset=utf-8
OSLC-Core-Version 2.0The resulting RDF XML document contains information about various OSLC related capabilities and services. By looking through the information, especially using the Turtle format, it is easy to identify.
- The OSLC query capability
- Various dialogs such as OSLC selection, creation dialogs and pickers
- The OSLC creation factories for all the work item types
- The OSLC resource shapes for all the work item types
Similar to the work item services above, it is possible to get the desired information. Here example code getting the creation factories and related resource shapes for all the work item types.
The pattern repeats. To create a work item of a specific type, get the creation factory for that type. To get information about the attributes to create, in the work item, get the resource shape for the type. For the attributes in the resource shape get the type, allowed values and multiplicities.
Other Formats
The rootservices document is only available in RDF XML. Dependent on the tool, other formats might be supported for subsequent documents. For example using the header
Accept application/json; charset=utf-8it is possible to try to get the JSON representation. This works for EWM in various places. No guarantee. The discovery mechanism in this case is similar to the XML example above, the only difference is that JSON is a format that is easier to read for humans in my opinion. Instead of creating a graph, it is necessary to use a JSON library to access the data.
The code below shows how to get the service providers when using JSON format instead of RDF XML.
The discovery is analogue to what has been shown above with RDF. Even the structure of the code is similar, which is due to the fact that the data structure is similar. It is just in a different format that is easier to digest than RDF, at least for me.
Summary
I have struggled for a while with how to explain the discovery process. Especially how to get the data out of the RDF XML has been hard. Since I found the Turtle format, it makes a lot more sense to me. So, as always, I hope that this was of interest and helps the users and the Jazz community to make their life easier.
rsjazz 