Skip to main content
Skip table of contents

Connectors

Please make sure to read the Introduction to the REST API before starting to use it.

This page describes all rest endpoints which are related to one or multiple connectors. A connector is one half of a synchronization, responsible for one project.

MethodURLDescription
POST/connectors/{connectorKey}/resyncTriggers a resync from the given connector to the other connector.
GET/connectors/{connectorKey}/syncInformationReturns an array of sync information (which local issue belongs to which remote issue) for this connector.
POST/connectors/{connectorKey}/syncInformationImports an array of sync information into this connectors sync information.
DELETE/connectors/{connectorKey}/syncInformationDeletes the sync information for a single entry.

How to find the connector key

All endpoints described here need a connector key. You can find the corresponding connector key by using the synchronization endpoints. Inside a synchronization, you can locate two connectorKeys, one for each project.

Detailed description

Trigger a resync

POST /connectors/{connectorKey}/resync

This REST API request mirrors the UI action to trigger a resync, it will force a resynchronization of all issues matching the given JQL.

URL ParameterDescriptionDefaultRequired
connectorKeyThe key of the connector you are interested in.-
(tick)

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity ParameterTypeDescriptionDefaultRequired
jql
stringA JQL query string selecting the issues you want to synchronize. The JQL you already configured in the synchronization will be combined with it.-
fieldMappings
string arrayThis array contains the IDs of all the field mappings which should be considered during the resync. You can get these ids by examining the synchronization configuration you can get via the get synchronization endpoint. You have to use the id value of each fieldmapping.-
(tick)
 
responsibility
booleanThis relates to the advanced setting responsibility if it also should be resynced or not.false
sendStatusField
booleanIf the status field should also be resynced or not - please be aware that you will force the other issue in the current status regardless of the history how the issue transitioned to that state. We recommend to only resync the status in exceptional cases.false

Example Request

CODE
{
    "jql": "component = A",
    "fieldMappings" : ["5f513c5e-49ca-4d26-856f-8fce2d7597e8", "468e9b09-e09d-4d90-ad6a-aa18dc336b4d"],
    "responsibility": false,
    "sendStatusField": false
}


Example Response

The endpoint will return an asynchronous task response, the result of this call can be retrieved via the asynchronous tasks resource.

CODE
{
    "id": "7F000001016A52EDC061ACC436508270",
    "startTimestamp": "Apr 25, 2019 -- 07:17 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "progress": 0,
    "message": "Starting resync for connector CON-2-BP"
}

Get all sync information

GET /connectors/{connectorKey}/syncInformation

Returns an array of sync information (which local issue belongs to which remote issue) for this connector.

URL ParameterDescriptionDefaultRequired
connectorKeyThe key of the connector you are interested in.-(tick)
localIssueKeyThe key of an issue belonging to this project. If specified, only entries matching this local key will be returned.-
remoteIssueKeyThe key of an issue belonging to the partner project. If specified, only entries matching this remote key will be returned.-

Response

The endpoint will return a list of sync information matching your (optionally defined) filter criteria.

CODE
[
  {
    "id": 1,
    "connectorKey": "PA-2",
    "localIssueKey": "PA-1",
    "remoteIssueKey": "PB-1",
    "firstSyncDate": 1495002038742,
    "lastOutgoingChange": 1495002035948,
    "lastChangeSeen": 1495002035948,
    "outgoingMessageSequenceId": 1,
    "lastIncomingChange": 1495002053729,
    "incomingMessageSequenceId": 1,
    "incomingChangesIgnored": false
  },
  {
    "id": 2,
    "connectorKey": "PA-2",
    "localIssueKey": "PA-2",
    "remoteIssueKey": "PB-2",
    "firstSyncDate": 1495002042722,
    "lastOutgoingChange": 1495002040675,
    "lastChangeSeen": 1495002040675,
    "outgoingMessageSequenceId": 1,
    "lastIncomingChange": 1495002058847,
    "incomingMessageSequenceId": 1,
    "incomingChangesIgnored": false
  }
]

Import sync information

POST /connectors/{connectorKey}/syncInformation

Imports all given sync information. This endpoint can be used to set already existing issues in correlation.

URL ParameterDescriptionDefaultRequired
connectorKeyThe key of the connector you are interested in.-(tick)

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity ParameterTypeDescriptionDefaultRequired
localIssueKey
stringThe issue key of this project.-(tick)
remoteIssueKey
stringThe issue key of the partner project-(tick) 
firstSyncDate
longThe time in millis when the first sync happened.
lastOutgoingChange
longThe time in millis when the last change has been sent.
lastChangeSeen
longThe time in millis when the last outgoing change has been checked.
outgoingMessageSequenceId
integerThe sequence id of the last sent message.-
lastIncomingChange
longThe time in millis when the last change has been received.-
incomingMessageSequenceId
integerThe sequence id of the last received message.-
incomingChangesIgnored
booleanDefines if incoming changes should be discarded, e.g. for deleted issues.false

Example Request

CODE
[
  {
    "localIssueKey": "PA-1",
    "remoteIssueKey": "PB-1",
    "firstSyncDate": 1495002038742,
    "lastOutgoingChange": 1495002035948,
    "lastChangeSeen": 1495002035948,
    "outgoingMessageSequenceId": 1,
    "lastIncomingChange": 1495002053729,
    "incomingMessageSequenceId": 1,
    "incomingChangesIgnored": false
  },
  {
    "localIssueKey": "PA-2",
    "remoteIssueKey": "PB-2",
    "firstSyncDate": 1495002042722,
    "lastOutgoingChange": 1495002040675,
    "lastChangeSeen": 1495002040675,
    "outgoingMessageSequenceId": 1,
    "lastIncomingChange": 1495002058847,
    "incomingMessageSequenceId": 1,
    "incomingChangesIgnored": false
  }
]


Example Response

The endpoint will response with a HTTP status 200 OK if the import succeeded.

Delete a sync information entry

DELETE /connectors/{connectorKey}/syncInformation

Deletes a single sync information entry.

URL ParameterDescriptionDefaultRequired
connectorKeyThe key of the connector you are interested in.-(tick)
syncInfoIdThe id of the sync information entry. This can be found via the get endpoint.-(tick)

If you omit the syncInfoId parameter from the URL and only specify connectorKey, then Backbone will remove all sync information for this connector. You can not revert these changes, except if you have a database backup.


Example Result

The endpoint will response with a HTTP status 200 OK if the import succeeded.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.