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.

Method	URL	Description
POST	/connectors/{connectorKey}/resync	Triggers a resync from the given connector to the other connector.
GET	/connectors/{connectorKey}/syncInformation	Returns an array of sync information (which local issue belongs to which remote issue) for this connector.
POST	/connectors/{connectorKey}/syncInformation	Imports an array of sync information into this connectors sync information.
DELETE	/connectors/{connectorKey}/syncInformation	Deletes 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 Parameter	Description	Default	Required
connectorKey	The key of the connector you are interested in.	-

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

Entity Parameter	Type	Description	Default
jql	string	A 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 array	This 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.	-
responsibility	boolean	This relates to the advanced setting responsibility if it also should be resynced or not.	false
sendStatusField	boolean	If 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 Parameter	Description	Default
connectorKey	The key of the connector you are interested in.	-
localIssueKey	The key of an issue belonging to this project. If specified, only entries matching this local key will be returned.	-
remoteIssueKey	The 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 Parameter	Description	Default	Required
connectorKey	The key of the connector you are interested in.	-

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

Entity Parameter	Type	Description	Default
localIssueKey	string	The issue key of this project.	-
remoteIssueKey	string	The issue key of the partner project	-
firstSyncDate	long	The time in millis when the first sync happened.	-
lastOutgoingChange	long	The time in millis when the last change has been sent.	-
lastChangeSeen	long	The time in millis when the last outgoing change has been checked.	-
outgoingMessageSequenceId	integer	The sequence id of the last sent message.	-
lastIncomingChange	long	The time in millis when the last change has been received.	-
incomingMessageSequenceId	integer	The sequence id of the last received message.	-
incomingChangesIgnored	boolean	Defines 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 Parameter	Description	Default	Required
connectorKey	The key of the connector you are interested in.	-
syncInfoId	The id of the sync information entry. This can be found via the get endpoint.	-

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.