Integration REST API

This API is dedicated to programmatic integration between Jira and third-party systems, Jira automation, or workflow when JWT is not feasible. In order to to authenticate calls please setup personal access token as described here.

Three request headers must be set beforehand:

email - email address of the user, who will be accessing API
jira-host - address of Jira Cloud instance
api-token - token created by the user who will be accessing the API

Endpoints

Integration API is available on sfapp.almarise.com

How to identify the Jira Issue ID in Cloud

The most straightforward way to determine your data location is to send the API request e.g. GET with the following URLs:

One of them will return status 200 and the other one - 404. This way you will know that your data is stored in the respective location.

Get Value

GET/integration/app/rest/api/v1/secure-field/value/{issueId}

This endpoint allows to get all Secure field values for the given issue. Only users with READ permission can see the secure values.

issueId - id of the issue.

[
    {
        "fieldName": "Secure Number field",
        "fieldType": "SECURE_NUMBER",
        "globalConfigurationId": "64d25ee1ae45d1595276f16a",
        "textFieldValue": null,
        "numberFieldValue": 7654.0,
        "date": null,
        "permissions": {
            "EDIT": true,
            "VIEW": true,
            "HISTORY": true
        },
        "required": false
    }
]

Update Value

POST/integration/app/rest/api/v1/secure-field/value/{issueId}

Endpoint updates all Secure field values for the given issue. Only users with WRITE permission can update values.

GlobalConfigurationId of the Secure field is required and can be obtained by using a GET endpoint described above.

issueId - id of the issue.

Fields with value are mapped to:

textFieldValue - Secure Text Single Line, Secure Text Multi Line
numericFieldValue - Secure Number
dateFieldValue - Secure Date in format "yyyy-MM-dd"
dateTimeFieldValue - Secure Date Time in format "yyyy-MM-dd'T'HH:mm:ss.SSSZ".

Request body example:

[
  {
    "globalConfigurationId": "64d25ee1ae45d1595276f16a",
    "numberFieldValue": 500
    
  }
]

[
    {
        "globalConfigurationId": "64d25ee1ae45d1595276f16a",
        "textFieldValue": null,
        "numberFieldValue": 500.0,
        "dateFieldValue": null,
        "dateTimeFieldValue": null
    }
]

Get History

GET/integration/app/rest/api/v1/secure-field/history/{issueId}

Get Secure fields history records. Only users with HISTORY permission can access the records.

issueId - id of the issue

page - number of a page

size - number of items on a page

{
    "total": 2,
    "page": 0,
    "pageSize": 10,
    "issueId": "10008",
    "items": [
        {
            "authorId": "5e8f9de61c07ed0b7df4063c",
            "secureFieldId": "64d25ee1ae45d1595276f16a",
            "secureFieldName": "Secure Number field",
            "oldValue": "7654.0",
            "newValue": "500.0",
            "created": 1691509448914
        },
        {
            "authorId": "5e8f9de61c07ed0b7df4063c",
            "secureFieldId": "64d25ee1ae45d1595276f16a",
            "secureFieldName": "Secure Number field",
            "oldValue": null,
            "newValue": "7654.0",
            "created": 1691508486073
        }
    ]
}

Responses

200 - OK. Returned if the request is successful.

401 - Unauthorized.

403 - Forbidden. Returned if the user does not have permission to complete this request.

404 - Not Found. Returned if the issue does not exist.

500 - Server Error.

Page tree