Home

Awesome

Jama OSLC API

License: MIT Discourse status Gitter

<a title="By Jama Software (crunchbase) [Public domain], via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File%3AJama-Logo.png"><img width="100" height="100" alt="Jama-Logo" src="https://upload.wikimedia.org/wikipedia/commons/f/f0/Jama-Logo.png" /></a>

<pre> </pre>

<a title="OSLC" href="http://oslc.co/"><img height="90" src="images/OSLC_logo-Extended-LT.png" /></a>

Summary

Features

Installation Instructions

Prerequisites

Configuration to enable OAuth (optional)

Running the Jama OSLC API

Getting Started

Explore OSLC Jama resources by viewing them in HTML in your browser. Navigate through OSLC resources as described in the OSLC Core Specification

If OAuth is enabled, access the rootservices resource at http://localhost:8080/jama-oslc-adapter/services/rootservices. If using your browser, you will download a file named rootservices.rdf. This document will show the ServiceProviderCatalog URL, oauthRequestTokenUrl, oauthUserAuthorizationUrl, and oauthAccessTokenUrl, as shown below.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:Description xmlns:ns1="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:ns2="http://purl.org/dc/terms/" xmlns:ns8="http://open-services.net/xmlns/cm/1.0/" xmlns:ns9="http://jazz.net/xmlns/prod/jazz/jfs/1.0/" xmlns:ns10="http://jazz.net/ns/ui#" xmlns:ns11="http://jazz.net/xmlns/prod/jazz/calm/1.0/" xmlns:ns12="http://xmlns.com/foaf/0.1/" ns1:about="http://localhost:8080/jama-oslc-adapter/services//rootservices">
<ns2:title>OSLC Adapter/Jira Root Services</ns2:title>
<ns8:cmServiceProviders ns1:resource="http://localhost:8080/jama-oslc-adapter/services//catalog/singleton"/>
<ns9:oauthRequestTokenUrl ns1:resource="http://localhost:8080/jama-oslc-adapter/services//oauth/requestToken"/>
<ns9:oauthUserAuthorizationUrl ns1:resource="http://localhost:8080/jama-oslc-adapter/services//oauth/authorize"/>
<ns9:oauthAccessTokenUrl ns1:resource="http://localhost:8080/jama-oslc-adapter/services//oauth/accessToken"/>
<ns9:oauthRealmName>Jama</ns9:oauthRealmName>
<ns9:oauthRequestConsumerKeyUrl ns1:resource="http://localhost:8080/jama-oslc-adapter/services//oauth/requestKey"/>
</ns1:Description>

Specify in OAuthClient.java your consumer name, key and secret, as well as oauthRequestTokenUrl, oauthUserAuthorizationUrl, and oauthAccessTokenUrl. Run OAuthClient.java to get a requesttoken. The OAuthClient will then print in the console the following message:

> log4j:WARN No appenders could be found for logger (org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager).
> log4j:WARN Please initialize the log4j system properly.
> log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
> Enter this URL in a browser and run again: http://localhost:8080/jama-oslc-adapter/services/oauth/authorize?oauth_token=bfca9c38-78b3-4848-bfb7-694401e5cc96
> org.eclipse.lyo.client.oslc.OAuthRedirectException
> 	at org.eclipse.lyo.client.oslc.OslcOAuthClient.getResourceInternal(OslcOAuthClient.java:203)
> 	at org.eclipse.lyo.client.oslc.OslcOAuthClient.getResource(OslcOAuthClient.java:113)
> 	at com.jama.oslc.client.OAuthClient.main(OAuthClient.java:28)

Follow the instruction printed in the console:

Enter this URL in a browser and run again: http://localhost:8080/jama-oslc-adapter/services/oauth/authorize?oauth_token=bfca9c38-78b3-4848-bfb7-694401e5cc96

Your url to authorize your token will be different so please use the url as printed in your console and do not copy the url in this readme.

After entering the authorization url in a browser, you will see a login screen where you will be asked to provide your Jama user account credentials to authorize a third-party application to access your OSLC Jama API data on your behalf.

You can reuse the Jama user account credentials defined in config.properties. If your credentials are valid, you should see this message in the browser: Request authorized. Then you can access all resources of the OSLC Jama API as if OAuth was disabled.

Start with the Service Provider Catalog resource (entry point resource) at http://localhost:8080/jama-oslc-adapter/services/serviceProviderCatalog. It will show you the Jama projects exposed by the OSLC API. The ServiceProviderCatalog has links to ServiceProvider resources, one for each Jama project containing an item of type Stakeholder requirement (item type id = 45).

Click on a ServiceProvider resource (e.g. http://localhost:8080/jama-oslc-adapter/services/serviceProvider/Semiconductor_Sample_Set). It describes a Jama project. A ServiceProvider resource has links to Service resources. In the case of the Jama OSLC API, a Service resource has links to a CreationFactory and a QueryCapability resource. As the ServiceProvider resource contains the inline representation of the Service, CreationFRactory and QueryCapability resources, the HTML representation of the ServiceProvider directly resource displays the details of the CreationFaactory and QueryCapability resources. The inline representation of linked resources in the ServiceProvider resource is visible when viewing the RDF representation of the ServiceProvider resource.

Click on a Jama Requirements Query Capability (e.g. http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement). It will display all requirements contained in a a Jama project. Note: it will only display requirements of type "Stakeholder Requirement". Additional requirements types can be exposed by the OSLC API through additional item type-specific query capabilities or through a single query capability exposing all requirements as items with different types. The Jama Requirements Creation Factory resource is primarily used by applications using the OSLC API as a client. The Creation Factory resource therefore does not require an HTML representation. As a reminder, all HTML representations of resources provided by the OSLC API are optional. Only the RDF representation of resources exposed by the OSLC API is mandatory.

Click on an individual Jama Requirement resource (e.g. http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement/3919). It will display the main attributes of a Jama requirement.

Access this web page hosted by the OSLC API to test the OSLC UI Preview. Hover over the link to a Jama requirement to see a UI preview window pop up. The UI Preview window can contain custom information and be formatted in various ways. The window size (height, width, and small vs large preview) information is defined according to the OSLC standard.

Setting the OAuth cookie in Postman

In order to access RDF resources from this API with OAuth enabled, you need to send your OAuth cookie together with the request. This cookie is printed after authenticating your username and password.

<img height="70" src="images/oauth-cookie.PNG" />

In postman, click on the cookie link as shown below.

<img height="100" src="images/cookie-edit.PNG" />

Now find the domain in which the Jama API is running and click on the JSESSIONID cookie. If the domain has various JSESSIONID cookies, find the one that shows path=/jama-oslc-adapter

<img height="200" src="images/cookie-value.PNG" />

After finding the right cookie, please copy the JSESSIONID value shown in the authentication page and replace it in postman.

After saving the cookie, you should be able to access the RDF resources normally.

Testing the OSLC API manually using curl or a REST client

curl with cookie example

curl -H Accept:application/rdf+xml --cookie "JSESSIONID=idx5iZsA8zaRIbZYvrQJ6SNFbqrJ9fph8Lb5fTOk.desktop-ia0coj8" http://localhost:8080/jama-oslc-adapter/services/serviceProviderCatalog

Service Provider Catalog

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/serviceProviderCatalog

Example of Service Provider

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/serviceProvider/Semiconductor_Sample_Set

Example of Query Resource

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement

Example of Resource

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement/3919

Tracked Resource Set (TRS)

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/trs

TRS Base

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/trs/base

Example of TRS ChangeLog

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/trs/changeLog

Jama RDF Vocabulary

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/vocabulary

Jama Requirement Resource Shape

curl -H Accept:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/resourceShapes/Requirement

Example of Jama Requirement Creation Factory

curl -X POST -H Accept:application/rdf+xml -H Content-Type:application/rdf+xml http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement

with this body

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:oslc="http://open-services.net/ns/core#" xmlns:item="http://localhost:8080/jama-oslc-adapter/vocabulary/Requirement#" xmlns:oslc_rm="http://open-services.net/ns/rm#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:jama="http://localhost:8080/jama-oslc-adapter/vocabulary/" > <rdf:Description rdf:about="http://localhost:8080/jama-oslc-adapter/services/Semiconductor_Sample_Set/requirement/9999"> <dcterms:title rdf:parseType="Literal">New Jama Requirement X</dcterms:title> <rdf:type rdf:resource="http://open-services.net/ns/rm#Requirement"/> <dcterms:identifier>9999</dcterms:identifier> <dcterms:description rdf:parseType="Literal">Description of new Jama Requirement X</dcterms:description> <jama:requirement_parentID rdf:parseType="Literal">569</jama:requirement_parentID> <rdf:type rdf:resource="http://localhost:8080/jama-oslc-adapter/vocabulary/Requirement"/> </rdf:Description> </rdf:RDF>

Testing the OSLC API automatically

Open-Source License

A few files are not released under the MIT license but under the Eclipse Distribution and Eclipse Public licenses.

More Documentation