Synchronisations

This chapter focuses on synchronisations.

get Get all synchronisations by project

A GET to /projects/{id}/synchronisations returns all the synchronisations that the client is allowed to read.

HTTP request

GET /api/rest/latest/projects/14/synchronisations?page=1&size=2 HTTP/1.1
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

sort

which attributes of the returned entities should be sorted on (optional)

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2620

{
  "_embedded" : {
    "synchronisations" : [ {
      "_type" : "synchronisation",
      "id" : 1,
      "server_name" : "BugtrackerDemo",
      "server_id" : 3,
      "name" : "tata",
      "activated" : false,
      "synchronisation_path" : "/Test Project-1/demo2",
      "select_type" : "BOARD",
      "select_value" : "Tableau XS",
      "additional_JQL" : "",
      "restricted_to_active_sprint" : false,
      "sprint_synchronisation_activated" : false,
      "last_sync_date" : "2020/03/27 10:20",
      "last_successful_sync_date" : "2020/03/27 10:20",
      "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
      "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
      "last_status" : "SUCCESS",
      "status" : "SUCCESS",
      "project_id" : 14,
      "project_name" : "Test Project-1",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/synchronisations/1"
        }
      }
    }, {
      "_type" : "synchronisation",
      "id" : 2,
      "server_name" : "BugtrackerDemo2",
      "server_id" : 3,
      "name" : "toto",
      "activated" : false,
      "synchronisation_path" : "/Test Project-1/demo2",
      "select_type" : "BOARD",
      "select_value" : "Tableau XS",
      "additional_JQL" : "",
      "restricted_to_active_sprint" : false,
      "sprint_synchronisation_activated" : true,
      "sprint_synchronisation_path" : "/Test Project-1/sprint-sync",
      "sprint_additional_JQL" : "",
      "sprint_restricted_to_active_sprint" : false,
      "last_sync_date" : "2020/03/27 10:20",
      "last_successful_sync_date" : "2020/03/27 10:20",
      "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
      "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
      "last_status" : "SUCCESS",
      "status" : "SUCCESS",
      "project_id" : 14,
      "project_name" : "Test Project-1",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/synchronisations/2"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/14/synchronisations?page=0&size=2"
    },
    "prev" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/14/synchronisations?page=0&size=2"
    },
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/14/synchronisations?page=1&size=2"
    },
    "last" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/14/synchronisations?page=1&size=2"
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 4,
    "totalPages" : 2,
    "number" : 1
  }
}

Response fields

Path Type Description

_embedded.synchronisations

Array

the list of elements for that page

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the client is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

get Get synchronisation

A GET to /synchronisations/{id} returns the synchronisation with the given id.

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}
Parameter Description

id

the id of the synchronisation

HTTP request

GET /api/rest/latest/synchronisations/3 HTTP/1.1
Accept: application/json
Host: localhost:8080

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 947

{
  "_type" : "synchronisation",
  "id" : 3,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 123,
  "name" : "tata",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "Tableau XS",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "/Test Project-1/sprint-sync",
  "sprint_additional_JQL" : "",
  "sprint_restricted_to_active_sprint" : false,
  "last_sync_date" : "2020/03/27 10:20",
  "last_successful_sync_date" : "2020/03/27 10:20",
  "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/3"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the entity

_type

String

the type of the entity

server_name

String

name of the bug-tracker used for the current synchronisation

server_id

Number

id of the bug-tracker used for the current synchronisation

name

String

name of the synchronisation

activated

Boolean

synchronisation is enabled/disabled

synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM

select_type

String

select type

select_value

String

select value

additional_JQL

String

JQL script

restricted_to_active_sprint

Boolean

restrict requirement synchronisation to active sprint

sprint_synchronisation_activated

Boolean

sprint synchronisation is enabled/disabled

sprint_synchronisation_path

String

directory where the synchronized sprints are saved in SquashTM (only present if sprint_synchronisation_activated is true)

sprint_additional_JQL

String

JQL script for synchronized sprints (only present if sprint_synchronisation_activated is true)

sprint_restricted_to_active_sprint

Boolean

restrict sprint synchronisation to active sprint (only present if sprint_synchronisation_activated is true)

last_sync_date

String

last synchronisation date (server timezone)

last_successful_sync_date

String

last successful synchronisation date (server timezone)

last_sync_on

String

last synchronisation date (full ISO-8601 format, UTC)

last_successful_sync_on

String

last successful synchronisation date (full ISO-8601 format, UTC)

last_status

String

last status

status

String

status

project_id

Number

id of the project where the current synchronisation is configured

project_name

String

name of the project where the current synchronisation is configured

_links

Object

related links

Links

Relation Description

self

link to this synchronisation

post Create synchronisation

A POST to /projects/{id}/synchronisations creates a new synchronisation.

HTTP request

POST /api/rest/latest/projects/14/synchronisations HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 419
Host: localhost:8080

{
  "server_id" : 14,
  "name" : "demoSynchro",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "Tableau XS",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "My path/for sprints",
  "sprint_additional_JQL" : "additional JQL",
  "sprint_restricted_to_active_sprint" : true
}

Path parameters

Table 1. /api/rest/latest/projects/{id}/synchronisations
Parameter Description

id

the id of the project

Request fields

Path Type Description

server_id

Number

id of the bug tracker used for the current synchronisation (mandatory)

name

String

name of the synchronisation (mandatory)

activated

Boolean

whether the synchronisation is enabled or not

synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM (mandatory)

select_type

String

select type (mandatory)

select_value

String

select value (mandatory)

restricted_to_active_sprint

Boolean

restrict requirement synchronisation to active sprint

sprint_synchronisation_activated

Boolean

sprint synchronisation is enabled/disabled

sprint_synchronisation_path

String

directory where the synchronized sprints are saved in SquashTM (mandatory if sprint_synchronisation_activated is true)

sprint_additional_JQL

String

JQL script for synchronized sprints

sprint_restricted_to_active_sprint

Boolean

restrict sprint synchronisation to active sprint (mandatory if sprint_synchronisation_activated is true)

Query parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 896

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "demoSynchro",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "Tableau XS",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "My path/for sprints",
  "sprint_additional_JQL" : "additional JQL",
  "sprint_restricted_to_active_sprint" : true,
  "last_sync_date" : "never",
  "last_successful_sync_date" : "never",
  "last_sync_on" : null,
  "last_successful_sync_on" : null,
  "last_status" : "NEVER_EXECUTED",
  "status" : "NEVER_EXECUTED",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

the id of the entity

server_name

String

name of the bug tracker used for the current synchronisation

server_id

Number

id of the bug tracker used for the current synchronisation

name

String

name of the synchronisation

activated

Boolean

enable/disable synchronisation

select_type

String

select type

select_value

String

select value

additional_JQL

String

JQL script

synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM

restricted_to_active_sprint

Boolean

restrict requirement synchronisation to active sprint

sprint_synchronisation_activated

Boolean

sprint synchronisation is enabled/disabled

sprint_synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM (only present if sprint_synchronisation_activated is true)

sprint_additional_JQL

String

JQL script for synchronized sprints (only present if sprint_synchronisation_activated is true)

sprint_restricted_to_active_sprint

Boolean

restrict sprint synchronisation to active sprint (only present if sprint_synchronisation_activated is true)

last_sync_date

String

last synchronisation date (since it is just created, it will always be 'never')

last_successful_sync_date

String

last successful synchronisation date (since it is just created, it will always be 'never')

last_sync_on

Null

last synchronisation date (since it is just created, it has not been synchronized yet)

last_successful_sync_on

Null

last successful synchronisation date ((since it is just created, it has not been synchronized yet)

last_status

String

last status (since it is just created, it will always be 'NEVER_EXECUTED')

status

String

status (since it is just created, it will always be 'NEVER_EXECUTED')

project_id

Number

id of the project where the current synchronisation is configured

project_name

String

name of the project where the current synchronisation is configured

_links

Object

related links

Links

Relation Description

self

link to this synchronisation

patch Modify requirement synchronisation

A PATCH to /synchronisations/{id} modifies synchronisation with the given id. Only name, select value and additional JQL (both related to requirement synchronisation) can be modified. To modify sprint synchronisation, use the next endpoint PATCH to /synchronisations/{id}/sprints. Warning, if a board name ('select value') is updated here, it will also be updated for the associated sprints synchronisation (if any). This may impact the synchronisation perimeter.

HTTP request

PATCH /api/rest/latest/synchronisations/4 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 92
Host: localhost:8080

{
  "name" : "UpdateDemoSynchro",
  "select_value" : "tab Update",
  "additional_JQL" : ""
}

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 815

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "UpdateDemoSynchro",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "tab Update",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : false,
  "last_sync_date" : "2020/03/27 10:20",
  "last_successful_sync_date" : "2020/03/27 10:20",
  "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

post Create a sprint synchronisation

A POST to /synchronisations/{id}/sprints add a new sprint synchronisation configuration to an existing synchronisation with the given id. This endpoint can be used only if there is not already a sprint synchronisation configuration for given synchronisation. To update an existing sprint synchronisation configuration, use the following endpoint: PATCH to /synchronisations/{id}/sprints.

HTTP request

POST /api/rest/latest/synchronisations/4/sprints HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 208
Host: localhost:8080

{
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "The sprint/synchro/path",
  "sprint_additional_JQL" : "sprint additional JQL",
  "sprint_restricted_to_active_sprint" : true
}

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}/sprints
Parameter Description

id

the id of the synchronisation

Request fields

Path Type Description

sprint_synchronisation_activated

Boolean

sprint synchronisation is enabled/disabled (mandatory with value at true)

sprint_synchronisation_path

String

directory where the synchronized sprints are saved in SquashTM (mandatory)

sprint_additional_JQL

String

JQL script for synchronized sprints (optional)

sprint_restricted_to_active_sprint

Boolean

restrict sprint synchronisation to active sprint (mandatory)

Query parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 990

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "UpdateDemoSynchro",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "The board",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "/Test Project-1/The sprint/synchro/path",
  "sprint_additional_JQL" : "sprint additional JQL",
  "sprint_restricted_to_active_sprint" : true,
  "last_sync_date" : "2024/03/30 10:20",
  "last_successful_sync_date" : "2024/03/30 10:20",
  "last_sync_on" : "2024-03-30T09:20:00.000+00:00",
  "last_successful_sync_on" : "2024-03-30T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

the id of the entity

server_name

String

name of the bug tracker used for the current synchronisation

server_id

Number

id of the bug tracker used for the current synchronisation

name

String

name of the synchronisation

activated

Boolean

enable/disable synchronisation

select_type

String

select type

select_value

String

select value

additional_JQL

String

JQL script

synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM

restricted_to_active_sprint

Boolean

restrict requirement synchronisation to active sprint

sprint_synchronisation_activated

Boolean

sprint synchronisation is enabled/disabled

sprint_synchronisation_path

String

directory where the synchronized requirements are saved in SquashTM

sprint_additional_JQL

String

JQL script for synchronized sprints

sprint_restricted_to_active_sprint

Boolean

restrict sprint synchronisation to active sprint

last_sync_date

String

last synchronisation date

last_successful_sync_date

String

last successful synchronisation date

last_sync_on

String

last synchronisation date (since it is just created, it has not been synchronized yet)

last_successful_sync_on

String

last successful synchronisation date

last_status

String

last status

status

String

status

project_id

Number

id of the project where the current synchronisation is configured

project_name

String

name of the project where the current synchronisation is configured

_links

Object

related links

Links

Relation Description

self

link to this synchronisation

patch Modify sprint synchronisation

A PATCH to /synchronisations/{id}/sprints modifies synchronisation with the given id. Only the sprint additional JQL can be modified. To modify the rest of the synchronisation’s configuration, use the previous endpoint: PATCH to /synchronisations/{id}, and to create a new sprint synchronisation configuration, use the endpoint POST to /synchronisations/{id}/sprints.

HTTP request

PATCH /api/rest/latest/synchronisations/4/sprints HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 62
Host: localhost:8080

{
  "sprint_additional_JQL" : "the new additional JQL query"
}

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}/sprints
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 986

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "UpdateDemoSynchro",
  "activated" : false,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "The board",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : true,
  "sprint_synchronisation_path" : "/Test Project-1/sprint-sync",
  "sprint_additional_JQL" : "the new additional JQL query",
  "sprint_restricted_to_active_sprint" : false,
  "last_sync_date" : "2024/03/30 10:20",
  "last_successful_sync_date" : "2024/03/30 10:20",
  "last_sync_on" : "2024-03-30T09:20:00.000+00:00",
  "last_successful_sync_on" : "2024-03-30T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

patch Activate/deactivate synchronisation

A PATCH to /synchronisations/{id}/activate with a request parameter enable=true or enable=false activates or deactivates the synchronisation with the given id.

HTTP request

PATCH /api/rest/latest/synchronisations/4/activate?enabled=true HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}/activate
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 805

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "DemoSynchro",
  "activated" : true,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "Tableau",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : false,
  "last_sync_date" : "2020/03/27 10:20",
  "last_successful_sync_date" : "2020/03/27 10:20",
  "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

get Launch Synchronisation

A GET to /synchronisations/{id}/synchronize launch synchronisation project

HTTP request

GET /api/rest/latest/synchronisations/4/synchronize HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}/synchronize
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 808

{
  "_type" : "synchronisation",
  "id" : 4,
  "server_name" : "BugtrackerDemo3",
  "server_id" : 14,
  "name" : "demoSynchro",
  "activated" : true,
  "synchronisation_path" : "/Test Project-1/demo2",
  "select_type" : "BOARD",
  "select_value" : "Tableau XS",
  "additional_JQL" : "",
  "restricted_to_active_sprint" : false,
  "sprint_synchronisation_activated" : false,
  "last_sync_date" : "2020/03/27 10:20",
  "last_successful_sync_date" : "2020/03/27 10:20",
  "last_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_successful_sync_on" : "2020-03-27T09:20:00.000+00:00",
  "last_status" : "SUCCESS",
  "status" : "SUCCESS",
  "project_id" : 14,
  "project_name" : "Test Project-1",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/synchronisations/4"
    }
  }
}

delete Delete synchronisation

A DELETE to /synchronisations/{id} deletes the synchronisation with the given id.

HTTP request

DELETE /api/rest/latest/synchronisations/12 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 204 No Content

delete Delete sprint synchronisation

A DELETE to /synchronisations/{id}/sprints deletes the sprint synchronisation from the synchronisation with the given id.

HTTP request

DELETE /api/rest/latest/synchronisations/12/sprints HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/synchronisations/{id}/sprints
Parameter Description

id

the id of the synchronisation

HTTP response

HTTP/1.1 204 No Content