Page History

...

Panel

panelIconId	atlassian-info
panelIcon	:info:
bgColor	#DEEBFF

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

#FFFFFFexpand

Panel

panelIconId

atlassian-note

panelIcon

:note:

bgColor

Info

Integration API is available on sfapp.almarise.com

title	How do I know where my data is stored?

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:

Jira project ID: one of the easiest ways to identify the project ID is to use API:

https://

eu

your-

sfapp

domain.

almarise.com/integration/app

atlassian.net/rest/api/

v1/secure-field/value/{issueId}

https://us-sfapp.almarise.com/integration/app/rest/api/v1/secure-field/value/{issueId}

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.

3/project.

How to determine your data location:

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

Image Added

Get Value

Panel

bgColor	#DEEBFF

GETGET/integrationintegration/appapp/restrest/apiapi/v1v1/secure-fieldfield/valuevalue/{issueId}

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

Expand

title	Parameters

issueId - id of the issue OR issue key.

Expand

title	Response example

Code Block

theme	RDark

[
    {
        "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

Panel

bgColor	#E3FCEF

POST/integrationintegration/appapp/restrest/apiapi/v1v1/secure-fieldfield/valuevalue/{issueId}

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

...

Expand

title	Parameters

issueId - id of the issue OR issue key.

Expand

title	Request body

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:

Code Block

languagetheme	jsonRDark

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

...

Expand

title	Response example

Code Block

theme	RDark

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

Get History

Panel

bgColor	#DEEBFF

GET/integrationintegration/appapp/restrest/apiapi/v1v1/secure-fieldfield/historyhistory/{issueId}

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

Expand

title	Parameters

issueId - id of the issue OR issue key.

page - number of a page

size - number of items on a page

...

Expand

title	Response example

Code Block

theme	RDark

{
    "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

Panel

bgColor	#E3FCEF

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.

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

Expand

title	Request body

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

Expand

title	Secure number

UI

REST

Image Added

Code Block

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

Expand

title	Secure text

UI

REST

Image Added

Code Block

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

Expand

title	Secure date

UI

REST

Image Added

Code Block

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

Expand

title	Secure group

UI

REST

Image Added

Code Block

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

Expand

title	Secure list

UI

REST

Image Added

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

Expand

title	Secure user

UI

REST

Image Added

Code Block

{
    "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 within	string (example: 10000)
page	the number of the search result page to be shown	integer (example: 0)
numberOfIssuesOnPage	number of the issues to be displayed per page	integer (example: 20)
sort	sorting the search results by the field
criteriaList*	list of search criteria
customFieldId*	Id of the secure field to search	string (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 search	string (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)

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

Expand

title	Response example

Code Block

theme	RDark




[
    {
        "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

Status

colour	Green
title	200

- OK. Returned if the request is successful.

Status

colour	Yellow
title	401

- Unauthorized.

Status

colour	Yellow
title	403

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

Status

colour	Yellow
title	404

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

Status

colour	Yellow
title	500

- Server Error.

Page tree

Versions Compared

Old Version 23

New Version Current

Key

Endpoints

Get Value

Update Value

Get History

Search for secure fields

JQL operators

Responses