Download PDF
Download page Connectors.
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
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 | Required |
|---|---|---|---|---|
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
{
"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.
{
"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 /connectors/{connectorKey}/syncInformation
Returns an array of sync information (which local issue belongs to which remote issue) for this connector.
| URL Parameter | Description | Default | Required |
|---|---|---|---|
| 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.
[
{
"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
}
]
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 | Required |
|---|---|---|---|---|
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
[
{
"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 /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 sync information 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.