EWM Reportable REST API


Finally, to close the series of posts, there is another public REST API available for EWM. The Reportable REST API provides information about resources that may be useful in reporting, and provide some features not available in a “normal” REST API. This API is intended to be consumed in a number of scenarios, including:

  • For direct consumption by a reporting or document generation tool such as Rational Publishing Engine (RPE).
  • The ETLs (data collection jobs) in RTC use these APIs as a source of data to deposit into the data warehouse.

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.

External Links

I used the following link for exploring this mechanism.

Not OSLC

This series mentions OSLC a lot. The Reportable REST API is not an OSLC API. It uses different representations and no headers.

The Reportable REST API

I did completely miss the reportable REST API for years. Some 2 years ago, I helped a team working with a customer to access data that is not accessible in OSLC. The data is specifically the approval data for a work item.

I developed a solution prototype to access this data using a web microservice based on the plain Java Client Libraries API. When I did a presentation for the Engineering Community of Practice about that prototype, a colleague in the audience pointed out to me, the approval data would be available in the Reportable REST API. So I checked and they where right.

This made the microservice I had done part of the final solution unnecessary. The usage of the Reportable REST API had several additional advantages. It did not require its own application server, no updates for newer versions. Authentication, security, role based access was all supported. The solution was easier, cheaper, faster.

Although the documentation for the Reportable REST Service is quite good, I think some hints and examples might be useful.

Root URL

Assuming PublicURI being the public URI of the CCM server e.g. https://elm.example.com:9443/ccm the URL for the EWM Reportable REST API is

PublicURI + '/rpt/repository'

Supported Resources

The EWM Reportable REST API supports the following resource types.

  • foundation: Common artifacts such as project areas, team areas, contributors, iterations and links
  • scm: Source Control artifacts such as streams and components, as well as stream sizing deltas
  • build: Build artifacts such as build results, build result contributions, build definitions, and build engines
  • apt: Agile Planning artifacts such as team capacity and resource schedules and absences
  • workitem: Work Item artifacts such as work items, categories, severities, and priorities

For each resource name ResourceType from the selection above, the URL is

PublicURI + '/rpt/repository/' + ResourceType

As an example for the workitem resource the URL is

https://elm.example.com:9443/ccm/rpt/repository/workitem

Trying to GET the URL above does not return any detailed data. The reason is, that the properties/attributes to display are not yet specified.

Resource Schema

For any of the supported resources a schema can be requested by a HTTP GET on the resource type URL of the resource type and the query parameter
?metadata=schema appended. As an example the GET below gets the schema for the work item resource type (no header required).

GET https://elm.example.com:9443/ccm/rpt/repository/workitem?metadata=schema

The schema information sent back looks like below.

Part of the work item resource type schema.

Please understand the Common Properties and the elements available for all the resource types by checking the wiki page Reportable REST API.

Please also check the Examples. The reportable REST API provides a query language that allows to select items based on certain criteria that are based on the schema.

As an example this query below finds the work item with the Id 1 and provides the id and the summary property for the work item.

https://elm.example.com:9443/ccm/rpt/repository/workitem?fields=workitem/workItem[id=1]/(id|summary)

The part workitem/workItem selects all work items. The part [id=1] selects the work item with id 1. Removing this term would query for all work items. The section /(id|summary) selects the work item properties/attributes id and summary to be returned. The image below shows this executed.

Execution of a query for the work item with id 1.

Paging

The reportable REST API supports paging. The documentation for EWM/RTC does not document how, but The DNG Reportable Rest API does.

The pagination supports these two query parameter to set the size and the size as well as the position (controlling the page).

size=10

size=10&pos=10

By default the pagination is set to 100, but other values are supported. The query parameter has to be added with a prefix ? or &, dependent on the parameters position in the URL.

The response data provides the URL for the next page. The reference is sent in the first block (see the blue box above). Please note that you can not use the URL as it is. It is necessary to url decode the URL first. The image below shows the URLs with paging information. The URL QueryURI is called. The code then gets the nextPage URL from the result, URL decodes it, and executes the next page.

Code to get the next page from the query. Page size is set to 10.

Please note that the URL for the next page contains a reference (id=_7dgCcJl2Eey2fKi1TcCeOA) to the previous query that can be used to call the next page. The URL in the call below, that shows this, was urldecoded from the response shown above.

GET https://elm.example.com:9443/ccm/rpt/repository/workitem?id=_7dgCcJl2Eey2fKi1TcCeOA&fields=workitem/workItem/(id)&size=10&pos=10

Nested Property/Attribute Data

The properties/attributes to be displayed can be nested. Below is a more complex query that gets approval data for the work item 1 and displays the details about the approval data:

GET https://elm.example.com:9443/ccm/rpt/repository/workitem?fields=workitem/workItem[id=1]/(id|summary|approvalDescriptors/(id|typeIdentifier|typeName|name|cumulativeStateIdentifier|cumulativeStateName|dueDate|approvals/(stateIdentifier|stateDate|stateName|approver/(name)|approvalDescriptor/(id))))

The query selects work item with id 1. For the selected work item(s) it returns the properties/attributes work item id, the summary and the approval descriptors. For the approval descriptors it returns the id, typeIdentifier, the typeName, name, cumulativeStateIdentifier, cumulativeStateName, dueDate and the approvals. For the approvals within, it returns the stateIdentifier, stateDate, stateName, the approvers and the approvalDescriptors. For the approvers it returns the user name. For the approvalDescriptors the ID is returned.

The / behind an item type refers to an instance of that item type. The term in brackets () specifies which attributes should be returned in the result. The attributes are separated by |. If an attribute is a complex type it can be referred to with a nested / and a specification which attributes to return in a nested () statement.

See the work item examples for more choices.

The image below shows a part of the complex values returned by the query above.

The complex nested structure of the query above.

The image below shows the work item approval data the query reads.

Work Item Approval data.

It is obvious you can query and create complex data sets that can be used for reporting, publishing and other uses.

Summary

This concludes my mini blog series about EWM OSLC and REST APIs. As usual I hope that I am able to help someone out there and make their work easier. IF you have suggestions and feedback, please leave a comment.

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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.