[update] Accessing Custom Jira Fields via OSLC
OSLC Connect for Jira supports the standard shapes for OSLC Change Management objects. This allows users to use the standard identifiers to extract values for reports, searches, or other integrations. However, what if you want to use custom Jira fields in your reports. How would you consider doing this? And how would your tooling understand this new attribute?
The answer for this is Resource Shapes. In OSLC, this is the type definition for an object. This effectively describes the attributes and the types of attributes for a resource. In practice, this defines what attributes are available for an artifact for every Jira Issue in a particular Scheme.
Updating the Jira Resource Shape
The standard artifact shape attributes can be found in the OSLC Connect for Jira help. (https://help.sodius.cloud/help/topic/com.sodius.oslc.app.jira.doc/html/admin/server/trsFeeds.html?cp=0_0_1_0_2_3_0 ). However, we know users use extended attributes so we enable users to extend the types and we will describe below how to discover the ids to access them with remote tools.
With OSLC Connect for Jira, administrators can update the attributes included in the issue shape. This is done on a Jira Scheme level and modified in the Jira Administration for OSLC Connect.
On this page, users can add additional Jira fields in the issue shape. Note that not all fields are supported and presented on the Jira form. More details are defined in the product help → https://help.sodius.cloud/help/topic/com.sodius.oslc.app.jira.doc/html/admin/server/issueShapes.html?cp=0_0_1_0_4_3
When this is updated, the next time the Shape is requested, or an artifact is requested, the extended attributes will be available for that scheme. If you have multiple schemes, each will need to be updated.
With tools like Report Builder, you will access the attribute's name. For other tools, users will need to request and review the shape and artifact data to guide their tool definitions.
Accessing the Resource Shape
OSLC interactions are common web interactions. If a tool or a user wants to access a resource shape they only need to request the shape document and read the contents. Many tools will do this automatically to aid in reporting, however, we occasionally need to access these directly.
We recommend that uses use a REST tool like Insomnia or Postman to interact with their server, however we will also show a command line cURL example to access the resources.
To access the resource shape we need to perform a GET on ‘/rest/oslc/1.0/cm/resourceShape/projectId/issue’ with a header ‘Accept: application/rdf+xml’. You will also need to be authorized to do this operation.
In cURL you would do the following:
curl --header "Accept: application/rdf+xml" -u userId:userPassword --request GET --url https://jira-7-detroit.sodius.cloud:8443/rest/oslc/1.0/cm/resourceShape/10101/issue
To update for your environment you will need to update
userId and userPassword
replace jira-7-detroit.sodius.cloud:8443 with your Jira base URL
replace 10101 with the Id of your Jira project
When using Insomnia you will see the desired XML document describing all of the attributes.
For example, one of the standard attributes is Created and is described as follows:
Or with the custom attribute that we added above, Sprint, can be seen as:
What a user can observe is that the ‘dcterms:title’ provides the attribute name from Jira. If we want to find the attribute on an actual Jira issue we would want to use the ‘oslc:propertyDefintion’ value. In this case we would expect the XML+RDF for a Jira Issue to include a node for “http://atlassian.com/ns/cm-x#customfield_10104” and this would be the Jira sprint value.
By retrieving the Issue Shape document, a user has all the information necessary to access the attribute in the Jira Issue Resource.
Accessing the Issue Resource
OSLC interactions are common web interactions. If a tool or a user wants to access an issue resource they only need to request the document and read the contents. Many tools will do this automatically to aid in reporting, however, we occasionally need to access these directly.
We recommend that uses use a REST tool like Insomnia or Postman to interact with their server, however we will also show a command line cURL example to access the resources.
To access the issue resource we need to perform a GET on ‘/rest/oslc/1.0/cm/issue/issueId’ with a header ‘Accept: application/rdf+xml’. You will also need to be authorized to do this operation.
In cURL you would do the following:
curl --header "Accept: application/rdf+xml" -u userId:userPassword --request GET --url https://jira-7-detroit.sodius.cloud:8443/rest/oslc/1.0/cm/issue/AMRCM-19
To update for your environment you will need to update
userId and userPassword
replace jira-7-detroit.sodius.cloud:8443 with your Jira base URL
replace AMRCM-19 with the Id of your Jira Issue
When using Insomnia you will see the desired XML document describing all of the attributes of your issue.
When looking for the “Created” value from the resource shape, we can observe the following:
This shows how the oslc:propertyDefinition is used. The dcterms:created is equivalent http://purl.org/dc/terms/created from the namespace prefix for dcterms representing http://purl.org/dc/terms/. This is using the namespace definition in the XML document:
We can also find our custom Sprint attribute in the same way.
You will notice the jira_x prefix on all the custom Jira attributes, and the associated namespace definition. This matches what we found in the resource shape document. You can use this to validate that on an issue you can observe the attributes you expect and the format they are available in.
Note, the shape document is always available via the instanceShape reference on the ticket. When looking at the Issue, you can always look up the attribute definitions.
This is how a tool can combine the data from the ticket information and the shape document to retrieve and render the attributes on a Jira artifact via these OSLC documents.
Using this in Polarion Tables
One of the main usages for this information would be to add Jira information to tables or reports in Polarion. All the existing documents apply to creating the tables. However, if you were to add the Sprint information to the table, you would modify your configuration from the example to the following:
<?xml version="1.0" encoding="UTF-8"?>
<remote-attributes-configurations>
<remote-attributes-configuration remoteOslcType="oslc_cm:ChangeRequest">
<attribute label="Jira Id" oslc="dcterms:identifier"/>
<attribute label="Jira Status" oslc="oslc_cm:status" visible="true"/>
<attribute label="Priority" oslc="jira:priority" visible="true"/>
<attribute label="Sprint" oslc="jira_x:customfield_10104" visible="true"/>
</remote-attributes-configuration>
</remote-attributes-configurations>Note the addition of the jira_x and the usage of the id information for Sprint using the jira_x prefix.
To use ‘jira_x’ it must be added to the namespaces used in the OSLC Semantics in the Global Configuration of Polarion.
Navigate to the Default Repository in Polarion and the Linked Data Semantics
Make sure ‘jira_x’ is defined in the namespace.
It should be as follows:
<namespace prefix="jira_x" url="http://atlassian.com/ns/cm-x#"/>