Monitoring Backbone Issue Sync

If you want to monitor the status of Backbone, e.g. with the monitoring tool of your choice, this information will help you find the corresponding information. The base bath for all rest endpoints is <JIRA_BASE_URL>/plugins/servlet/backbone-issue-sync/api/1/.

REST endpoints

Get all integrations

URL

/integrations

HTTP

GET

Parameters

Name	Description
projectKey	A JIRA project key. Only integrations configured for this project will be returned.
jiraBaseUrl	The base bath of the JIRA instance where the projectKey is defined.

Responses

200 - All integrations of this backbone installation - or matching the projectKey filter.

Example

CODE

[
  {
    "createdUser": "admin",
    "lastModifiedUser": "admin",
    "createdDate": "2016-11-10T11:07:10+0100",
    "lastModifiedDate": "2016-11-10T11:07:10+0100",
    "integrationKey": "INT-16",
    "summary": "Agile Project <> Project B",
    "description": "This integration synchronizes issues between project Agile Project (AP) and project Project B (PB)",
    "status": {
      "status": "STOPPED",
      "firstConnector": {
        "connectorKey": "AP-29",
        "online": true,
        "reconnecting": false,
        "incomingRouteStatus": "STOPPED",
        "incomingProcessingStatus": "IDLE",
        "incomingDetails": "",
        "outgoingRouteStatus": "STOPPED",
        "outgoingProcessingStatus": "IDLE",
        "outgoingDetails": "",
        "externalRouteStatus": "STOPPED",
        "issuesInError": 0
      },
      "secondConnector": {
        "connectorKey": "PB-30",
        "online": true,
        "reconnecting": false,
        "incomingRouteStatus": "STOPPED",
        "incomingProcessingStatus": "IDLE",
        "incomingDetails": "",
        "outgoingRouteStatus": "STOPPED",
        "outgoingProcessingStatus": "IDLE",
        "outgoingDetails": "",
        "externalRouteStatus": "STOPPED",
        "issuesInError": 0
      }
    },
    "firstConnector": {
      "createdUser": "admin",
      "lastModifiedUser": "admin",
      "createdDate": "2016-11-10T11:07:10+0100",
      "lastModifiedDate": "2016-11-10T11:07:10+0100",
      "connectorKey": "AP-29",
      "projectKey": "AP",
      "connection": {
        "application": {
          "baseUrl": "http://localhost:8080",
          "user": "backbone"
        },
        "connector": {
          "sendQueue": {
            "@type": "vm",
            "name": "AP-29_PB-30"
          },
          "receiveQueue": {
            "@type": "vm",
            "name": "PB-30_AP-29"
          },
          "initialInternalPollingDelay": 1000,
          "internalPollingInterval": 1000
        }
      }
    },
    "secondConnector": {
      "createdUser": "admin",
      "lastModifiedUser": "admin",
      "createdDate": "2016-11-10T11:07:10+0100",
      "lastModifiedDate": "2016-11-10T11:07:10+0100",
      "connectorKey": "PB-30",
      "projectKey": "PB",
      "connection": {
        "application": {
          "baseUrl": "http://localhost:8081/jira2",
          "user": "backbone"
        },
        "connector": {
          "sendQueue": {
            "@type": "vm",
            "name": "PB-30_AP-29"
          },
          "receiveQueue": {
            "@type": "vm",
            "name": "AP-29_PB-30"
          },
          "initialInternalPollingDelay": 1000,
          "internalPollingInterval": 1000
        }
      }
    }
  },
  {
    "createdUser": "admin",
    "lastModifiedUser": "backbone",
    "createdDate": "2016-10-10T16:36:31+0200",
    "lastModifiedDate": "2016-10-10T16:44:06+0200",
    "integrationKey": "INT-15",
    "summary": "Some project",
    "description": "This is the integration between Some project and the integration partner.",
    "distributed": true,
    "master": true,
    "partnerProjectType": "business",
    "status": {
      "status": "RUNNING",
      "firstConnector": {
        "connectorKey": "SP-28",
        "startTime": 1484063311224,
        "online": true,
        "reconnecting": false,
        "incomingRouteStatus": "STARTED",
        "incomingProcessingStatus": "IDLE",
        "incomingDetails": "",
        "outgoingRouteStatus": "STARTED",
        "outgoingProcessingStatus": "IDLE",
        "outgoingDetails": "",
        "externalRouteStatus": "STARTED",
        "issuesInError": 0
      }
    },
    "firstConnector": {
      "createdUser": "admin",
      "lastModifiedUser": "backbone",
      "createdDate": "2016-10-10T16:44:06+0200",
      "lastModifiedDate": "2017-01-10T16:48:31+0100",
      "connectorKey": "SP-28",
      "projectKey": "SP",
      "connection": {
        "application": {
          "baseUrl": "http://localhost:8080",
          "user": "backbone"
        },
        "connector": {
          "sendQueue": {
            "@type": "file",
            "path": "INT-15/SEND"
          },
          "receiveQueue": {
            "@type": "file",
            "path": "INT-15/RECEIVE"
          },
          "initialInternalPollingDelay": 1000,
          "internalPollingInterval": 1000
        }
      }
    }
  }
]

Get status of an integration

URL	/integrations/{integrationKey}/status
HTTP	GET

Responses

200 - The status of an integration.

Example

CODE

{
  "status": "RUNNING",
  "firstConnector": {
    "connectorKey": "SSD-38",
    "startTime": 1484063311400,
    "online": true,
    "reconnecting": false,
    "incomingRouteStatus": "STARTED",
    "incomingProcessingStatus": "IDLE",
    "incomingDetails": "",
    "outgoingRouteStatus": "STARTED",
    "outgoingProcessingStatus": "IDLE",
    "outgoingDetails": "",
    "externalRouteStatus": "STARTED",
    "issuesInError": 0
  },
  "secondConnector": {
    "connectorKey": "AP-39",
    "startTime": 1484063311530,
    "online": true,
    "reconnecting": false,
    "incomingRouteStatus": "STARTED",
    "incomingProcessingStatus": "IDLE",
    "incomingDetails": "",
    "outgoingRouteStatus": "STARTED",
    "outgoingProcessingStatus": "IDLE",
    "outgoingDetails": "",
    "externalRouteStatus": "STARTED",
    "issuesInError": 0
  }
}

404 - If the integration cannot be found.

Please note that this REST API may be extended/changed any time although we give our best to not introduce any breaking changes.

Important Folders

Backbone generates change messages for every update of an issue in JIRA. This change message is then transferred to the other project (which could be another server in a distributed configuration) and will then be applied in the target JIRA. The Backbone folder structure is defined as you can see here. It is placed in the folder JIRA_HOME/data/backbone-issue-sync.

Folder Name	Description
default
INT-?	All data about one integration is inside the folder with the key of the integration which you can get via the "Get all integrations" endpoint or from the address bar of your browser when viewing the details of an integration.
PRJ-?	This folder corresponds to the project which is integrated. The question mark will be a number which makes this project key unique. For centralized configurations there should be two folders, for distributed only one.
RECEIVE	Contains all the received messages. New messages from the other project will arrive in this folder and moved to the corresponding subfolder after analyzing/processing it.
archive	Contains all successfully processed messages. It is safe to delete all messages in this folder.
error	Contains a folder for every issue which has messages in error, e.g. a change has been received but cannot be written since a field is not on the edit screen.
issue-missing	Contains a folder for every issue which is missing. In this folder all messages will be placed which need this issue so that they can get applied, e.g. a message for a subtask and the parent task is not yet synched. As soon as the missing issue has been created, these messages will be processed.
sequence-error	Contains all messages which will not be processed yet because a previous message for this issue has not been processed. As soon as the missing message arrived, these messages will be processed.
offline	Contains messages if the JIRA of this project is offline and the messages could not be applied. As soon as the JIRA is online again, these messages will be processed.
invalid	All files which are no "bac" files and which are placed into the RECEIVE folder will be moved to here.
discard	All messages which have older message sequence ids (e.g. due to a resync message) will be moved here.
SEND	All messages in the send folder will be send out with Backbone.
error	If a message failed to be sent, it will be stored in this folder.