Creating links on Jira issues using OSLC services

The process to create an OSLC link on a Jira issue is the following:

1. Execute a GET request on the Jira issue OSLC URL to obtain the current content of the resource.
2. Modify in memory the content of the issue to add a new link to a target resource.
3. Execute a PUT request on the Jira issue OSLC URL to inject the new content.

This page provide guidance on how to add a unidirectional link from a Jira issue to a remote OSLC resource. The same process is to apply to create the reverse link in the remote OSLC resource to target the Jira issue.

To execute those REST requests, you are free to use the REST library of your choice. You may use the MDAccess for OSLC library to ease the execution of requests, as demonstrated in Running OSLC snippets on Jira section.

Authentication

OSLC Connect for Jira supports BASIC authentication, so that you can easily execute REST services using the Jira user and password of your choice in the Authorization request header.

GET the resource

Here is the REST request to obtain the Jira issue as an OSLC resource:

• Method: GET
• URL: https://SERVER:PORT/rest/oslc/1.0/cm/issue/ISSUE
• Request Headers:
  • Authorization: Jira user and password encoded as BASIC authentication
  • Accept: application/rdf+xml
  • OSLC-Core-Version: 2.0
• Response Headers:
  • ETag: resource version identifier
• Response Body: An XML stream describing the content of the Jira issue, which looks the following:

<rdf:RDF 
  ...
  <rdf:Description rdf:about="https://SERVER:PORT/rest/oslc/1.0/cm/issue/ISSUE">
    <dcterms:title rdf:parseType="Literal">Test</dcterms:title>
    <rdf:type rdf:resource="http://atlassian.com/ns/cm#Issue"/>
    <rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
    ...
  </rdf:Description>
</rdf:RDF>

Modify the resource content in memory

The intent is now to add a link targeting an OSLC remote resource in this XML content.

If for example the Jira issue is to implement a requirement, the link type to use is http://open-services.net/ns/cm#implementsRequirement and the new resource content should be something like:

<rdf:RDF 
  ...
  <rdf:Description rdf:about="https://SERVER:PORT/rest/oslc/1.0/cm/issue/ISSUE">
    <dcterms:title rdf:parseType="Literal">Test</dcterms:title>
    <rdf:type rdf:resource="http://atlassian.com/ns/cm#Issue"/>
    <rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
    ...
    <oslc_cm:implementsRequirement rdf:resource="https://REMOTE-SERVER:REMOTE-PORT/myRemoteApp/myRequirement/IDENTIFIER"/>
    ...
  </rdf:Description>
</rdf:RDF>

Refer to the Links across OSLC domains section for details on link types.

PUT the resource

Here is the REST request to update the content of the Jira issue:

• Method: PUT
• URL: https://SERVER:PORT/rest/oslc/1.0/cm/issue/ISSUE
• Request Headers:
  • Authorization: Jira user and password encoded as BASIC authentication
  • Accept: application/rdf+xml
  • OSLC-Core-Version: 2.0
  • If-Match: The value of the ETag header received in the GET response
• Request Body: The XML stream describing the new content of the Jira issue, similar to the one in previous section

HTTP Status

Each HTTP response has an associated HTTP status that can either be:

• HTTP 200: the request was successfully executed.
• HTTP 400: the request is invalid, the response body should contain information on the root cause.
• HTTP 401: the authentication failed, probably because the user name and password do not match an existing user in Jira.
• HTTP 403: the authentication succeeded but you don't have permission to read or update the Jira issue
• HTTP 404: the resource is not found, which may mean the identifier does not resolve an existing Jira issue (e.g. it has been deleted).
• HTTP 500: an error occurred on server side, contact your Jira administrator to check Jira's log files to identify the root cause.