Breadcrumbs

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.

-

(tick)

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.

-

(tick)

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

Required

connectorKey

The key of the connector you are interested in.

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg

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


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.

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg

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.

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg

remoteIssueKey

string

The issue key of the partner project

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg

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

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg

syncInfoId

The id of the sync information entry. This can be found via the

Connectors

endpoint.

-

https://www.k15t.com/s/en_US/7901/0b59262db6a7cd3dbeee6d1b1416b77c01706b36/_/images/icons/emoticons/check.svg


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.