Skip to main content
Skip table of contents

Integration/Synchronization actions

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

Method

URL

Description

GET

integrations

Returns a list of all Backbone synchronizations in this Jira.

POST

integrations

Creates a new synchronization.

GET

/integrations/{integrationKey}

Returns all details about a single synchronization.

PUT

/integrations/{integrationKey}

Update an existing synchronization.

DELETE

/integrations/{integrationKey}

Deletes a synchronization.

GET

/integrations/{integrationKey}/status

Returns the status of a single synchronization.

GET

/integrations/{integrationKey}/conflicts

Returns all validation conflicts for a single synchronization.

PUT

/integrations/{integrationKey}/start

Starts a single synchronization.

PUT

/integrations/{integrationKey}/stop

Stop a single synchronization.

PUT

/integrations/{integrationKey}/applicationConnection

Updates the base url and sync user credentials of a synchronization.

PUT

/integrations/{integrationKey}/applicationConnection

Updates the proxy settings of a synchronization.

Detailed description

Get all synchronizations

GET /integrations

Retrieve all Backbone synchronizations of this Jira instance.

URL Parameter

Description

Default

Required

projectKey

Key of a Jira project. If defined, only the synchronizations for this project will be returned.

Note: If the user only has project admin permissions, this is a required parameter.    

-

see description

Response

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

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)",
    "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",
    "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
        }
      }
    }
  }
]


Create a synchronization

POST /integrations

Creates a new synchronization.

URL Parameter

Description

Default

Required

none




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

summary

string

The name of the synchronization.

-

(tick)

description

string

A more detailed description of the synchronization.

-


firstConnector.projectKey

string

The key of the project.

 (tick)

firstConnector.connection.application.baseUrl

string

A url to connect via REST to the JIRA instance.

 (tick)

firstConnector.connection.application.user

string 

The synchronization user to use. 

 (tick)

firstConnector.connection.application.password

string

The password for the synchronization user.

-

 (tick)

The secondConnector parameters correspond to the firstConnector ones.

Example Request

CODE
{
  "summary": "Project A <> Project B (REST)",
  "description": "This integration synchronizes issues between project Project A (PA) and project Project B (PB)",
  "firstConnector": {
    "projectKey": "PA",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone",
        "password": "backbone"
      }
    }
  },
  "secondConnector": {
    "projectKey": "PB",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone",
        "password": "backbone"
      }      
    }
  }
}

Example Result

The endpoint will return the synchronization including filled default values, e.g. for the integrationKey and the connectorKeys.

CODE
{
  "createdUser": "admin",
  "lastModifiedUser": "admin",
  "createdDate": "2017-05-17T08:01:37+0200",
  "lastModifiedDate": "2017-05-17T08:01:37+0200",
  "integrationKey": "INT-3",
  "summary": "Project A <> Project B (REST)",
  "description": "This integration synchronizes issues between project Project A (PA) and project Project B (PB)",
  "firstConnector": {
    "createdUser": "admin",
    "lastModifiedUser": "admin",
    "createdDate": "2017-05-17T08:01:37+0200",
    "lastModifiedDate": "2017-05-17T08:01:37+0200",
    "connectorKey": "PA-4",
    "projectKey": "PA",
    "projectConnectorKey": "k15t.backbone.syncinfo.8ddf109d-44d5-41a0-b74e-905d1302c809",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone"
      },
      "connector": {
        "sendQueue": {
          "@type": "file",
          "path": "INT-3/PA-4_to_PB-5"
        },
        "receiveQueue": {
          "@type": "file",
          "path": "INT-3/PB-5_to_PA-4"
        },
        "initialInternalPollingDelay": 1000,
        "internalPollingInterval": 1000
      }
    },
    "configuration": {
      "sync": {
        "outgoingJqls": [],
        "outgoingInterval": "5s",
        "incomingInterval": "5s",
        "automaticConflictResolution": false
      },
      "advanced": {
        "archivedMessagesPerIssue": 2,
        "discardedMessagesPerIssue": 2,
        "sequenceErrorRetries": 5
      },
      "fieldDefaults": [],
      "issueTypeMappings": {
        "incoming": [],
        "outgoing": []
      },
      "fieldMappings": [],
      "workflowMappings": [
        {
          "id": "##GLOBAL##"
        }
      ]
    }
  },
  "secondConnector": {
    "createdUser": "admin",
    "lastModifiedUser": "admin",
    "createdDate": "2017-05-17T08:01:37+0200",
    "lastModifiedDate": "2017-05-17T08:01:37+0200",
    "connectorKey": "PB-5",
    "projectKey": "PB",
    "projectConnectorKey": "k15t.backbone.syncinfo.3545b1cc-bf5e-4305-8b98-b98d356430bc",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone"
      },
      "connector": {
        "sendQueue": {
          "@type": "file",
          "path": "INT-3/PB-5_to_PA-4"
        },
        "receiveQueue": {
          "@type": "file",
          "path": "INT-3/PA-4_to_PB-5"
        },
        "initialInternalPollingDelay": 1000,
        "internalPollingInterval": 1000
      }
    },
    "configuration": {
      "sync": {
        "outgoingJqls": [],
        "outgoingInterval": "5s",
        "incomingInterval": "5s",
        "automaticConflictResolution": false
      },
      "advanced": {
        "archivedMessagesPerIssue": 2,
        "discardedMessagesPerIssue": 2,
        "sequenceErrorRetries": 5
      },
      "fieldDefaults": [],
      "issueTypeMappings": {
        "incoming": [],
        "outgoing": []
      },
      "fieldMappings": [],
      "workflowMappings": [
        {
          "id": "##GLOBAL##"
        }
      ]
    }
  }
}


Get a single synchronization

GET /integrations/{integrationKey}

Retrieve all details about a single Backbone synchronization.

URL Parameter

Description

Default

Required

integrationKey

Key of the Backbone synchronization. You can get this from the "get synchronizations" endpoint.

-

(tick)


Example Response

The endpoint will return all details about the synchronization with the given integrationKey. In this response, you can identify. e.g. the connector keys needed for additional calls to the connector endpoints. Simply locate the connectorKey and check if it starts with your project key to see if you have the right one.

CODE
 {
  "createdUser": "admin",
  "lastModifiedUser": "admin",
  "createdDate": "2017-05-17T07:46:24+0200",
  "lastModifiedDate": "2017-05-17T07:46:24+0200",
  "integrationKey": "INT-2",
  "summary": "Project A <> Project B",
  "description": "This integration synchronizes issues between project Project A (PA) and project Project B (PB)",
  "firstConnector": {
    "createdUser": "admin",
    "lastModifiedUser": "admin",
    "createdDate": "2017-05-17T07:46:24+0200",
    "lastModifiedDate": "2017-05-17T07:46:24+0200",
    "connectorKey": "PA-2",
    "projectKey": "PA",
    "projectConnectorKey": "k15t.backbone.syncinfo.639105c0-0c5c-40c6-91ed-10429b674728",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone"
      },
      "connector": {
        "sendQueue": {
          "@type": "file",
          "path": "INT-2/PA-2_to_PB-3"
        },
        "receiveQueue": {
          "@type": "file",
          "path": "INT-2/PB-3_to_PA-2"
        },
        "initialInternalPollingDelay": 1000,
        "internalPollingInterval": 1000
      }
    },
    "configuration": {
      "sync": {
        "outgoingJqls": [],
        "outgoingInterval": "5s",
        "incomingInterval": "5s",
        "automaticConflictResolution": false
      },
      "advanced": {
        "archivedMessagesPerIssue": 2,
        "discardedMessagesPerIssue": 2,
        "sequenceErrorRetries": 5
      },
      "fieldDefaults": [],
      "issueTypeMappings": {
        "incoming": [],
        "outgoing": []
      },
      "fieldMappings": [],
      "workflowMappings": [
        {
          "id": "##GLOBAL##"
        }
      ]
    }
  },
  "secondConnector": {
    "createdUser": "admin",
    "lastModifiedUser": "admin",
    "createdDate": "2017-05-17T07:46:24+0200",
    "lastModifiedDate": "2017-05-17T07:46:24+0200",
    "connectorKey": "PB-3",
    "projectKey": "PB",
    "projectConnectorKey": "k15t.backbone.syncinfo.d8705c91-4023-4012-9e7e-fcdcf6399df0",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone"
      },
      "connector": {
        "sendQueue": {
          "@type": "file",
          "path": "INT-2/PB-3_to_PA-2"
        },
        "receiveQueue": {
          "@type": "file",
          "path": "INT-2/PA-2_to_PB-3"
        },
        "initialInternalPollingDelay": 1000,
        "internalPollingInterval": 1000
      }
    },
    "configuration": {
      "sync": {
        "outgoingJqls": [],
        "outgoingInterval": "5s",
        "incomingInterval": "5s",
        "automaticConflictResolution": false
      },
      "advanced": {
        "archivedMessagesPerIssue": 2,
        "discardedMessagesPerIssue": 2,
        "sequenceErrorRetries": 5
      },
      "fieldDefaults": [],
      "issueTypeMappings": {
        "incoming": [],
        "outgoing": []
      },
      "fieldMappings": [],
      "workflowMappings": [
        {
          "id": "##GLOBAL##"
        }
      ]
    }
  }
}


Update an existing synchronization

PUT /integrations/{integrationKey}

Update an existing synchronization identified by the integrationKey.

URL Parameter

Description

Default

Required

integrationKey

Key of the Backbone synchronization. You can get this from the "get synchronizations" endpoint.

-

(tick)

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs any (or all) of the following parameters:

Entity Parameter

Type

Description

Default

Required

integrationKey

string

The key of the Backbone synchronization

-

(tick)

summary

string

The name of the synchronization.

-


description

string

A more detailed description of the synchronization.

-


firstConnector.projectKey

string

The key of the project.


firstConnector.connection.application.baseUrl

string

A url to connect via REST to the JIRA instance.


firstConnector.connection.application.user

string 

The synchronization user to use. 


firstConnector.connection.application.password

string

The password for the synchronization user.

-


The secondConnector parameters correspond to the firstConnector ones.

Example Request

CODE
{
  "integrationKey": "INT-2",
  "summary": "Project A <> Project B (REST)",
  "description": "This integration synchronizes issues between project Project A (PA) and project Project B (PB)",
  "firstConnector": {
    "projectKey": "PA",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone",
        "password": "backbone"
      }
    }
  },
  "secondConnector": {
    "projectKey": "PB",
    "connection": {
      "application": {
        "baseUrl": "http://localhost:8510/jira",
        "user": "backbone",
        "password": "backbone"
      }      
    }
  }
}

Example Result

The endpoint will return something like this:

CODE
{
    "id": "7F000001017359F6298874C57A8E9AC5",
    "startTimestamp": "Jul 17, 2020 -- 01:29 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "progress": 0,
    "message": "The task has been started."
}


Delete a synchronization

DELETE /integrations/{integrationKey}

Delete the Backbone synchronization identified by the integrationKey.

URL Parameter

Description

Default

Required

integrationKey

Key of the Backbone synchronization. You can get this from the "get synchronizations" endpoint.

-

(tick)


Response

The endpoint will respond with a HTTP 200 if successful.

Start a synchronization

PUT /integrations/{integrationKey}/start

Starts the synchronization with the given integrationKey asynchronously.

URL Parameter

Description

Default

Required

integrationKey

 Key of the Backbone synchronization.

 -

 (tick)

You don't need to provide a body with your request.

Example Result

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

CODE
{
    "id": "53A90124015DAC398C292BBD70979338",
    "startTimestamp": "Aug 04, 2017 -- 09:50 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task has been started.",
    "resourceLocation": null
}


Stop a synchronization

PUT /integrations/{integrationKey}/stop

Stops the synchronization with the given integrationKey asynchronously.

URL Parameter

Description

Default

Required

integrationKey

 Key of the Backbone synchronization.

 -

 (tick)

You don't need to provide a body with your request.

Example Result

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

CODE
{
    "id": "53A90124015DAC398C292BBD70979338",
    "startTimestamp": "Aug 04, 2017 -- 09:50 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task has been started.",
    "resourceLocation": null
}


Update base url and sync user

PUT /integrations/{integrationKey}/applicationConnection

Asynchronously updates the connection details like base url and sync user credentials. Automatically restarts the synchronization after updating the connection details.

URL Parameter

Description

Default

Required

integrationKey

 Key of the Backbone synchronization.

 -

 (tick)

Example Request

For each side of the synchronization, you have to provide the connection details like base url and the username + password of the sync user. However, please note that you can not update the sync user's username with this request. You can only update the base url and a sync user's password.

CODE
{
  "firstConnector": {
    "baseUrl": "<new base url>",
    "user": "<syncuser username>",
    "password": "<syncuser password>"
  },
  "secondConnector": {
    "baseUrl": "<new base url>",
    "user": "<syncuser username>",
    "password": "<syncuser password>"
  }
}

Example Result

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

CODE
{
    "id": "53A90124015DAC398C292BBD70979338",
    "startTimestamp": "Aug 04, 2017 -- 09:50 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task has been started.",
    "resourceLocation": null
}


Update proxy settings

PUT /integrations/{integrationKey}/applicationConnection

Asynchronously updates the connection proxy settings like proxyUri and proxy credentials. Automatically restarts the synchronization after updating the connection details.

URL Parameter

Description

Default

Required

integrationKey

 Key of the Backbone synchronization.

 -

 (tick)

Example Request

For each side of the synchronization, you have to provide the connection details like base url and the username + password of the sync user. However, please note that you can not update the sync user's username with this request. You can only update the proxy settings. Proxy settings can updated for one of the projects or both of them. In this example we are updating the proxy settings for the first project.

CODE
{
  "firstConnector": {
    "baseUrl": "<new base url>",
    "user": "<syncuser username>",
    "password": "<syncuser password>",
    "proxy": {
       "proxyUri": "<proxy url:port>",
       "username": "<proxy username>",
       "password": "<proxy password>"
    }
  },
  "secondConnector": {
    "baseUrl": "<new base url>",
    "user": "<syncuser username>",
    "password": "<syncuser password>"
  }
}

Example Result

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

CODE
{
    "id": "53A90124015DAC398C292BBD70979338",
    "startTimestamp": "Aug 04, 2017 -- 09:50 AM",
    "finished": false,
    "cancelled": false,
    "hasFailed": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task has been started.",
    "resourceLocation": null
}




JavaScript errors detected

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

If this problem persists, please contact our support.