Rate this page:
APIs related to integrating Remote Links data with Jira Software. These APIs are available to Atlassian Connect apps. To use these APIs you must have the Remote Link module in your app's descriptor. Read more about Jira Software modules here.
The Remote Link module allows third-party providers to add a generic link through a public REST API and associate it with Jira issues or services.
Supplied remote link information will be presented in the right sidebar of the new Jira issue view under Releases.
This module also provides actions, which allows users to perform an action on the remote link.
Note that the module key and name are not private and should therefore not contain any sensitive or personally identifiable information.
An example can also be found at jira-data-provider-sample-addon, which has an atlassian-connect.json
.
1 2{ "modules": { "jiraRemoteLinkInfoProvider": { "homeUrl": "https://my-remotelink-provider.com", "logoUrl": "https://my-remotelink-provider.com/images/logo.svg", "documentationUrl": "https://my-remotelink-provider.com/docs/jira-integration", "actions": [ { "actionId": "action-1", "actionLabel": { "value": { "value": "Acknowledge" } }, "templateUrl": "https://my-remotelink-provider.com/ack/{ack-id}" } ], "name": { "value": "My Remote Link Provider" }, "key": "remotelink-integration" } } }
Property | type | Description | Required |
---|---|---|---|
key | string | A key to identify this module. Must match ^[a-zA-Z0-9-]+$ pattern, with a max length of 100 | Yes |
name | object (i18N) | A human readable name. This object supports internationalization. | Yes |
homeUrl | string | URL to the provider’s homepage | Yes |
logoUrl | string | Optional URL to the provider’s logo, which will be displayed in the UI | |
documentationUrl | string | Optional URL to documentation about the provider’s Jira integration | |
actions | object | Optional actions that can be performed by Jira users on the remote link |
Property | type | Description | Required |
---|---|---|---|
actionId | string | A key to identify a specific action. Used for associating a specific Remote link to an action of this ID. The actionId of an action must be unique across all actions. | Yes |
actionLabel | object | The actionLabel of an Action is shown visibly to the User alongside the Remote Link. | Yes |
templateUrl | string | The templateUrl of an Action is a template where strings can be substituted into the URL for a specific Remote Link. Strings used in the templateUrl must be passed in via an attribute map when associating an action with a remote link. | Yes |
Property | type | Description | Required |
---|---|---|---|
value | object (i18n) | The label shown on the UI. This object supports internationalization. | Yes |
POST /rest/remotelinks/1.0/bulk
Update / insert Remote Link data.
Remote Links are identified by their ID, existing Remote Link data for the same ID will be replaced if it exists and the updateSequenceId of existing data is less than the incoming data.
Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are
available within a short period of time, but may take some time during peak load and/or maintenance times.
The getRemoteLinkById
operation can be used to confirm that data has been stored successfully (if needed).
In the case of multiple Remote Links being submitted in one request, each is validated individually prior to submission. Details of which Remote LInk failed submission (if any) are available in the response object.
Only Connect apps that define the jiraRemoteLinkInfoProvider
module can access this resource. This resource
requires the 'WRITE' scope for Connect apps.
Connect app scope required: WRITE
string
All requests must be signed with a Connect JWT token that corresponds to an app installed in Jira.
If the Connect JWT token corresponds to an app that does not define jiraRemoteLinkInfoProvider
module it will be rejected with a 403.
See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations.
JWT \S+
The payload used to submit (update / insert) Remote Link data.
Properties assigned to Remote Link data that can then be used for delete / query operations.
Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system.
Properties are supplied as key/value pairs, a maximum of 5 properties can be supplied, and keys must not contain ':' or start with '_'.
5
Array<RemoteLinkData>
A list of Remote Links to submit to Jira. Each Remote Link may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.
1
Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. It is not considered private information. Hence, it may not contain personally identifiable information.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
curl --request POST \
--url 'https://your-domain.atlassian.com/rest/remotelinks/1.0/bulk' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"properties": {
"accountId": "account-234",
"projectId": "project-123"
},
"remoteLinks": [
{
"schemaVersion": "1.0",
"id": "111-222-333",
"updateSequenceNumber": 1523494301448,
"displayName": "Remote Link #42",
"url": "<string>",
"type": "security",
"description": "Remote Link #42 with more information in this description",
"lastUpdated": "2018-01-20T23:27:25.000Z",
"associations": [
{
"associationType": "issueKeys",
"values": [
"ABC-123",
"ABC-456"
]
}
],
"status": {
"appearance": "inprogress",
"label": "ANOMALOUS"
},
"actionIds": [
"action-111-222-333",
"action-444-555-666"
],
"attributeMap": {}
}
],
"providerMetadata": {
"product": "Opsgenie 6.10.2"
}
}'
Submission accepted. Each submitted Remote Link that is of a valid format will be eventually available in Jira.
Details of which Remote Links were submitted and which failed submission (due to data format problems etc.) are available in the response object.
Content type | Value |
---|---|
application/json |
DELETE /rest/remotelinks/1.0/bulkByProperties
Bulk delete all Remote Links data that match the given request.
One or more query params must be supplied to specify Properties to delete by.
Optional param _updateSequenceNumber
is no longer supported. If more than one Property is provided,
data will be deleted that matches ALL of the Properties (e.g. treated as an AND).
See the documentation for the submitRemoteLinks
operation for more details.
e.g. DELETE /bulkByProperties?accountId=account-123&repoId=repo-345
Deletion is performed asynchronously. The getRemoteLinkById
operation can be used to confirm that data has been
deleted successfully (if needed).
Only Connect apps that define the jiraRemoteLinkInfoProvider
module, and on-premise integrations, can access this resource.
This resource requires the 'DELETE' scope for Connect apps.
Connect app scope required: DELETE
integer
This parameter usage is no longer supported.
An optional _updateSequenceNumber
to use to control deletion.
Only stored data with an updateSequenceNumber
less than or equal to that provided will be deleted.
This can be used help ensure submit/delete requests are applied correctly if issued close together.
If not provided, all stored data that matches the request will be deleted.
int64
Free-form query parameters to specify which properties to delete by. Properties refer to the arbitrary information the provider tagged Remote Links with previously.
For example, if the provider previously tagged a remote link with accountId: "properties": { "accountId": "account-123" }
And now they want to delete Remote Links in bulk by that specific accountId as follows: e.g. DELETE /bulkByProperties?accountId=account-123
string
All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.
If the Connect JWT token corresponds to an app that does not define jiraRemoteLinkInfoProvider
module it will be rejected with a 403.
See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations.
JWT \S+
1 2
curl --request DELETE \
--url 'https://your-domain.atlassian.com/rest/remotelinks/1.0/bulkByProperties'
Delete accepted. Data will eventually be removed from Jira.
A schema has not been defined for this response code.
GET /rest/remotelinks/1.0/remotelink/{remoteLinkId}
Retrieve the currently stored Remote Link data for the given ID.
The result will be what is currently stored, ignoring any pending updates or deletes.
Only Connect apps that define the jiraRemoteLinkInfoProvider
module, and on-premise integrations, can access this resource.
This resource requires the 'READ' scope for Connect apps.
Connect app scope required: READ
string
The ID of the Remote Link to fetch.
255
string
All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.
If the Connect JWT token corresponds to an app that does not define jiraRemoteLinkInfoProvider
module it will be rejected with a 403.
See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations.
JWT \S+
1 2 3
curl --request GET \
--url 'https://your-domain.atlassian.com/rest/remotelinks/1.0/remotelink/{remoteLinkId}' \
--header 'Accept: application/json'
The Remote Link data currently stored for the given ID.
Content type | Value |
---|---|
application/json |
DELETE /rest/remotelinks/1.0/remotelink/{remoteLinkId}
Delete the Remote Link data currently stored for the given ID.
Deletion is performed asynchronously. The getRemoteLinkById
operation can be used to confirm that data has been
deleted successfully (if needed).
Only Connect apps that define the jiraRemoteLinkInfoProvider
module, and on-premise integrations, can access this resource.
This resource requires the 'DELETE' scope for Connect apps.
Connect app scope required: DELETE
string
The ID of the Remote Link to fetch.
255
integer
This parameter usage is no longer supported.
An optional _updateSequenceNumber
to use to control deletion.
Only stored data with an updateSequenceNumber
less than or equal to that provided will be deleted.
This can be used help ensure submit/delete requests are applied correctly if issued close together.
int64
string
All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.
If the Connect JWT token corresponds to an app that does not define jiraRemoteLinkInfoProvider
module it will be rejected with a 403.
See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations.
JWT \S+
1 2
curl --request DELETE \
--url 'https://your-domain.atlassian.com/rest/remotelinks/1.0/remotelink/{remoteLinkId}'
Delete has been accepted. Data will eventually be removed from Jira if it exists.
A schema has not been defined for this response code.
Rate this page: