These are the public REST services exposed by the XL Release server.

You can access the REST API via a URL of the form http://[host]:[port]/[context-root]/[service-resource].

For example:

GET http://localhost:5516/api/v1/templates/Applications/Release2994650

GET http://localhost:5516/api/v1/templates/Applications/Folder608123241/Folder283360226/Release482440157

Identifiers

You need to know the identifiers that releases, phases, and tasks have in the database. Both templates and releases have an ID of the form Applications/ReleaseXXXXXXXXX, where XXXXXXXXX is a nine-digit number (all IDs start with Applications/ for technical reasons). If you have organized templates and releases in folders, their IDs will be of the form Applications/FolderXXXXXXXXX-FolderXXXXXXXXX-ReleaseXXXXXXXXX.

The fastest way to find the ID of a template or release is to open it in a browser and look at the URL in the location bar. Take the last part of the URL and add the Applications/ prefix. If the template or release is in a folder, you must also replace the hyphens (-) with forward slashes (/).

To get the identifiers of phases and tasks, first do a REST call to get the contents of a release, and then inspect the results to find the IDs.

Authentication

Most resources require authentication. You can use HTTP Basic Authentication.

Error codes

400

Sending an invalid JSON object or a JSON object containing incorrect parameters or values will return a Bad Request response:

Can't parse the following as a JSON object:
[{}]
401

Sending incorrect user/password in the Authorization header will return an Unauthorized response.

402

Having an expired or invalid license will return Payment required response.

403

Trying to access endpoints without all the correct permissions will return a Forbidden response:

Permission template#edit on APPLICATIONS on Applications/Release126975871 is not granted to you.
409

When CIs with the same name exist in the same location, a Conflict error will be returned:

A folder with the title 'Folder 2' already exists under the folder with ID 'Applications'.
500

If the server can’t process your request, an Internal Server Error will be returned.

Topics

Finding templates, releases, phases, tasks

This section describes how to use the XL Release API to retrieve the properties from the main building blocks of the system.

Find template/release by ID

To find a template or release using a specific ID, execute this command:

$ curl 'http://localhost:5516/api/v1/templates/Applications/ReleasesTest/Release1' -i -H 'Accept: application/json'

Using the following parameters

  • for template:

Table 1. /api/v1/templates/{templateId}
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

  • for release:

Table 2. /api/v1/releases/{releaseId}
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains a JSON representation of the template/release:

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

{
  "id" : "Applications/ReleasesTest/Release1",
  "type" : "xlrelease.Release",
  "$token" : "08e46a31-c80d-487b-9f9b-53ebaf9153d2",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:59.518+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:59.518+0100",
  "title" : "Applications/ReleasesTest/Release1",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

Find archived release by ID

To find an archived release using a specific ID, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/archived/Applications/ReleasesTest/Release1' -i -H 'Accept: application/json'

Using the following parameters:

Table 3. /api/v1/releases/archived/{releaseId}
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

You will receive the same response as in Find template/release by ID

Find release by title

Note that you cannot find a template by title.

To find a release using a specific title, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/byTitle?releaseTitle=Find%20me' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

releaseTitle

The title of the release

The response contains a list of releases with the specified title:

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

[ {
  "id" : "Applications/ReleasesTest/Release1",
  "type" : "xlrelease.Release",
  "$token" : "d172e8e0-2cd2-4792-ad22-98b05836397a",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:38.630+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:38.630+0100",
  "title" : "Find me",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ]
} ]

Find phase by ID

To find a phase using a specific ID, execute this command:

$ curl 'http://localhost:5516/api/v1/phases/Applications/ReleasesTest/Release1/Phase1' -i -H 'Accept: application/json'

Using the following parameters:

Table 4. /api/v1/phases/{phaseId}
Parameter Description

phaseId

Full phase identifier; for example, Applications/Release1/Phase2

The response contains the phase as JSON:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1",
  "type" : "xlrelease.Phase",
  "$token" : "165f31cb-7888-461d-9a2a-70862dda2b79",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:36.644+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:36.644+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1",
  "flagStatus" : "OK",
  "tasks" : [ ],
  "release" : "Applications/ReleasesTest/Release1",
  "status" : "PLANNED",
  "color" : "#00FF00"
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

The color of the phase top bar in the UI. Format: #(hex value); for example '#009CDB'

Find task by ID

To find a task using a specific ID, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1' -i -H 'Accept: application/json'

Using the following parameters:

Table 5. /api/v1/tasks/{taskId}
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

The response contains the task as JSON:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "034b66a5-a37f-4f53-b8dd-f2cda6c82e28",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:53.451+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:53.451+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "owner" : "admin",
  "startDate" : "2017-11-10T11:33:53.447+01:00",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

Search phases in a release by title

To find a phase in a release using a specific title, execute this command:

$ curl 'http://localhost:5516/api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/ReleasesTest/Release1' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

phaseTitle

The phase title

releaseId

Full phase identifier; for example, Applications/Release1/Phase2

The response contains a list of phases with the specified title:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Phase1",
  "type" : "xlrelease.Phase",
  "$token" : "df35d7b1-c22e-4ad0-b5dd-aa54c288e783",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:35.854+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:35.854+0100",
  "title" : "find me",
  "flagStatus" : "OK",
  "tasks" : [ ],
  "release" : "Applications/ReleasesTest/Release1",
  "status" : "PLANNED",
  "color" : "#00FF00"
} ]

Search tasks in a release by title

To find a task in a release using a specific title, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/ReleasesTest/Release1' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

taskTitle

The task title

phaseTitle

The phase title

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains a list of tasks with the specified title:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "43a2c0c5-1b5c-4cc7-9057-2dc857955dc1",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:47.293+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:47.293+0100",
  "title" : "find me",
  "owner" : "admin",
  "startDate" : "2017-11-10T11:33:47.288+01:00",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
} ]

Release life cycle

For a detailed description about the release and task life cycle, refer to XL Release documentation

Create a release from template

If you use the API, you cannot create a release without an existing template.

To create a new release from a template, execute this command:

$ curl 'http://localhost:5516/api/v1/templates/Applications/ReleasesTest/Release1/create' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"releaseTitle":"release from api","releaseVariables":{},"releasePasswordVariables":{}}'

Using the following parameters:

Table 6. /api/v1/templates/{templateId}/create
Parameter Description

templateId

Full template identifier; for example, Applications/Release1
Path Type Description

releaseTitle

String

Release title

releaseVariables

Object

Release variables

releasePasswordVariables

Object

Release password variables

If you want to create a release that contains variables, you must specify a value for each variable. For example:

{
  "releaseTitle": "release from api",
  "releaseVariables": {
    "variable1": "value1"
  },
  "releasePasswordVariables": {
    "passwordVariable": "passwordValue"
  }
}
To create and start the release, use /start instead of /create in the curl command.

The response contains the new release.

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

{
  "id" : "Applications/ReleasesTest/Release910243525",
  "type" : "xlrelease.Release",
  "$token" : "2cebf4dd-b68f-4a08-ba8d-edd6883afa55",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:57.813+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:57.813+0100",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2017-11-10T11:33:57.788+01:00",
  "dueDate" : "2017-11-10T13:33:57.788+01:00",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2017-11-10T11:33:57.788+01:00",
  "queryableEndDate" : "2017-11-10T13:33:57.788+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarLinkToken" : "1200235996844148520",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/ReleasesTest/Release1",
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

All the variables in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

Start a planned release

To start a planned release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/start' -i -X POST -H 'Accept: application/json'

Using the following parameters:

Table 7. /api/v1/releases/{releaseId}/start
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

You will receive the same response as in Create a release from template

Get active tasks

To retrieve a list of active tasks from a release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/active-tasks' -i -H 'Content-Type: application/json'

Using the following parameters:

Table 8. /api/v1/releases/{releaseId}/active-tasks
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains a list of active tasks:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "202494e7-79cd-4af6-9b70-2d5dc84213fd",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:45.581+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:45.581+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "startDate" : "2017-11-10T11:33:45.576+01:00",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

[].type

String

This field represents type of 'xlrelease.Task'.

[].title

String

The title of the item.

[].description

String

The description of the item.

[].owner

String

The owner of the item.

[].scheduledStartDate

String

The date that the item is supposed to start.

[].dueDate

String

The date that the item is supposed to end.

[].startDate

String

The actual start date.

[].endDate

String

The actual end date.

[].plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

[].flagStatus

String

Flags indicate that an item needs attention.

[].flagComment

String

The reason the item is flagged.

[].comments

Array

The comments on the task.

[].container

Varies

The phase or task this task is contained in.

[].attachments

Array

List of file attachments on this task.

[].status

String

The state the task is in.

[].team

String

The name of the team this task is assigned to.

[].waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

[].delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

[].precondition

String

A snippet of code that is evaluated when the task is started.

[].failuresCount

Number

The number of times this task has failed.

[].variableMapping

Object

Map from property name to a variable name that replaces that property

[].tags

Array

The tags of the task. Tags can be used for grouping and querying.

Assign a task to a user

To assign a task to a user, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/assign/admin' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json'

Using the following parameters:

Table 9. /api/v1/tasks/{taskId}/assign/{username}
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

username

The user name of the assigned user

The response contains the task as JSON:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "072a3c17-2407-4169-b1ce-83cab4174872",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:55.710+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:55.765+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "owner" : "admin",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

Add a comment to a task

To add a comment to a task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/comment' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment":"Important step in our pipeline"}'

Using the following parameters:

Table 10. /api/v1/tasks/{taskId}/comment
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3
Path Type Description

comment

String

The comment to associate with the action

The response contains the modified task with the added comment:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "5eeaab82-2e2e-44c3-a276-ef199b3da718",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:56.691+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:56.691+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "flagStatus" : "OK",
  "comments" : [ {
    "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/Comment598116776",
    "type" : "xlrelease.Comment",
    "$token" : "e947eab0-eab8-4b7a-ac14-71951660fa44",
    "$createdBy" : "admin",
    "$createdAt" : "2017-11-10T11:33:56.744+0100",
    "$lastModifiedBy" : "admin",
    "$lastModifiedAt" : "2017-11-10T11:33:56.744+0100",
    "text" : "Important step in our pipeline",
    "author" : "admin",
    "date" : "2017-11-10T11:33:56.743+01:00"
  } ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

Complete a task

To complete a task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/complete' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment":"Task completed!"}'

Using the following parameters:

Table 11. /api/v1/tasks/{taskId}/complete
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3
Path Type Description

comment

String

The comment to associate with the action

The response contains the completed task with the added comment.

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "50e1749d-b004-4989-abee-492172065530",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:50.221+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:50.323+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "owner" : "admin",
  "startDate" : "2017-11-10T11:33:50.216+01:00",
  "endDate" : "2017-11-10T11:33:50.311+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "comments" : [ {
    "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/Comment358914156",
    "type" : "xlrelease.Comment",
    "$token" : "9a2d2ced-efb7-408b-8a2a-addd254d4230",
    "$createdBy" : "admin",
    "$createdAt" : "2017-11-10T11:33:50.373+0100",
    "$lastModifiedBy" : "admin",
    "$lastModifiedAt" : "2017-11-10T11:33:50.373+0100",
    "text" : "Task completed!",
    "author" : "admin",
    "date" : "2017-11-10T11:33:50.371+01:00"
  } ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "COMPLETED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

Fail a task

To fail a task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/fail' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment":"Task failed :-("}'

Using the following parameters:

Table 12. /api/v1/tasks/{taskId}/fail
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3
Path Type Description

comment

String

The comment to associate with the action

The response contains the failed task with the added comment:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "180f8fc2-8bcd-4628-82a8-ba2e0f29c481",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:54.521+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:54.613+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "owner" : "admin",
  "startDate" : "2017-11-10T11:33:54.517+01:00",
  "flagStatus" : "OK",
  "comments" : [ {
    "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/Comment984909642",
    "type" : "xlrelease.Comment",
    "$token" : "d809db71-aa22-413c-a404-3d7ff23ce2f1",
    "$createdBy" : "admin",
    "$createdAt" : "2017-11-10T11:33:54.643+0100",
    "$lastModifiedBy" : "admin",
    "$lastModifiedAt" : "2017-11-10T11:33:54.643+0100",
    "text" : "Task failed :-(",
    "author" : "admin",
    "date" : "2017-11-10T11:33:54.642+01:00"
  } ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "FAILED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 1,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

Skip a task

To skip a task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/skip' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment":"Task skipped"}'

Using the following parameters:

Table 13. /api/v1/tasks/{taskId}/skip
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3
Path Type Description

comment

String

The comment to associate with the action

The response contains the skipped task and the added comment:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "e0b04d7c-a133-43da-bbf8-1af132f34991",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:57.161+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:57.244+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "owner" : "admin",
  "startDate" : "2017-11-10T11:33:57.157+01:00",
  "endDate" : "2017-11-10T11:33:57.238+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "comments" : [ {
    "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/Comment99147535",
    "type" : "xlrelease.Comment",
    "$token" : "3f198a7b-c15b-4d49-b017-da8cd8244745",
    "$createdBy" : "admin",
    "$createdAt" : "2017-11-10T11:33:57.276+0100",
    "$lastModifiedBy" : "admin",
    "$lastModifiedAt" : "2017-11-10T11:33:57.276+0100",
    "text" : "Task skipped",
    "author" : "admin",
    "date" : "2017-11-10T11:33:57.274+01:00"
  } ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "SKIPPED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

Start a task that is waiting for input

To start a task that is waiting for input, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/start' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "variables": [  { "key": "title", "value": "value1",  "type": "xlrelease.StringVariable", "id": "Applications\/ReleasesTest\/Release1\/Variable1" } ]}'

Using the following parameters:

Table 14. /api/v1/tasks/{taskId}/start
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3
Path Type Description

variables

Array

List of variables

The response contains the task updated:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.UserInputTask",
  "$token" : "da0bc450-1885-497e-9f55-bcd574879f0d",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:55.161+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:55.284+0100",
  "title" : "This task value1",
  "startDate" : "2017-11-10T11:33:55.281+01:00",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "variables" : [ "Applications/ReleasesTest/Release1/Variable1" ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

variables

Array

List of variables

Abort a release

If a release is in status IN_PROGRESS, you can stop and abort it by using the following command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/abort' -i -X POST -H 'Accept: application/json'

Using the following parameters:

Table 15. /api/v1/releases/{releaseId}/abort
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains the release aborted:

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

{
  "id" : "Applications/ReleasesTest/Release1",
  "type" : "xlrelease.Release",
  "$token" : "00649242-095e-4f56-a030-ba4b9ba05e27",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:38.030+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:38.100+0100",
  "title" : "Running release, don't abort me",
  "endDate" : "2017-11-10T11:33:38.090+01:00",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableEndDate" : "2017-11-10T11:33:38.090+01:00",
  "realFlagStatus" : "OK",
  "status" : "ABORTED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

Building templates and releases

For a details description on templates and releases, refer to Core concepts of XL Release

Templates

Create a template

To create a new template, execute this command:

$ curl 'http://localhost:5516/api/v1/templates/' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1","type":"xlrelease.Release","title":"Applications\/ReleasesTest\/Release1","scheduledStartDate":"2017-11-10T11:33:58.837+01:00","flagStatus":"OK","maxConcurrentReleases":100,"releaseTriggers":[],"teams":[],"memberViewers":[],"roleViewers":[],"attachments":[],"phases":[],"queryableStartDate":"2017-11-10T11:33:58.837+01:00","realFlagStatus":"OK","status":"TEMPLATE","tags":[],"variables":[],"calendarPublished":false,"tutorial":false,"abortOnFailure":false,"allowConcurrentReleasesFromTrigger":true,"runningTriggeredReleasesCount":0,"createdFromTrigger":false,"extensions":[],"$metadata":{"globalVariables":null}}'

Using the following fields:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

The response contains the template JSON:

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

{
  "id" : "Applications/Release269172372",
  "type" : "xlrelease.Release",
  "$token" : "52e03188-dda0-46a2-9b96-12cdfb89acfb",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:58.853+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:58.853+0100",
  "title" : "Applications/ReleasesTest/Release1",
  "scheduledStartDate" : "2017-11-10T11:33:58.837+01:00",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ {
    "id" : "Applications/Release269172372/Team157880396",
    "type" : "xlrelease.Team",
    "teamName" : "Release Admin",
    "members" : [ ],
    "roles" : [ ],
    "permissions" : [ "release#edit", "release#start", "release#reassign_task", "template#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ]
  }, {
    "id" : "Applications/Release269172372/Team61025820",
    "type" : "xlrelease.Team",
    "teamName" : "Template Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "template#edit", "template#view", "template#edit_triggers", "template#edit_security", "template#create_release" ]
  } ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release269172372/Phase73277273",
    "type" : "xlrelease.Phase",
    "$token" : "75e8bfa5-db05-4c69-a6de-b45f225b606f",
    "$createdBy" : "admin",
    "$createdAt" : "2017-11-10T11:33:58.877+0100",
    "$lastModifiedBy" : "admin",
    "$lastModifiedAt" : "2017-11-10T11:33:58.877+0100",
    "title" : "New Phase",
    "flagStatus" : "OK",
    "tasks" : [ ],
    "release" : "Applications/Release269172372",
    "status" : "PLANNED"
  } ],
  "queryableStartDate" : "2017-11-10T11:33:58.837+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "template#view", "template#edit_triggers", "template#edit_security", "template#edit", "template#create_release" ],
      "teams" : [ "Template Owner" ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any
Import a template, serialized in XLR format

You can also import templates that were previously exported using XL Release. Send the .xlr file to /api/v1/templates/import with header Content-type: multipart/form-data. It’s possible to add the query parameter folderId to specify under which folder the template will be imported.

Refer to Release life cycle for more information about starting the release

Phases

The following operations are valid for both templates and releases.

Add a phase to a release

After creating a new template or a release, you can add phases to it. To add a new phase, execute this command:

$ curl 'http://localhost:5516/api/v1/phases/Applications/ReleasesTest/Release1/phase' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1\/Phase1","type":"xlrelease.Phase","title":"Applications\/ReleasesTest\/Release1\/Phase1","flagStatus":"OK","tasks":[],"release":"Applications\/ReleasesTest\/Release1","status":"PLANNED","color":"#00FF00"}'

Using the following parameters:

Table 16. /api/v1/phases/{id}/phase
Parameter Description

id

Full identifier of the template/release; for example, Applications/Release1
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

The color of the phase top bar in the UI. Format: #(hex value); for example '#009CDB'

The response contains the created phase:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase434959404",
  "type" : "xlrelease.Phase",
  "$token" : "bef3586c-4572-477c-9997-85fc8723e214",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:32.578+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:32.578+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1",
  "flagStatus" : "OK",
  "tasks" : [ ],
  "release" : "Applications/ReleasesTest/Release1",
  "status" : "PLANNED",
  "color" : "#00FF00"
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

The color of the phase top bar in the UI. Format: #(hex value); for example '#009CDB'
Update phase in a release

To update a phase in a release or in a template, execute this command:

$ curl 'http://localhost:5516/api/v1/phases/Applications/ReleasesTest/Release1/Phase1' -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1\/Phase1","type":"xlrelease.Phase","title":"new title","flagStatus":"OK","tasks":[],"release":"Applications\/ReleasesTest\/Release1","status":"PLANNED","color":"#FFFF00"}'

Using the following parameters:

Table 17. /api/v1/phases/{phaseId}
Parameter Description

phaseId

Full phase identifier; for example, Applications/Release1/Phase2
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

The color of the phase top bar in the UI. Format: #(hex value); for example '#009CDB'

The response contains the updated phase:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1",
  "type" : "xlrelease.Phase",
  "$token" : "3f4eda3c-30d8-479a-b79a-cf8958daa677",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:34.684+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:34.759+0100",
  "title" : "new title",
  "flagStatus" : "OK",
  "tasks" : [ ],
  "release" : "Applications/ReleasesTest/Release1",
  "status" : "PLANNED",
  "color" : "#FFFF00"
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

The color of the phase top bar in the UI. Format: #(hex value); for example '#009CDB'

Tasks

Add a task in a phase or in another task

To add a new task in a phase or in another task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/tasks' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"null", "type":"xlrelease.UserInputTask","title":"input task"}'

Using the following parameters:

Table 18. /api/v1/tasks/{containerId}/tasks
Parameter Description

containerId

Full identifier of the task container: either a Phase, a ParallelGroup or a SequentialGroup; for example Applications/Release1/Phase2
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the task.
You can use more fields in the request like status, overdueNotified, etc…​

The response contains the created task:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task87989119",
  "type" : "xlrelease.UserInputTask",
  "$token" : "b1e8b7b3-271c-4726-b87a-f1df9134b894",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:48.487+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:48.487+0100",
  "title" : "input task",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "variables" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

variables

Array

List of variables
Add a task to a specific position inside a phase

To add a new task to a specified position, execute this command:

$ curl 'http://localhost:5516/api/v1/phases/Applications/ReleasesTest/Release1/Phase1/tasks?position=0' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1\/Phase1\/Task1","type":"xlrelease.UserInputTask","title":"input task","flagStatus":"OK","comments":[],"container":"Applications\/ReleasesTest\/Release1\/Phase1","attachments":[],"status":"PLANNED","overdueNotified":false,"waitForScheduledStartDate":true,"delayDuringBlackout":false,"hasBeenFlagged":false,"hasBeenDelayed":false,"failuresCount":0,"variableMapping":{},"tags":[]}'

Using the following parameters:

Parameter Description

position

The position in the phase, zero-based; leave empty to add the task to the end of the phase
Table 19. /api/v1/phases/{phaseId}/tasks
Parameter Description

phaseId

Full identifier of the task container: either a Phase, a ParallelGroup or a SequentialGroup; for example Applications/Release1/Phase2
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

The response contains the created task:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task541711990",
  "type" : "xlrelease.UserInputTask",
  "$token" : "7ff6ed91-5a3b-4d90-b7e0-c8492259e1c5",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:33.767+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:33.767+0100",
  "title" : "input task",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "variables" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

variables

Array

List of variables
Update the task for a specific ID

To update a task for a specific ID, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1' -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications/ReleasesTest/Release1/Phase1/Task1", "type":"xlrelease.Task","title":"new title"}'

Using the following parameters:

Table 20. /api/v1/tasks/{taskId}
Parameter Description

taskId

The updated task object; only top-level properties will be updated.
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the task.

The response contains the updated task:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.Task",
  "$token" : "4e69cf1e-ed82-47e2-b596-8e0e5067352f",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:51.052+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:51.202+0100",
  "title" : "new title",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.
Task types

In XL Release each task has a type: some tasks are manual and some tasks can be automatic. See Task types for the list of types and explanation about them.

From the technical point of view there are core task types like: xlrelease.Task, xlrelease.ParallelGroup, and "extension" tasks introduced by the plugins. For the extension tasks the type is always the same: xlrelease.CustomScriptTask. This kind of task always contains a child property called pythonScript which contains the actual type and custom properties of the task. That is also why when you create a new custom task you extend from type xlrelease.PythonScript and not from xlrelease.CustomScriptTask. See Create custom task types. For example, here is a model of a Jenkins build task (showing only important fields):

{
    "id": "Applications/Folder6723679/Release640465921/Phase394617260/Task110995606",
    "type": "xlrelease.CustomScriptTask",
    "pythonScript": {
        "type": "jenkins.Build"
        "id": "Applications/Folder6723679/Release640465921/Phase394617260/Task110995606/PythonScript",
        "jenkinsServer": "Configuration/Custom/Configuration8602147",
        "buildStatus": "SUCCESS",
        "buildNumber": "5"
    }
}

Here is the list of the types that you get in a default installation of XL Release.

Task Task Type Extension Type

Gate

xlrelease.GateTask

-

Manual

xlrelease.Task

-

User Input

xlrelease.UserInputTask

-

Create Release

xlrelease.CreateReleaseTask

-

Jenkins

xlrelease.CustomScriptTask

jenkins.Build

JIRA Create Issue

xlrelease.CustomScriptTask

jira.CreateIssue

JIRA Query

xlrelease.CustomScriptTask

jira.Query

Jira Update Issue

xlrelease.CustomScriptTask

jira.UpdateIssue

Jira Update Issues

xlrelease.CustomScriptTask

jira.UpdateIssues

Jira Update Issues by Query

xlrelease.CustomScriptTask

jira.UpdateIssuesByQuery

Jira Query

xlrelease.CustomScriptTask

jira.Query

Notification

xlrelease.NotificationTask

-

Remote Unix script

xlrelease.CustomScriptTask

remoteScript.Unix

Remote Win script

xlrelease.CustomScriptTask

remoteScript.Windows

Remote Win SSH script

xlrelease.CustomScriptTask

remoteScript.WindowsSsh

Remote Z/os script

xlrelease.CustomScriptTask

remoteScript.Zos

Jython script

xlrelease.ScriptTask

-

Groovy script

xlrelease.GroovyScriptTask

-

Webhook XML

xlrelease.CustomScriptTask

webhook.XmlWebhook

Webhook JSON

xlrelease.CustomScriptTask

webhook.JsonWebhook

XL Deploy

xlrelease.CustomScriptTask

xldeploy.Deploy
Change task type

You can change the type of a task. The target task type can be a core task type such as xlrelease.GateTask or a custom script definition type such as jenkins.Build.

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/changeType?targetType=xlrelease.GateTask' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json'

Using the following parameters:

Parameter Description

targetType

Target task type; for example, targetType=xlrelease.Task or targetType=jenkins.Build
Table 21. /api/v1/tasks/{taskId}/changeType
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

The response contains the updated task:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "type" : "xlrelease.GateTask",
  "$token" : "9a65c469-7043-46a7-bf57-29d65acbf05c",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:49.719+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:49.757+0100",
  "title" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "flagStatus" : "OK",
  "comments" : [ ],
  "container" : "Applications/ReleasesTest/Release1/Phase1",
  "attachments" : [ ],
  "status" : "PLANNED",
  "overdueNotified" : false,
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "conditions" : [ ],
  "dependencies" : [ ]
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.GateTask'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

The task is not started until the scheduledStartDate is reached if set to true.

delayDuringBlackout

Boolean

The task is not started when a blackout period is active.

precondition

String

A snippet of code that is evaluated when the task is started.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

Map from property name to a variable name that replaces that property

tags

Array

The tags of the task. Tags can be used for grouping and querying.

conditions

Array

Conditions

dependencies

Array

Dependencies
Gate tasks
Add a condition to a gate task

To add a condition to a gate task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/conditions' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"title":"this must be true to go on","checked":false}'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

Using the following parameters:

Table 22. /api/v1/tasks/{taskId}/conditions
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

The response contains the created gate condition:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/GateCondition562052538",
  "type" : "xlrelease.GateCondition",
  "$token" : "7112468d-836f-48cf-a451-8e59dfb9a730",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:52.011+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:52.011+0100",
  "title" : "this must be true to go on",
  "checked" : false
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.GateCondition'.

title

String

Title

checked

Boolean

Checked
Update a condition on a gate task

To (un)check the condition on a gate task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/GateCondition1' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"title":"my first condition","checked":true}'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

Using the following parameters:

Table 23. /api/v1/tasks/{conditionId}
Parameter Description

conditionId

Full identifier of the condition; for example, Applications/Release1/Phase2/Task3/GateCondition1

The response contains the updated gate condition:

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

{
  "id" : "Applications/ReleasesTest/Release1/Phase1/Task1/GateCondition1",
  "type" : "xlrelease.GateCondition",
  "$token" : "2de8fdbf-a656-4259-a3f6-f40838e4f83d",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:52.482+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:52.482+0100",
  "title" : "my first condition",
  "checked" : true
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.GateCondition'.

title

String

Title

checked

Boolean

Checked
Delete a condition from a gate task

To delete a condition from a gate task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/GateCondition1' -i -X DELETE

Using the following parameters:

Table 24. /api/v1/tasks/{conditionId}
Parameter Description

conditionId

Full identifier of the condition; for example, Applications/Release1/Phase2/Task3/GateCondition1

You will receive this empty response:

HTTP/1.1 204 No Content
Add a dependency to a gate task

To add a dependency to a gate task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release2/Phase1/Task1/dependencies/Applications/ReleasesTest/Release1/Phase1/Task1' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json'

Using the following parameters:

Table 25. /api/v1/tasks/{taskId}/dependencies/{targetId}
Parameter Description

taskId

Full identifier of the gate task; for example, Applications/Release1/Phase2/Task3

targetId

Full identifier of the release, phase or task that the gate will depend on, or a variable which will resolve to such an identifier. When using a variable you can also combine variables, for example "Applications/${shortReleaseId}". Note that in this case you need to do URL encoding of the variable name.

The response contains the new dependency:

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

{
  "id" : "Applications/ReleasesTest/Release2/Phase1/Task1/Dependency611486883",
  "type" : "xlrelease.Dependency",
  "$token" : "24bf1288-ae7f-4578-9cab-126eae62fa86",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:54.054+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:54.054+0100",
  "gateTask" : "Applications/ReleasesTest/Release2/Phase1/Task1",
  "target" : "Applications/ReleasesTest/Release1/Phase1/Task1",
  "archivedAsResolved" : false
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Dependency'.

gateTask

Varies

The source gate task from the dependency.

target

Varies

The target of the dependency (release, phase, or task).

targetId

String

The target ID of the dependency (when it is filled, the target will be empty).

archivedTargetTitle

String

The target title once it is archived.

archivedTargetId

String

The target ID once it is archived.

archivedAsResolved

Boolean

Shows if the plan item was COMPLETED or ABORTED.
Delete a dependency to a gate task

To delete a dependency to a gate task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/Dependency1' -i -X DELETE

Using the following parameters:

Table 26. /api/v1/tasks/{dependencyId}
Parameter Description

dependencyId

Full identifier of the dependency; for example, Applications/Release1/Phase2/Task3/Dependency0

You will receive this empty response:

HTTP/1.1 204 No Content

Properties

Update template properties

To update the properties of a template, execute this command:

$ curl 'http://localhost:5516/api/v1/templates/Applications/ReleasesTest/Release1' -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1","type":"xlrelease.Release","title":"Applications\/ReleasesTest\/Release1","scheduledStartDate":"2017-11-10T11:33:58.366+01:00","flagStatus":"OK","maxConcurrentReleases":100,"releaseTriggers":[],"teams":[],"memberViewers":[],"roleViewers":[],"attachments":[],"phases":[],"queryableStartDate":"2017-11-10T11:33:58.366+01:00","realFlagStatus":"OK","status":"TEMPLATE","tags":[],"variables":[],"calendarPublished":false,"tutorial":false,"abortOnFailure":false,"allowConcurrentReleasesFromTrigger":true,"runningTriggeredReleasesCount":0,"createdFromTrigger":false,"extensions":[],"$metadata":{"globalVariables":null}}'

Using the following parameters:

Table 27. /api/v1/templates/{templateId}
Parameter Description

templateId

Full template identifier; for example, Applications/Release1
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

The response the updated template:

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

{
  "id" : "Applications/ReleasesTest/Release1",
  "type" : "xlrelease.Release",
  "$token" : "3684b292-5096-4024-b916-bbd8bf8fe3c5",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:58.329+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:58.417+0100",
  "title" : "Applications/ReleasesTest/Release1",
  "scheduledStartDate" : "2017-11-10T11:33:58.366+01:00",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2017-11-10T11:33:58.366+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any
Update release properties

To update the properties of a release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1' -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1","type":"xlrelease.Release","title":"new title","scheduledStartDate":"2017-11-10T11:33:40.812+01:00","dueDate":"2017-11-10T11:33:40.812+01:00","flagStatus":"OK","maxConcurrentReleases":100,"releaseTriggers":[],"teams":[],"memberViewers":[],"roleViewers":[],"attachments":[],"phases":[],"queryableStartDate":"2017-11-10T11:33:40.812+01:00","queryableEndDate":"2017-11-10T11:33:40.812+01:00","realFlagStatus":"OK","status":"PLANNED","tags":[],"variables":[],"calendarPublished":false,"tutorial":false,"abortOnFailure":false,"allowConcurrentReleasesFromTrigger":true,"runningTriggeredReleasesCount":0,"createdFromTrigger":false,"extensions":[],"$metadata":{"globalVariables":null}}'

Using the following parameters:

Table 28. /api/v1/releases/{releaseId}
Parameter Description

releaseId

Full identifier of the releaseToUpdate; for example, Applications/Release1
Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

The response contains the updated release:

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

{
  "id" : "Applications/ReleasesTest/Release1",
  "type" : "xlrelease.Release",
  "$token" : "194b8789-eab0-4a31-a552-ef2ffb837e1a",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:40.801+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:40.883+0100",
  "title" : "new title",
  "scheduledStartDate" : "2017-11-10T11:33:40.812+01:00",
  "dueDate" : "2017-11-10T11:33:40.812+01:00",
  "flagStatus" : "OK",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2017-11-10T11:33:40.812+01:00",
  "queryableEndDate" : "2017-11-10T11:33:40.812+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "$token" : "f3c61336-380b-49d9-83ac-8f7c9acfc304",
      "$createdBy" : "admin",
      "$createdAt" : "2017-11-10T11:33:22.436+0100",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2017-11-10T11:33:27.006+0100",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

The time that the item is supposed to take to complete, in seconds.

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

The triggers that may start a release from a template. (Templates only)

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

The calculated flag status, derived from the flags from the release and its tasks.

status

String

The state the release is in.

tags

Array

The tags of the release. Tags can be used for grouping and querying.

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

Releases automatically abort when a task fails if this property is set to true.

allowConcurrentReleasesFromTrigger

Boolean

If set to false, a trigger can’t create a release if the previous one it created is still running.

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

The credentials of this user are used to run automated scripts in this release.

scriptUserPassword

String

The password of the user that lends his credentials to run the scripts.

extensions

Array

Extensions of this release, e.g. 'Release contents dashboard'

startedFromTaskId

String

The Create Release task from which this release was created, if any

Delete commands for task, template, or release

Delete a task

To delete a task, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1' -i -X DELETE

Using the following parameters:

Table 29. /api/v1/tasks/{taskId}
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

You will receive this empty response:

HTTP/1.1 204 No Content
Delete template

To delete a template, execute this command:

$ curl 'http://localhost:5516/api/v1/templates/Applications/ReleasesTest/Release1' -i -X DELETE

Using the following parameters:

Table 30. /api/v1/templates/{templateId}
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

You will receive this empty response:

HTTP/1.1 204 No Content
Delete release
To delete a release, it must be in aborted or done status.

To delete a release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1' -i -X DELETE

Using the following parameters:

Table 31. /api/v1/releases/{releaseId}
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

You will receive this empty response:

HTTP/1.1 204 No Content
You cannot delete a phase from a template or release.

Folders

In XL Release folders can be used to organize templates and releases. You can operate with folders using the Folders API.

Listing the root folders

To list the root folders, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/list?depth=4' -i -H 'Accept: application/json'

You receive a response containing a list of folders:

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

[ {
  "id" : "Applications/Folder795016273",
  "type" : "xlrelease.Folder",
  "$token" : "f3145b9e-c87b-48e0-91d3-777ed9ed9de3",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:31.582+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:31.582+0100",
  "title" : "Microservices",
  "children" : [ {
    "id" : "Applications/Folder795016273/Folder632119254",
    "type" : "xlrelease.Folder",
    "children" : [ ],
    "$metadata" : {
      "security" : {
        "permissions" : [ "template#view", "release#start", "folder#view", "release#edit_security", "release#reassign_task", "folder#edit_security", "release#view", "release#abort", "folder#edit", "template#edit_triggers", "template#edit_security", "release#edit", "template#edit", "template#create_release", "release#edit_task" ],
        "teams" : [ "Folder Owner", "Template Owner", "Release Admin" ]
      }
    }
  } ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "template#view", "release#start", "folder#view", "release#edit_security", "release#reassign_task", "folder#edit_security", "release#view", "release#abort", "folder#edit", "template#edit_triggers", "template#edit_security", "release#edit", "template#edit", "template#create_release", "release#edit_task" ],
      "teams" : [ "Folder Owner", "Template Owner", "Release Admin" ]
    }
  }
} ]

All the folders in the response and their description and properties:

Path Type Description

[].id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

[].type

String

This field represents type of 'xlrelease.Folder'.

[].title

String

User provided title of the folder

[].children

Array

Sub-folders of this folder

Creating folders

You can create a new sub-folder under any folder, including the Applications root folder.

For example, to create a top-level folder titled "New folder", execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications' -i -X POST -H 'Content-Type: application/json' -d '{"id":null,"type":"xlrelease.Folder","title":"New folder","children":[]}'

Using the following parameters:

Path Type Description

id

Null

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.Folder'.

title

String

User provided title of the folder

children

Array

Sub-folders of this folder

You receive the created folder as a response containing its normal fields.

Listing folders inside another folder

To receive a list of all the folders that are contained by another folder, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder104417770/list' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

depth

The (optional) depth to search for; defaults at 1

permissions

The (optional) boolean to decorate the folders with the effective permissions; defaults with false

page

The (optional) page of results to return; defaults at 0

resultsPerPage

The (optional) the number of results per page; defaults at 50
Table 32. /api/v1/folders/{folderId}/list
Parameter Description

folderId

The parent folder to retrieve from

Find a folder

You can search for folders by title using nested paths. To find a folder using a specific title, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/find?byPath=Microservices/QA' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

byPath

The path for the folder to search on

depth

The (optional) depth to search for; defaults at 1

Get folder

To find a folder using a specific folder ID, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder683502819/Folder700545036' -i -H 'Accept: application/json'

Using the following parameters:

Table 33. /api/v1/folders/{folderId}
Parameter Description

folderId

The id of the folder
Parameter Description

depth

The (optional) depth to search for; defaults at 1

Templates and releases

You can retrieve templates and releases within specific folders.

To find templates in a folder, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder173905993/Folder69927750/templates' -i -H 'Accept: application/json'

If you want to search for releases, use /releases instead of /templates at the end of the URL

Using the following parameters:

Table 34. /api/v1/folders/{folderId}/templates
Parameter Description

folderId

The id of the folder
Parameter Description

depth

The (optional) depth to search for; defaults at 1

page

The (optional) page of results to return; defaults at 0

resultsPerPage

The (optional) the number of results per page; defaults at 50

Move templates

Templates can be moved from one folder to another folder. Because folders have their own permissions, you can use an optional parameter called mergePermissions to merge source folder and target folder permissions.

To move a template from one folder to another, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder410285770/templates/Applications/Folder871626640/Release1' -i -X POST -H 'Accept: application/json'

Using the following parameters:

Table 35. /api/v1/folders/{folderId}/templates/{templateId}
Parameter Description

folderId

The target folder the template will be moved to

templateId

The id of the template to be moved

Add folder inside folder

To create nested folders, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder430413425' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id":null,"type":"xlrelease.Folder","title":"QA","children":[]}'

Using the following parameters:

Table 36. /api/v1/folders/{folderId}
Parameter Description

folderId

The id of the folder to create the folder in

Delete folders

To delete a folder, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder764139516' -i -X DELETE

Using the following parameters:

Table 37. /api/v1/folders/{folderId}
Parameter Description

folderId

The id of the folder to delete

Move folders

To move folders inside another folder, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder539420140/move?newParentId=Applications/Folder904859291' -i -X POST -H 'Accept: application/json'

Using the following parameters:

Table 38. /api/v1/folders/{folderId}/move
Parameter Description

folderId

The id of the folder to move
Parameter Description

newParentId

The id of the parent folder the folder will be moved under

Note that you cannot move a folder if it contains active releases or templates with active triggers.

Rename folders

To rename a folder, execute this command:

$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder559792654/rename?newName=Microservices%20II' -i -X POST -H 'Accept: application/json'

Using the following parameters:

Table 39. /api/v1/folders/{folderId}/rename
Parameter Description

folderId

The id of the folder to move
Parameter Description

newName

The new name of the folder

Working with variables

For a detailed description about variables, refer to Variables in XL Release

Types of variables

Table 40. Variables
Variable XL-Release type Example value

String

xlrelease.StringVariable

"Hello variable"

Boolean

xlrelease.BooleanVariable

False

Integer

xlrelease.IntegerVariable

1

List string

xlrelease.ListStringVariable

["first","second"]

Map string string

xlrelease.MapStringStringVariable

<"Key","value">

Set string

xlrelease.SetStringVariable

("unique","value")

Password

xlrelease.PasswordStringVariable

"myH4x0rP455w0rd"

CRUD on variables

Variables on release or templates

The following operations are available for both templates and releases. You can use either /templates for templates or /releases for releases in each curl command.

List all release/template variables

To get the list of all the variables inside a template or release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/variables' -i -H 'Accept: application/json'

Using the following path parameters:

Table 41. /api/v1/releases/{releaseId}/variables
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains a list of variables:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "76f28597-a94d-447c-8231-df32bc43d775",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:39.731+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:39.731+0100",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "value1"
} ]

All the variables in the response and their description:

Path Type Description

[].id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

The unique name of the variable in the way it is used in template or release, without curly braces

[].requiresValue

Boolean

Shows if an empty value is a valid value for this variable

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

Value of the release variable or default value of the template variable
Find release/template variable by ID

To get the information for only a specific variable inside a release or a template, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1' -i -H 'Accept: application/json'

Using the following path parameters:

Table 42. /api/v1/releases/{variableId}
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1

All the fields in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.StringVariable'.

key

String

The unique name of the variable in the way it is used in template or release, without curly braces

requiresValue

Boolean

Shows if an empty value is a valid value for this variable

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

label

String

Label of the variable

description

String

Description of the variable

valueProvider

Varies

Configuration of the variable values provider

value

String

Value of the release variable or default value of the template variable
Create new release/template variable

To add a new variable into your Applications/ReleasesTest/Release1 release: The new variable will contain a String, so make sure the type is xlrelease.StringVariable. Do the following command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/variables' -i -X POST -H 'Content-Type: application/json' -d '{"id":null,"key":"newVar","type":"xlrelease.StringVariable","requiresValue":false,"showOnReleaseStart":false,"value":"new value","label":null,"description":null,"valueProvider":null}'

Using the following path parameters:

Table 43. /api/v1/releases/{releaseId}/variables
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

All the fields in the response and their description:

Path Type Description

key

String

The unique name of the variable in the way it is used in template or release, without curly braces

value

String

Value of the release variable or default value of the template variable

requiresValue

Boolean

Shows if an empty value is a valid value for this variable

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

The response is similar to previous case

Delete new release/template variable

To delete variables, you can execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1' -i -X DELETE -H 'Accept: application/json'

Using the following path parameters:

Table 44. /api/v1/releases/{variableId}
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1

You will receive this empty response:

HTTP/1.1 204 No Content
Update variable

To update a single variable, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1' -i -X PUT -H 'Content-Type: application/json' -d '{"id":"Applications\/ReleasesTest\/Release1\/Variable1","type":"xlrelease.StringVariable","key":"var1","requiresValue":true,"showOnReleaseStart":true,"value":"updated value"}'

Using the following path parameters:

Table 45. /api/v1/releases/{variableId}
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1
Update variables

You can also update several variables in the same request by executing the following command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/variables' -i -X PUT -H 'Content-Type: application/json' -d '[{"id":"Applications\/ReleasesTest\/Release1\/Variable1","type":"xlrelease.StringVariable","key":"var1","requiresValue":true,"showOnReleaseStart":true,"value":"updated value"}]'

Using the following path parameters:

Table 46. /api/v1/releases/{releaseId}/variables
Parameter Description

releaseId

Full identifier of the release; for example, Applications/Release1

The response contains a list of updated variables:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "cb5cb4e4-7e34-4b84-b950-cdaf77a814c5",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:44.430+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:44.500+0100",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "updated value"
} ]

Advanced

Variable values.

To get all the possible values that you can use in an specific variable, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1/possibleValues' -i -H 'Accept: application/json'

Using the following path parameters:

Table 47. /api/v1/releases/{variableId}/possibleValues
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1

The response contains the list of values:

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

[ "value1", "value2", "value3" ]
Verify if a variable is used in a release.

To verify if a variable is used inside a release, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1/used' -i -H 'Accept: application/json'

Using the following path parameters:

Table 48. /api/v1/releases/{variableId}/used
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1

The response contains true if variable is used, false otherwise:

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

false
Replace a variable.

To replace one or more variables, execute this command:

$ curl 'http://localhost:5516/api/v1/releases/Applications/ReleasesTest/Release1/Variable1/replace' -i -X POST -H 'Content-Type: application/json' -d '{"variable":"${var2}","value":"value2"}'

Using the following path parameters:

Table 49. /api/v1/releases/{variableId}/replace
Parameter Description

variableId

Full identifier of the variable; for example, Applications/Release1/Variable1
Path Type Description

variable

String

Variable key with placeholder

value

String

The new value

The response:

HTTP/1.1 204 No Content
Get variables used in a task

To get the variables used inside a task using the TaskApi, execute this command:

$ curl 'http://localhost:5516/api/v1/tasks/Applications/ReleasesTest/Release1/Phase1/Task1/variables' -i -H 'Accept: application/json'

With the following path parameters:

Table 50. /api/v1/tasks/{taskId}/variables
Parameter Description

taskId

Full identifier of the task; for example, Applications/Release1/Phase2/Task3

The response contains a list with the variables used in the task:

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

[ {
  "id" : "Applications/ReleasesTest/Release1/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "9bc94d4d-7461-4c5d-b2aa-370cfe0c7a25",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:48.942+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:48.942+0100",
  "key" : "title",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "value1"
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

The unique name of the variable in the way it is used in template or release, without curly braces

[].requiresValue

Boolean

Shows if an empty value is a valid value for this variable

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

Value of the release variable or default value of the template variable

Global variables

List global variables

To list all the global variables, execute this command:

$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global' -i -H 'Accept: application/json'

The response contains all the global variables defined in the system:

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

[ {
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "b902eb15-2b32-4a80-8f20-d92a6bd8d866",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:26.184+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:26.184+0100",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "value"
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

The unique name of the variable in the way it is used in template or release, without curly braces

[].requiresValue

Boolean

Shows if an empty value is a valid value for this variable

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

Value of the release variable or default value of the template variable
Find global variable by ID

To obtain a specific global variable, execute this command:

$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' -i -H 'Accept: application/json'

Using the following path parameters:

Table 51. /api/v1/config/{variableId}
Parameter Description

variableId

Full identifier of the global variable; for example, Configuration/variables/global/Variable1

The response contains the global variable:

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

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "92c00f76-2f8e-43a4-ba1b-f181ea350912",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:24.564+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:24.564+0100",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "value"
}
Create global variable

To add new global variable, execute this command:

$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global' -i -X POST -H 'Content-Type: application/json' -d '{"id":null,"key":"global.newVar","type":"xlrelease.StringVariable","requiresValue":false,"showOnReleaseStart":false,"value":"new value","label":null,"description":null,"valueProvider":null}'

All the variables in the response and their description:

Path Type Description

key

String

The unique name of the variable in the way it is used in template or release, without curly braces

value

String

Value of the release variable or default value of the template variable

requiresValue

Boolean

Shows if an empty value is a valid value for this variable

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

The response contains the added global variable:

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

{
  "id" : "Configuration/variables/global/Variable251632349",
  "type" : "xlrelease.StringVariable",
  "$token" : "af148e33-2d64-4fad-bf44-d0f36ee0f304",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:25.373+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:25.373+0100",
  "key" : "global.newVar",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value"
}
Update global variable

To update a global variable, execute this command:

$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' -i -X PUT -H 'Content-Type: application/json' -d '{"id":"Configuration\/variables\/global\/Variable1","type":"xlrelease.StringVariable","key":"global.var1","requiresValue":false,"showOnReleaseStart":false,"value":"updated value"}'

Using the following path parameters:

Table 52. /api/v1/config/{variableId}
Parameter Description

variableId

Full identifier of the global variable; for example, Configuration/variables/global/Variable1

All the variables in the response and their description:

Path Type Description

id

String

This field contains ID of object. It is required but not used on update operations. When creating objects just send 'null'.

type

String

This field represents type of 'xlrelease.StringVariable'.

key

String

The unique name of the variable in the way it is used in template or release, without curly braces

requiresValue

Boolean

Shows if an empty value is a valid value for this variable

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

label

String

Label of the variable

description

String

Description of the variable

valueProvider

Varies

Configuration of the variable values provider

value

String

Value of the release variable or default value of the template variable

The response contains the updated global variable:

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

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "$token" : "070be500-48c4-40be-a489-fad3aae24ea5",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:25.774+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:25.836+0100",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "updated value"
}
Delete global variable

To delete a global variable, execute this command

$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' -i -X DELETE

Using the following path parameters:

Table 53. /api/v1/config/{variableId}
Parameter Description

variableId

Full identifier of the global variable; for example, Configuration/variables/global/Variable1

You will receive this empty response:

HTTP/1.1 204 No Content

Searching for configuration objects

The Configuration API allows you to search for configuration objects using the following url:

$ curl 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server' -i -H 'Accept: application/json'

Using the following parameters:

Parameter Description

configurationType

Type of the Configuration object

title

The title of the Configuration object

The response contains a list of configuration objects that match the criteria:

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

[ {
  "id" : "Configuration/Custom/Configuration82469137",
  "type" : "jira.Server",
  "$token" : "8dc8444c-3db6-4147-819f-510912769e59",
  "$createdBy" : "admin",
  "$createdAt" : "2017-11-10T11:33:26.643+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2017-11-10T11:33:26.643+0100",
  "title" : "my JIRA server"
} ]