Updating Jira issues using OSLC services

The process to update an existing Jira issue is the following:

(Optional) Execute a GET request, on the Jira issue resource shape URL, to discover the editable properties and allowed values.
Execute a GET request, on the Jira issue OSLC URL, to obtain the current content of the resource.
Add, remove or modify any of the editable properties (including OSLC links) in the content of the issue.
Execute a PUT request, on the Jira issue OSLC URL, to inject the new content.

This page provides guidance on how to change an editable property on a Jira issue but take into account that, in the case of an OSLC link, similar steps may be required in the remote application to create the reverse link targeting the Jira issue (that depends on the nature of the link type and the remote application since some link types are discovered instead of saved if Configuration Management is enabled).

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.

GET the resource shape to discover the editable properties

Since not all Jira issue properties are editable, this step helps to determine those that are. If the PUT request includes changes to a property described as read-only in the resource shape, the change will be silently ignored for such property.

Here is the REST request to obtain the Jira issue resource shape (where the PROJECT variable is the Jira project identifier):

Method: GET
URL: https://SERVER:PORT/rest/oslc/1.0/cm/resourceShape/PROJECT/issue for Change Management or https://SERVER:PORT/rest/oslc/1.0/qm/resourceShape/PROJECT/TestCase for Quality Management (additional QM types are TestPlan, TestExecutionRecord, TestResult and TestScript)
Request Headers:
- Authorization: Jira user and password encoded as BASIC authentication
- Accept: application/rdf+xml
- OSLC-Core-Version: 2.0
Response Status: the HTTP response status
Response Body: An XML stream describing the content of the Jira issue shape, which looks like the following:

<rdf:RDF 
  ...
  <rdf:Description rdf:about="https://SERVER:PORT/rest/oslc/1.0/cm/resourceShape/PROJECT/issue">
    <oslc:name>ChangeRequest</oslc:name>
    <rdf:type rdf:resource="http://open-services.net/ns/core#ResourceShape"/>
    <oslc:property rdf:nodeID="A34"/>
    <oslc:property rdf:nodeID="A0"/>
    ...
  </rdf:Description>
  <rdf:Description rdf:nodeId="A0">
    <oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-many"/>
    <dcterms:description rdf:parseType="Literal">Related to a QM test execution resource.</dcterms:description>
    <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/cm#relatedTestExecutionRecord"/>
    <dcterms:title rdf:parseType="Literal">Related Test Execution Records</dcterms:title>
    <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference"/>
    <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource"/>
    <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
    <oslc:range rdf:resource="http://open-services.net/ns/qm#TestExecutionRecord"/>
    <oslc:name rdf:datatype="http://www.w3.org/2001/XMLSchema#string">relatedTestExecutionRecord</oslc:name>
    <rdf:type rdf:resource="http://open-services.net/ns/core#Property"/>
  </rdf:Description>
  ...
</rdf:RDF>

The properties to observe on each oslc:Property definition are:

Property Definition	Purpose	Value Sample
`dcterms:title`	Identifies the property.	`Due Date`
`dcterms:description`	Defines the function/role of the property.	`Date when the issue should be fixed.`
`oslc:propertyDefinition`	Defines the OSLC identifier to use in the issue content.	`http://atlassian.com/ns/cm#dueDate`
`oslc:readOnly`	Whether the property is not supported for editing.	`true`
`oslc:valueType`	Identifies the value type acceptable by the property.	`http://www.w3.org/2001/XMLSchema#dateTime`
`oslc:occurs`	Identifies how many values the property accepts.	`http://open-services.net/ns/core#Zero-or-one`
`oslc:allowedValue`	List a specific value accepted by the property.	`High` (sample for `jira:priority` property)

Important considerations to have in mind:

The oslc:propertyDefinition is the most important property because it identifies how the property will be listed (or must be specified) in the issue content, although the prefixed format is used there, e.g., jira:dueDate instead of http://atlassian.com/ns/cm#dueDate.
Only the properties that accept a specific set of values will include the oslc:allowedValue property (one per allowed value); e.g., jira:priority or oslc_cm:status. The exceptions to this rule are jira:affectsVersion, jira:fixVersion and jira:components. These properties, even if they do work with a specific set of values, do not include the oslc:allowedValue property unless the header X-oslc-connect-resource-shape-include-all-allowed-values: true is included, the reason: they could have hundreds or thousands of allowed values and including them by default could degrade the performance. It is recommended to check first the value to use/set in Jira before performing the PUT request. A bad request response will be returned if a value other than those is used for those properties.
Even if the oslc:readOnly property says editing is supported for a given property, the edition may be disabled by Jira if the corresponding field is not included in the screen associated with the current issue status (or transition). To ensure the property will be updated, include the corresponding field in such screen or add the following header in the PUT request: X-oslc-connect-resource-edition-skip-screen-checking: true. Take into account that this latter option will disable the screen checking for all fields. Note: the screen checking does not apply to OSLC links properties.
Workflow transitions are supported through the oslc_cm:status property, if the requesting user is allowed to do so and there is a valid transition from the current status value to the new one. Additional properties can be updated along this change but they are limited to the screen checking described above. No OSLC links should be modified during a transition, it is recommended to use two different PUT requests in such case.
Some Jira custom fields are also subject to modification but they are not listed (and not editable) by default in the resource shape unless they are added to the Issue shape in the admin page (mind custom fields listed as Not Supported will be ignored if added to the shape). Once this task is performed, GET the resource shape again to know whether the custom field is oslc:readOnly or not and the right oslc:propertyDefinition to use for updating/setting on an issue if so.

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 (or the proper Quality Management resource URL if the issue is not a Change Request)
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 Status: the HTTP response status
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://open-services.net/ns/cm#ChangeRequest"/>
    <dcterms:type>Task</dcterms:type>
    <jira:affectsVersion>1.0</jira:affectsVersion>
    <jira:priority>High</jira:priority>
    ...
  </rdf:Description>
</rdf:RDF>

Add, remove or modify any of the editable properties (including OSLC links)

Most of the time, the intent is 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://open-services.net/ns/cm#ChangeRequest"/>
    <dcterms:type>Task</dcterms:type>
    ...
    <oslc_cm:implementsRequirement rdf:resource="https://REMOTE-SERVER:REMOTE-PORT/myRemoteApp/myRequirement/IDENTIFIER"/>   	
    <jira:priority>Highest</jira:priority>
    <jira:affectsVersion>2.0</jira:affectsVersion>
    <jira:affectsVersion>3.0</jira:affectsVersion>
    <jira:fixVersion>4.0</jira:fixVersion>
    ...
  </rdf:Description>
</rdf:RDF>

Mind the valid link types depend on the resource type mapped to the issue, refer to the Links across OSLC domains section for details on link types.

Additional (editable) properties can be added/changed. If a property admits multiple values (the oslc:occurs property in the resource shape is either http://open-services.net/ns/core#Zero-or-many or http://open-services.net/ns/core#One-or-many), add an element for each of the values to set (do not separate them by commas) and use the proper oslc:propertyDefinition as stated in the resource shape but in the prefixed form. To remove (or un-set) an editable property, just remove the whole element before submitting the content.

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 (or the proper Quality Management resource URL if the issue is not a Change Request)
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
Response Status: the HTTP response status
Request Body: The XML stream describing the new content of the Jira issue, similar to the one in previous section