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 authenticate calls please setup a 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

Jira project ID: one of the easiest ways to identify the project ID is to use API: https://your-domain.atlassian.net/rest/api/3/project.

How to determine your data location:

  1. Go to the Jira issue that contains Secure fields.
  2. Open the Network tab in your browser.
  3. In the console, look for the issue ID.
  4. Place the cursor on the issue ID.

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 OR issue key.

[
    {
        "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 OR issue key.

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 OR issue key.

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
        }
    ]
}

Search for secure fields

POST​/integration/app/rest/api/v1/secure-field/search

The endpoint allows the searching of issues based on secure field values.

Only users with READ permission can utilise the endpoint. 

JQL operators

The availability of search operators varies depending on the type of secure field:

  • Number fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), LESS (<), LESS_EQUAL (<=), GREATER (>), GREATER_EQUAL (>=)

  • Text fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), CONTAIN (~), NOT_CONTAIN (!~)

  • Date fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), LESS (<), LESS_EQUAL (<=), GREATER (>), GREATER_EQUAL (>=)

  • Group fields: NOT_EMPTY, IN, NOT_IN
  • List fields: NOT_EMPTY, IN, NOT_IN
  • User fields: NOT_EMPTY, IN, NOT_IN.

Multiple criteria can be connected using AND operator.

Sorting order can be ASC or DESC.

Use group ID/user ID to search for Secure user and secure group fields.


UI vs. REST call examples for different secure field types:


UIREST 

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 10,
    "sort": {
        "sortField": "Secure Number",
        "order": "ASC"
    },
    "criteriaList": [
        {
            "customFieldId": "65dc98d4e255414216469654",
            "operator": "GREATER",
            "value": 5
        }
    ]
}
UIREST

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 10,
    "sort": {
        "sortField": "Secure Text (multi-line)",
        "order": "ASC"
    },
    "criteriaList": [
        {
            "customFieldId": "66cccbfa6abc1c0d56fe087d",
            "operator": "CONTAIN",
            "value": "localhost"
        }
    ]
}
UIREST

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 20,
    "sort": {
        "sortField": "Secure Date Picker",
        "order": "ASC"
    },
    "criteriaList": [
        {
            "customFieldId": "66cccbfa6abc1c0d56fe086d",
            "operator": "LESS_EQUAL",
            "value": "2024-09-01"
        }
    ]
}
UIREST

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 30,
    "criteriaList": [
        {
            "customFieldId": "65dc98d4e25541421646964c",
            "operator": "NOT_IN",
            "value": "b8a78765-cea8-4a32-ad10-e7df715275ca"
            
        }
    ]
}
UIREST

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 30,
    "criteriaList": [
        {
            "customFieldId": "65dc98d4e25541421646964a",
            "operator": "NOT_EMPTY"
            
        }
    ]
}
UIREST

{
    "projectId": "10076",
    "page": 0,
    "numberOfIssuesOnPage": 10,
    "criteriaList": [
        {
            "customFieldId": "66cccbfa6abc1c0d56fe0875",
            "operator": "IN",
            "value": "712020:51f069c5-053b-4b73-bc53-cf645e017ab7"
            
        }
    ]
}

Request structure

projectId*Id of the project to search withinstring (example: 10000)
pagethe number of the search result page to be showninteger (example: 0)
numberOfIssuesOnPagenumber of the issues to be displayed per pageinteger (example: 20)
sortsorting the search results by the field
criteriaList*list of search criteria
customFieldId*Id of the secure field to searchstring (example: 65f8a3f0be05d471ce104803)
operator*JQL search operator string (example: LESS_EQUAL)
value*the specific secure field's value to search against (example: 5)
jqlFilter (optional)JQL filter to narrow the searchstring (example: created >= -30d)
sessionId unique session Id in UUID4 format generated by the user. Required for performance optimization when loading multiple pages. string (example: c769436b-76a0-4d2e-bed3-47aaa0790eab)

(warning) Changes in criteria or sorting order must have a unique sessionId to obtain correct search results. 

[
    {
        "projectId": "10007",
        "issueId": "13243",
        "issueKey": "SGS-3176",
        "issueTypeId": "10004",
        "summary": "Story 2.0",
        "secureFieldValues": {
            "65f8a3f0be05d471ce104803": "70.0"
        },
        "secureFieldMetaData": {
               "65f8a3f0be05d471ce104803": {
                "customFieldId": "65f8a3f0be05d471ce104803",
                "customFieldName": "Secure Number",
                "issueTypeIds": [
                    "10000",
                    "10004",
                    "10005",
                    "10006",
                    "10007"
                ],
                "fieldType": "SECURE_NUMBER",
                "options": []
            }
        }
    }
]




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.


  • No labels