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:

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.
Properties that start with '$' sign are considered internal properties - i.e. may change between product versions. Please do not rely on those properties to be present.

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.

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, send this request:

HTTP Request
GET /api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' \
    '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

roleIds

The flag indicating if the release should be decorated with role ids extension; defaults to false

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

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1167

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "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" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
}

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Find archived release by ID

To find an archived release using a specific ID, send this request:

HTTP Request
GET /api/v1/releases/archived/Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/releases/archived/Applications/Release162151faba694d03aa3065665cf26f21' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/archived/Applications/Release162151faba694d03aa3065665cf26f21' \
    '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, send this request:

HTTP Request
GET /api/v1/releases/byTitle?releaseTitle=Find%20me
Curl
$ curl 'http://localhost:5516/api/v1/releases/byTitle?releaseTitle=Find%20me' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/byTitle?releaseTitle=Find%20me' \
    '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-Language: en
Content-Length: 1125
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Find me",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "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" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
} ]

Find releases by criteria

To find all releases matching a specific search criteria, send this request:

HTTP Request
POST /api/v1/releases/search?page=0&resultsPerPage=100&pageIsOffset=false

{
  "title" : "Find me",
  "tags" : [ "foo", "bar" ],
  "timeFrame" : "LAST_MONTH",
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : "ASC"
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/search?page=0&resultsPerPage=100&pageIsOffset=false' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "Find me",
  "tags" : [ "foo", "bar" ],
  "timeFrame" : "LAST_MONTH",
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : "ASC"
}'
HTTPie
$ echo '{
  "title" : "Find me",
  "tags" : [ "foo", "bar" ],
  "timeFrame" : "LAST_MONTH",
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : "ASC"
}' | http POST 'http://localhost:5516/api/v1/releases/search?page=0&resultsPerPage=100&pageIsOffset=false' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Parameter Description

page

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

resultsPerPage

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

pageIsOffset

The (optional) flag indicating if page is used as offset; defaults to false

The following filters are available to be specified in the request body:

Path Type Description

title

String

Case-insensitive matches the part of the release title

tags

String

Matches the releases containing all of the specified tags

timeFrame

String

The time-frame to search releases in. Valid values: LAST_MONTH, LAST_THREE_MONTHS, LAST_SIX_MONTHS, LAST_YEAR. Specify RANGE to filter by a custom from-to date range

from

Long

Matches the releases with end date after or equal to this date

to

Long

Matches the releases with start date before this date

active

Boolean

Matches the releases with the IN_PROGRESS, FAILED, FAILING or PAUSED status

planned

Boolean

Matches the releases with the PLANNED status

inProgress

Boolean

Matches the releases with the IN_PROGRESS status

paused

Boolean

Matches the releases with the PAUSED status

failing

Boolean

Matches the releases with the FAILING status

failed

Boolean

Matches the releases with the FAILED status

inactive

Boolean

Matches the releases with the COMPLETED or ABORTED status

completed

Boolean

Matches the releases with the COMPLETED status

aborted

Boolean

Matches the releases with the ABORTED status

onlyMine

Boolean

Matches the releases with me as the owner

onlyFlagged

Boolean

Matches the releases which need attention or are at risk

onlyArchived

Boolean

Matches the releases which have been archived

parentId

String

Matches the releases stored under this folder

orderBy

String

The order of the returning set: risk, start_date, end_date, title (only available for templates)

orderDirection

String

The order direction of the returning set: ASC, DESC

The response contains a list of releases matching the criteria:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 1357
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Find me",
  "scheduledStartDate" : "2021-03-15T11:24:15.706+01:00",
  "dueDate" : "2021-03-15T11:24:15.706+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:24:15.706+01:00",
  "queryableEndDate" : "2021-03-15T11:24:15.706+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ "foo", "bar" ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
} ]

Full search releases by criteria

To find all releases matching a specific search criteria grouped by database, send this request:

HTTP Request
POST /api/v1/releases/fullSearch?page=0&resultsPerPage=25&archivePage=0&archiveResultsPerPage=25

{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/fullSearch?page=0&resultsPerPage=25&archivePage=0&archiveResultsPerPage=25' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null
}' | http POST 'http://localhost:5516/api/v1/releases/fullSearch?page=0&resultsPerPage=25&archivePage=0&archiveResultsPerPage=25' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Parameter Description

page

The (optional) page of results to return from the active database; defaults at 0

resultsPerPage

The (optional) the number of results per page; from the active database; defaults at 100

archivePage

The (optional) page of results to return from the archive database; defaults to page

archiveResultsPerPage

The (optional) the number of results per page; from the archive database; defaults to resultsPerPage

The following filters are available to be specified in the request body:

Path Type Description

title

String

Case-insensitive matches the part of the release title

tags

String

Matches the releases containing all of the specified tags

timeFrame

String

The time-frame to search releases in. Valid values: LAST_MONTH, LAST_THREE_MONTHS, LAST_SIX_MONTHS, LAST_YEAR. Specify RANGE to filter by a custom from-to date range

from

Long

Matches the releases with end date after or equal to this date

to

Long

Matches the releases with start date before this date

active

Boolean

Matches the releases with the IN_PROGRESS, FAILED, FAILING or PAUSED status

planned

Boolean

Matches the releases with the PLANNED status

inProgress

Boolean

Matches the releases with the IN_PROGRESS status

paused

Boolean

Matches the releases with the PAUSED status

failing

Boolean

Matches the releases with the FAILING status

failed

Boolean

Matches the releases with the FAILED status

inactive

Boolean

Matches the releases with the COMPLETED or ABORTED status

completed

Boolean

Matches the releases with the COMPLETED status

aborted

Boolean

Matches the releases with the ABORTED status

onlyMine

Boolean

Matches the releases with me as the owner

onlyFlagged

Boolean

Matches the releases which need attention or are at risk

onlyArchived

Boolean

Matches the releases which have been archived

parentId

String

Matches the releases stored under this folder

orderBy

String

The order of the returning set: risk, start_date, end_date, title (only available for templates)

orderDirection

String

The order direction of the returning set: ASC, DESC

The response contains a list of grouped results (live, archived) matching the criteria:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 6253

{
  "live" : {
    "page" : 0,
    "size" : 3,
    "releases" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Planned Release",
      "scheduledStartDate" : "2021-03-15T11:24:15.912+01:00",
      "dueDate" : "2021-03-15T19:24:15.912+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2021-03-15T11:24:15.912+01:00",
      "queryableEndDate" : "2021-03-15T19:24:15.912+01:00",
      "realFlagStatus" : "OK",
      "status" : "PLANNED",
      "tags" : [ "foo", "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "runningTriggeredReleasesCount" : 0,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "riskScore" : "000",
      "totalRiskScore" : "0000",
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
    }, {
      "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Running Release",
      "dueDate" : "2021-03-15T19:19:15.912+01:00",
      "startDate" : "2021-03-15T11:19:15.912+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2021-03-15T11:19:15.912+01:00",
      "queryableEndDate" : "2021-03-15T19:19:15.912+01:00",
      "realFlagStatus" : "OK",
      "status" : "IN_PROGRESS",
      "tags" : [ "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "runningTriggeredReleasesCount" : 0,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "riskScore" : "000",
      "totalRiskScore" : "0000",
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
    }, {
      "id" : "Applications/Release9303b354aba041eea4e2486ed81f80c2",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Failed Release",
      "dueDate" : "2021-03-15T19:14:15.912+01:00",
      "startDate" : "2021-03-15T11:14:15.912+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2021-03-15T11:14:15.912+01:00",
      "queryableEndDate" : "2021-03-15T19:14:15.912+01:00",
      "realFlagStatus" : "OK",
      "status" : "FAILED",
      "tags" : [ "foo" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "runningTriggeredReleasesCount" : 0,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "riskScore" : "000",
      "totalRiskScore" : "0000",
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
    } ]
  },
  "archived" : {
    "page" : 0,
    "size" : 2,
    "releases" : [ {
      "id" : "Applications/Release4c0a37c875694c97b30fa971fc1ee03c",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Completed Release",
      "startDate" : "2021-03-15T03:24:15.912+01:00",
      "endDate" : "2021-03-15T11:24:15.912+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2021-03-15T03:24:15.912+01:00",
      "queryableEndDate" : "2021-03-15T11:24:15.912+01:00",
      "realFlagStatus" : "OK",
      "status" : "COMPLETED",
      "tags" : [ "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "runningTriggeredReleasesCount" : 0,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "riskScore" : "000",
      "totalRiskScore" : "0000",
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
    }, {
      "id" : "Applications/Release18a1237a6df6409b941ab62a245141cc",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Aborted Release",
      "startDate" : "2021-03-15T02:24:15.912+01:00",
      "endDate" : "2021-03-15T10:24:15.912+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2021-03-15T02:24:15.912+01:00",
      "queryableEndDate" : "2021-03-15T10:24:15.912+01:00",
      "realFlagStatus" : "OK",
      "status" : "ABORTED",
      "tags" : [ "foo" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "runningTriggeredReleasesCount" : 0,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "riskScore" : "000",
      "totalRiskScore" : "0000",
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
    } ]
  }
}

Count releases by criteria

To count releases matching a specific search criteria grouped by database, send this request:

HTTP Request
POST /api/v1/releases/count

{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/count' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : true,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : true,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderDirection" : null
}' | http POST 'http://localhost:5516/api/v1/releases/count' \
    'Accept:application/json' \
    'Content-Type:application/json'

The following filters are available to be specified in the request body:

Path Type Description

title

String

Case-insensitive matches the part of the release title

tags

String

Matches the releases containing all of the specified tags

timeFrame

String

The time-frame to search releases in. Valid values: LAST_MONTH, LAST_THREE_MONTHS, LAST_SIX_MONTHS, LAST_YEAR. Specify RANGE to filter by a custom from-to date range

from

Long

Matches the releases with end date after or equal to this date

to

Long

Matches the releases with start date before this date

active

Boolean

Matches the releases with the IN_PROGRESS, FAILED, FAILING or PAUSED status

planned

Boolean

Matches the releases with the PLANNED status

inProgress

Boolean

Matches the releases with the IN_PROGRESS status

paused

Boolean

Matches the releases with the PAUSED status

failing

Boolean

Matches the releases with the FAILING status

failed

Boolean

Matches the releases with the FAILED status

inactive

Boolean

Matches the releases with the COMPLETED or ABORTED status

completed

Boolean

Matches the releases with the COMPLETED status

aborted

Boolean

Matches the releases with the ABORTED status

onlyMine

Boolean

Matches the releases with me as the owner

onlyFlagged

Boolean

Matches the releases which need attention or are at risk

onlyArchived

Boolean

Matches the releases which have been archived

parentId

String

Matches the releases stored under this folder

orderBy

String

The order of the returning set: risk, start_date, end_date, title (only available for templates)

orderDirection

String

The order direction of the returning set: ASC, DESC

The response contains number of releases matching a specific search criteria grouped by status and database (live, archived) with combined results (all):

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 402
Content-Type: application/json

{
  "live" : {
    "total" : 3,
    "byStatus" : {
      "FAILED" : 1,
      "IN_PROGRESS" : 1,
      "PLANNED" : 1
    }
  },
  "archived" : {
    "total" : 2,
    "byStatus" : {
      "ABORTED" : 1,
      "COMPLETED" : 1
    }
  },
  "all" : {
    "total" : 5,
    "byStatus" : {
      "IN_PROGRESS" : 1,
      "ABORTED" : 1,
      "FAILED" : 1,
      "COMPLETED" : 1,
      "PLANNED" : 1
    }
  }
}

Find phase by ID

To find a phase using a specific ID, send this request:

HTTP Request
GET /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e' \
    '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-Length: 427
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "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'

originId

String

If given, then this phase has been copied as a part of restart phase operation based on this id

Find task by ID

To find a task using a specific ID, send this request:

HTTP Request
GET /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' \
    '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-Length: 1001
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:27.828+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Search phases in a release by title

To find a phase in a release using a specific title, send this request:

HTTP Request
GET /api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release162151faba694d03aa3065665cf26f21' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release162151faba694d03aa3065665cf26f21' \
    '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-Language: en
Content-Type: application/json
Content-Length: 348

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "type" : "xlrelease.Phase",
  "title" : "find me",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "status" : "PLANNED",
  "color" : "#00FF00"
} ]

Search phases in a release

To find a phase in a release send this request:

HTTP Request
GET /api/v1/phases/search?phaseTitle=DEV&releaseId=Applications/Release162151faba694d03aa3065665cf26f21&phaseVersion=ALL
Curl
$ curl 'http://localhost:5516/api/v1/phases/search?phaseTitle=DEV&releaseId=Applications/Release162151faba694d03aa3065665cf26f21&phaseVersion=ALL' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/search?phaseTitle=DEV&releaseId=Applications/Release162151faba694d03aa3065665cf26f21&phaseVersion=ALL' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

phaseTitle

Part of a phase title

releaseId

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

phaseVersion

Choose between [LATEST, ORIGINAL, ALL] to narrow down search for specific version

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

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 344

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "type" : "xlrelease.Phase",
  "title" : "DEV",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "status" : "PLANNED",
  "color" : "#00FF00"
} ]

Search tasks in a release by title

To find a task in a release using a specific title, send this request:

HTTP Request
GET /api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/Release162151faba694d03aa3065665cf26f21' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/Release162151faba694d03aa3065665cf26f21' \
    '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-Language: en
Content-Length: 885
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "find me",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:23.560+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
} ]

Listing planned or active releases

To list a page of planned or active (in_progress, failed, failing) releases send this request:

HTTP Request
GET /api/v1/releases?page=0&resultsPerPage=2&depth=1
Curl
$ curl 'http://localhost:5516/api/v1/releases?page=0&resultsPerPage=2&depth=1' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases?page=0&resultsPerPage=2&depth=1' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

page

The page to fetch, zero-based; default value is 0

resultsPerPage

Number of results per page, default value is 100

depth

The depth of object tree, zero-based; default value is 1. Items fetched with depth 0 contain only basic properties like 'id' and 'type'. Items fetched with depth 1 contain simple properties (). Collections and references to other items are fetched only for basic properties.

The response contains a page of planned or active releases fetched with given depth, sorted ascending by start date and title:

HTTP/1.1 200 OK
Content-Length: 2342
Content-Language: en
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "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" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
}, {
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
} ]

Listing templates

To list a page of release templates send this request:

HTTP Request
GET /api/v1/templates?title=Test%20template&tag=tag1&page=0&resultsPerPage=2&depth=1
Curl
$ curl 'http://localhost:5516/api/v1/templates?title=Test%20template&tag=tag1&page=0&resultsPerPage=2&depth=1' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates?title=Test%20template&tag=tag1&page=0&resultsPerPage=2&depth=1' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

page

The page to fetch, zero-based; default value is 0

resultsPerPage

Number of results per page, default value is 100

depth

The depth of object tree, zero-based; default value is 1. Items fetched with depth 0 contain only basic properties like 'id' and 'type'. Items fetched with depth 1 contain simple properties (). Collections and references to other items are fetched only for basic properties.

title

Title of the release

tag

Tag of the release

The response contains a page of release templates fetched with given depth, sorted ascending by title:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2304

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Test template 1",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ "tag1", "tag2", "tag3" ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
}, {
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Test template 2",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ "tag1", "tag2" ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
} ]

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, send this request:

HTTP Request
POST /api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create

{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "variables" : { },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "variables" : { },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}'
HTTPie
$ echo '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "variables" : { },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' \
    'Accept:application/json' \
    'Content-Type:application/json'

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

variables

Object

Release variables

releaseVariables

Object

Release variables (deprecated - use 'variables')

releasePasswordVariables

Object

Release password variables (deprecated - use 'variables')

scheduledStartDate

Null

Date when the release is supposed to start.

autoStart

Boolean

If true, the release will automatically start at the scheduledStartDate.

folderId

String

If not null, specifies the id of the folder where the release is to be created.

To create and start the release immediately, use /start instead of /create in the curl command. To schedule a release to start in the future, set autoStart to true and adjust the scheduledStartDate to the desired date and time.

The response contains the new release.

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2777

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Releasef14b86fab50444cd978035dc0f33245f",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2021-03-15T11:23:17.674+01:00",
  "dueDate" : "2021-03-15T19:23:17.674+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:17.674+01:00",
  "queryableEndDate" : "2021-03-15T19:23:17.674+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarLinkToken" : "8930165070268156713",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ "folder#edit_variables", "release#edit_precondition", "release#edit", "folder#edit_configuration", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "group#edit", "template#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "dashboard#view", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "delivery_pattern#edit", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "release#view", "delivery#view", "delivery#edit_tracked_item", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "template#edit_triggers", "template#edit_precondition", "dashboard#edit", "folder#edit_security", "release#abort", "folder#edit", "template#edit_failure_handler" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

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

{
  "releaseTitle": "release from api",
  "variables" : {
    "listVar": [ "a", "b" ],
  }
}

or if you’re using only string variables and older version of XL Release:

{
  "releaseTitle": "release from api",
  "releaseVariables": {
    "variable1": "value1"
  },
  "releasePasswordVariables": {
    "passwordVariable": "passwordValue"
  }
}

To create a new release from a template with variables, send this request:

HTTP Request
POST /api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create

{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder16471301a63401435604e56d1303c451",
  "variables" : {
    "listVar" : [ "a", "b" ],
    "stringVar" : "providedValue",
    "passwordVar" : "providedValue"
  },
  "releaseVariables" : {
    "stringVar" : "providedValue"
  },
  "releasePasswordVariables" : {
    "passwordVar" : "{aes:v0}z5dxb/4lHH+12jIj34y0QcyfiHTnYdjmb+K/qKSkgbI="
  },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder16471301a63401435604e56d1303c451",
  "variables" : {
    "listVar" : [ "a", "b" ],
    "stringVar" : "providedValue",
    "passwordVar" : "providedValue"
  },
  "releaseVariables" : {
    "stringVar" : "providedValue"
  },
  "releasePasswordVariables" : {
    "passwordVar" : "{aes:v0}z5dxb/4lHH+12jIj34y0QcyfiHTnYdjmb+K/qKSkgbI="
  },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}'
HTTPie
$ echo '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder16471301a63401435604e56d1303c451",
  "variables" : {
    "listVar" : [ "a", "b" ],
    "stringVar" : "providedValue",
    "passwordVar" : "providedValue"
  },
  "releaseVariables" : {
    "stringVar" : "providedValue"
  },
  "releasePasswordVariables" : {
    "passwordVar" : "{aes:v0}z5dxb/4lHH+12jIj34y0QcyfiHTnYdjmb+K/qKSkgbI="
  },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "releaseOwner" : null
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

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

templateId

Full template identifier; for example, Applications/Release1

Path Type Description

releaseTitle

String

Release title

variables

Object

Release variables

releaseVariables

Object

Release variables (deprecated - use 'variables')

releasePasswordVariables

Object

Release password variables (deprecated - use 'variables')

scheduledStartDate

Null

Date when the release is supposed to start.

autoStart

Boolean

If true, the release will automatically start at the scheduledStartDate.

folderId

String

If not null, specifies the id of the folder where the release is to be created.

you will receive following response:

HTTP/1.1 200 OK
Content-Length: 3857
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releaseb30d739cbff74c9da66bea3ae1acae38",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2021-03-15T11:23:21.820+01:00",
  "dueDate" : "2021-03-15T19:23:21.820+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:21.820+01:00",
  "queryableEndDate" : "2021-03-15T19:23:21.820+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releaseb30d739cbff74c9da66bea3ae1acae38/Variable756120096ce447fbb1830370bacf4659",
    "type" : "xlrelease.StringVariable",
    "key" : "stringVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "providedValue",
    "multiline" : false
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releaseb30d739cbff74c9da66bea3ae1acae38/Variablef521b4d0819840b6bef9a590b54b7f49",
    "type" : "xlrelease.PasswordStringVariable",
    "key" : "passwordVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "{aes:v0}pU8tXDzRYX7JDm6KLT42xqXmr0mkssd6E9TraJPfWvk="
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releaseb30d739cbff74c9da66bea3ae1acae38/Variable7f1cf7a1fc6340ff9e7e91798054e269",
    "type" : "xlrelease.ListStringVariable",
    "key" : "listVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : [ "a", "b" ]
  } ],
  "calendarLinkToken" : "1779183556501655338",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder16471301a63401435604e56d1303c451/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ "folder#edit_variables", "release#edit_precondition", "release#edit", "folder#edit_configuration", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "group#edit", "template#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "dashboard#view", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "delivery_pattern#edit", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "release#view", "delivery#view", "delivery#edit_tracked_item", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "template#edit_triggers", "template#edit_precondition", "dashboard#edit", "folder#edit_security", "release#abort", "folder#edit", "template#edit_failure_handler" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Start a planned release

To start a planned release, send this request:

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/start
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/start' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/start' \
    'Accept:application/json'

Using the following parameters:

Table 8. /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, send this request:

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/active-tasks
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/active-tasks' -i -X GET \
    -H 'Content-Type: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/active-tasks' \
    'Content-Type:application/json'

Using the following parameters:

Table 9. /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-Language: en
Content-Length: 984
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "startDate" : "2021-03-15T11:24:14.844+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
} ]

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.

[].facets

Array

Facets applied to the task.

[].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 to be delayed when a blackout period is active.

[].precondition

String

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

[].failureHandler

String

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

[].taskFailureHandlerEnabled

Boolean

The failed script will be executed.

[].taskRecoverOp

String

Task recovery operation performed after task failure.

[].phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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

[].locked

Boolean

The task is locked

[].checkAttributes

Boolean

Check attributes on task execution

[].watchers

Array

List of users watching this task

Assign a task to a user

To assign a task to a user, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/assign/admin
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/assign/admin' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/assign/admin' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 10. /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-Length: 948
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Add a comment to a task

To add a comment to a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/comment

{
  "comment" : "Important step in our pipeline"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/comment' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Important step in our pipeline"
}'
HTTPie
$ echo '{
  "comment" : "Important step in our pipeline"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/comment' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 11. /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-Length: 1319
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment61534d87f5964ca19bfb7138800da9fb",
    "type" : "xlrelease.Comment",
    "text" : "Important step in our pipeline",
    "author" : "admin",
    "date" : "2021-03-15T11:23:30.721+01:00",
    "creationDate" : "2021-03-15T11:23:30.721+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

Complete a task

To complete a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/complete

{
  "comment" : "Task completed!"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/complete' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Task completed!"
}'
HTTPie
$ echo '{
  "comment" : "Task completed!"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/complete' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 12. /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-Language: en
Content-Length: 1445
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:25.967+01:00",
  "endDate" : "2021-03-15T11:23:26.158+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment54db060c55774473a0e9b4532a1653d0",
    "type" : "xlrelease.Comment",
    "text" : "Task completed!",
    "author" : "admin",
    "date" : "2021-03-15T11:23:26.167+01:00",
    "creationDate" : "2021-03-15T11:23:26.166+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "COMPLETED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Reopen a task that has been completed in advance

To reopen a task that has been completed in advance, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/reopen

{
  "comment" : "Reopen a task that has been completed in advance."
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/reopen' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Reopen a task that has been completed in advance."
}'
HTTPie
$ echo '{
  "comment" : "Reopen a task that has been completed in advance."
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/reopen' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 13. /api/v1/tasks/{taskId}/reopen
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 planned task with the added comment.

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1359

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment25ca68e904bb4b1e9a019adb6ffa6010",
    "type" : "xlrelease.Comment",
    "text" : "Reopen a task that has been completed in advance.",
    "author" : "admin",
    "date" : "2021-03-15T11:23:29.066+01:00",
    "creationDate" : "2021-03-15T11:23:29.066+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Fail a task

To fail a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/fail

{
  "comment" : "Task failed :-("
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/fail' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Task failed :-("
}'
HTTPie
$ echo '{
  "comment" : "Task failed :-("
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/fail' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 14. /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-Length: 1373
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:28.575+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment19e7194d16af4b5991150772cd163425",
    "type" : "xlrelease.Comment",
    "text" : "Task failed :-(",
    "author" : "admin",
    "date" : "2021-03-15T11:23:28.754+01:00",
    "creationDate" : "2021-03-15T11:23:28.754+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "FAILED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 1,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Retry a failed task

To retry a failed task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/retry

{
  "comment" : "Retry failed task."
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/retry' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Retry failed task."
}'
HTTPie
$ echo '{
  "comment" : "Retry failed task."
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/retry' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 15. /api/v1/tasks/{taskId}/retry
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 running task with the added comment:

HTTP/1.1 200 OK
Content-Length: 1381
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:24.703+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment254b06ef5c044c4eae54d9b755ebfa28",
    "type" : "xlrelease.Comment",
    "text" : "Retry failed task.",
    "author" : "admin",
    "date" : "2021-03-15T11:23:24.727+01:00",
    "creationDate" : "2021-03-15T11:23:24.727+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Skip a task

To skip a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/skip

{
  "comment" : "Task skipped"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/skip' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "comment" : "Task skipped"
}'
HTTPie
$ echo '{
  "comment" : "Task skipped"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/skip' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 16. /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-Length: 1440
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2021-03-15T11:23:30.799+01:00",
  "endDate" : "2021-03-15T11:23:31.014+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment368a205ca804414d9abb27a645d6c610",
    "type" : "xlrelease.Comment",
    "text" : "Task skipped",
    "author" : "admin",
    "date" : "2021-03-15T11:23:31.019+01:00",
    "creationDate" : "2021-03-15T11:23:31.019+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "SKIPPED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

Start a task that is waiting for input

To start a task that is waiting for input, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/start

{
  "variables" : [ {
    "key" : "title",
    "value" : "value1",
    "type" : "xlrelease.StringVariable",
    "id" : "Applications/ReleasesTest/Release1/Variable1"
  } ]
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/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"
  } ]
}'
HTTPie
$ echo '{
  "variables" : [ {
    "key" : "title",
    "value" : "value1",
    "type" : "xlrelease.StringVariable",
    "id" : "Applications/ReleasesTest/Release1/Variable1"
  } ]
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/start' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 17. /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-Language: en
Content-Type: application/json
Content-Length: 954

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.UserInputTask",
  "title" : "This task ${title}",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "WAITING_FOR_INPUT",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ],
  "variables" : [ "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b" ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

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:

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/abort

{
  "abortComment" : "Abort comment"
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/abort' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "abortComment" : "Abort comment"
}'
HTTPie
$ echo '{
  "abortComment" : "Abort comment"
}' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/abort' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 18. /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-Language: en
Content-Type: application/json
Content-Length: 1233

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Running release, don't abort me",
  "endDate" : "2021-03-15T11:24:10.415+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableEndDate" : "2021-03-15T11:24:10.415+01:00",
  "realFlagStatus" : "OK",
  "status" : "ABORTED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "abortComment" : "Abort comment",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "blackout" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { }
  }
}

Resume release

Resume a release that had been paused as part of the restart operation.

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/resume
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/resume' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/resume' \
    'Accept:application/json'

Using the following parameters:

Table 19. /api/v1/releases/{releaseId}/resume
Parameter Description

releaseId

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

The response contains the resumed release:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 4284

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2021-03-15T11:24:10.048+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "endDate" : "2021-03-15T11:24:09.872+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false,
      "watchers" : [ ]
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
    "startDate" : "2021-03-15T11:24:10.050+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2021-03-15T11:24:10.053+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false,
      "watchers" : [ ]
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "IN_PROGRESS"
  } ],
  "queryableStartDate" : "2021-03-15T11:24:10.048+01:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "blackout" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { }
  }
}

Restart a phase

Restarts the release from a given phase and task.

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/restart?fromPhaseId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&fromTaskId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726&phaseVersion=ALL&resume=true

fromPhaseId=Applications%2FRelease162151faba694d03aa3065665cf26f21%2FPhase520d9bb734c8490cad6818f736da7a5e&fromTaskId=Applications%2FRelease162151faba694d03aa3065665cf26f21%2FPhase520d9bb734c8490cad6818f736da7a5e%2FTask97c27091a9b342599e1b631dc6d44726&phaseVersion=ALL&resume=true
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/restart?fromPhaseId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&fromTaskId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726&phaseVersion=ALL&resume=true' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/restart?fromPhaseId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&fromTaskId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726&phaseVersion=ALL&resume=true' \
    'Accept:application/json'

Using the following parameters:

Table 20. /api/v1/releases/{releaseId}/restart
Parameter Description

releaseId

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

Parameter Description

fromPhaseId

Full identifier of the phase; for example, Applications/Release1/Phase11

fromTaskId

Full identifier of the task; for example, Applications/Release1/Phase11/Task111

phaseVersion

'LATEST', or 'ORIGINAL' or old behavior 'ALL'. Determines which version to copy of the phase.

resume

When true resumes the paused release immediately

The response contains the restarted release:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 4552
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2021-03-15T11:24:12.276+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "startDate" : "2021-03-15T11:24:12.230+01:00",
    "endDate" : "2021-03-15T11:24:12.230+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2021-03-15T11:24:12.009+01:00",
      "endDate" : "2021-03-15T11:24:12.231+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false,
      "watchers" : [ ]
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phasee2b90ae293ae49f695fb9a94c038b4e6",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (2)",
    "startDate" : "2021-03-15T11:24:12.276+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phasee2b90ae293ae49f695fb9a94c038b4e6/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2021-03-15T11:24:12.276+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phasee2b90ae293ae49f695fb9a94c038b4e6",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false,
      "watchers" : [ ]
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "IN_PROGRESS",
    "originId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e"
  } ],
  "queryableStartDate" : "2021-03-15T11:24:12.276+01:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 1,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "blackout" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { }
  }
}

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, send this request:

HTTP Request
POST /api/v1/templates/?folderId=Applications/Folder01345a690c16b345168751d62934e912

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.338+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.338+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/?folderId=Applications/Folder01345a690c16b345168751d62934e912' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.338+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.338+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.338+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.338+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http POST 'http://localhost:5516/api/v1/templates/?folderId=Applications/Folder01345a690c16b345168751d62934e912' \
    'Accept:application/json' \
    'Content-Type:application/json'

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Using the following query parameters:

Parameter Description

folderId

If not null, specifies the id of the folder where the template is to be created

The response contains the template JSON:

HTTP/1.1 200 OK
Content-Length: 4731
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Release22ba7fd9d1124110a243a0e303078d7d",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.338+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teamb144d94c2140469cb012ccd0c1191bb4",
    "type" : "xlrelease.Team",
    "teamName" : "Template Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teama3f533e2ba204cf293166a353c8967c7",
    "type" : "xlrelease.Team",
    "teamName" : "Folder Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teame24327e34b3f4a15a5ea4638fd9dc9c2",
    "type" : "xlrelease.Team",
    "teamName" : "Release Admin",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ]
  } ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Release22ba7fd9d1124110a243a0e303078d7d/Phasebcf0af3f61c64cb09e4e6648a5c0ec16",
    "type" : "xlrelease.Phase",
    "title" : "New Phase",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ ],
    "release" : "Applications/Folder01345a690c16b345168751d62934e912/Release22ba7fd9d1124110a243a0e303078d7d",
    "status" : "PLANNED"
  } ],
  "queryableStartDate" : "2021-03-15T11:23:19.338+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ "folder#edit_variables", "release#edit_precondition", "release#edit", "folder#edit_configuration", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "group#edit", "template#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "dashboard#view", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "delivery_pattern#edit", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "release#view", "delivery#view", "delivery#edit_tracked_item", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "template#edit_triggers", "template#edit_precondition", "dashboard#edit", "folder#edit_security", "release#abort", "folder#edit", "template#edit_failure_handler" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Import a template, serialized in XLR format, or a Releasefile (Releasefile.groovy) inside a .zip file

You can also import templates that were previously exported using XL Release. Send the .xlr or .zip 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.

To import a template, send this request:

Curl
$ curl 'http://localhost:5516/api/v1/templates/import' --form file=@template.xlr
HTTPie
$ http -f POST http://localhost:5516/api/v1/templates/import file@template.xlr

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, send this request:

HTTP Request
POST /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/phase

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

Using the following parameters:

Table 21. /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'

originId

String

If given, then this phase has been copied as a part of restart phase operation based on this id

The response contains the created phase:

HTTP/1.1 200 OK
Content-Length: 427
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase37befca2eb0f4b6f98375645c438187d",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "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'

originId

String

If given, then this phase has been copied as a part of restart phase operation based on this id

Copy a phase in a release

You can easily copy a phase and paste into desirable position. XLR has several restrictions for copying a phase:

  • Position should be next to planned or in progress phase.

  • You cannot copy completed phase

Usage example:

HTTP Request
POST /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/copy?targetPosition=1

targetPosition=1
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/copy?targetPosition=1' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/copy?targetPosition=1' \
    'Accept:application/json'

Using the following path parameters:

Table 22. /api/v1/phases/{phaseId}/copy
Parameter Description

phaseId

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

Using the following query parameters:

Parameter Description

targetPosition

Phase position into release

The response contains the created phase:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1464

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phaseacec30e0571142bc91f8f4dd176db6c6",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phaseacec30e0571142bc91f8f4dd176db6c6/Task97c27091a9b342599e1b631dc6d44726",
    "type" : "xlrelease.GateTask",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "comments" : [ ],
    "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phaseacec30e0571142bc91f8f4dd176db6c6",
    "facets" : [ ],
    "attachments" : [ ],
    "status" : "PLANNED",
    "waitForScheduledStartDate" : true,
    "delayDuringBlackout" : false,
    "postponedDueToBlackout" : false,
    "hasBeenFlagged" : false,
    "hasBeenDelayed" : false,
    "taskFailureHandlerEnabled" : false,
    "failuresCount" : 0,
    "variableMapping" : { },
    "tags" : [ ],
    "dueSoonNotified" : false,
    "locked" : false,
    "checkAttributes" : false,
    "watchers" : [ ],
    "conditions" : [ ],
    "dependencies" : [ ]
  } ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "status" : "PLANNED",
  "color" : "#00FF00"
}

Update phase in a release

To update a phase in a release or in a template, send this request:

HTTP Request
PUT /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e

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

Using the following path parameters:

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

phaseId

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

Using the following query parameters:

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'

originId

String

If given, then this phase has been copied as a part of restart phase operation based on this id

The response contains the updated phase:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 346
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "type" : "xlrelease.Phase",
  "title" : "new title",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "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'

originId

String

If given, then this phase has been copied as a part of restart phase operation based on this id

Tasks

Add a task in a phase or in another task

To add a new task in a phase or in another task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks

{
  "id" : "null",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "null",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task"
}'
HTTPie
$ echo '{
  "id" : "null",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 24. /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-Language: en
Content-Type: application/json
Content-Length: 840

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task2db61f979f2d4237806e5fee6ff83fa3",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ],
  "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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

variables

Array

List of variables

Add a task to a specific position inside a phase

To add a new task to a specified position, send this request:

HTTP Request
POST /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks?position=0

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks?position=0' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}' | http POST 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks?position=0' \
    'Accept:application/json' \
    'Content-Type:application/json'

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

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

The response contains the created task:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 840

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Taskf87971c05a1d4b87acf72dbf8554b016",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ],
  "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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

variables

Array

List of variables

Copy a task to a specific position inside a phase

To copy a task to a specified position, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/copy/?targetContainerId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&targetPosition=1

targetContainerId=Applications%2FRelease162151faba694d03aa3065665cf26f21%2FPhase520d9bb734c8490cad6818f736da7a5e&targetPosition=1
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/copy/?targetContainerId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&targetPosition=1' -i -X POST
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/copy/?targetContainerId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&targetPosition=1'

Using the following path parameters:

Table 26. /api/v1/tasks/{taskId}/copy/
Parameter Description

taskId

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

Using the following query parameters:

Parameter Description

targetContainerId

Full identifier of the task container; for example, Applications/Release1/Phase3

targetPosition

Position within task container

The response contains the created task:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 984
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task131ace815ad24464acde8318911f5c17",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726 (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ],
  "conditions" : [ ],
  "dependencies" : [ ]
}

Update the task for a specific ID

To update a task for a specific ID, send this request:

HTTP Request
PUT /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "new title"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "new title"
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "new title"
}' | http PUT 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 27. /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-Language: en
Content-Type: application/json
Content-Length: 809

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "new title",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ]
}

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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

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

xlrelease.CustomScriptTask

jira.CreateSubtask

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.

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/changeType?targetType=xlrelease.GateTask

targetType=xlrelease.GateTask
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/changeType?targetType=xlrelease.GateTask' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/changeType?targetType=xlrelease.GateTask' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Parameter Description

targetType

Target task type; for example, targetType=xlrelease.Task or targetType=jenkins.Build

Table 28. /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-Length: 977
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "watchers" : [ ],
  "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.

facets

Array

Facets applied to the task.

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 to be delayed when a blackout period is active.

precondition

String

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

failureHandler

String

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

taskFailureHandlerEnabled

Boolean

The failed script will be executed.

taskRecoverOp

String

Task recovery operation performed after task failure.

phaseRecoverOp

String

Phase recovery operation performed after task recovery.

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.

locked

Boolean

The task is locked

checkAttributes

Boolean

Check attributes on task execution

watchers

Array

List of users watching this task

conditions

Array

Conditions

dependencies

Array

Dependencies

Lock/unlock task

Lock task

To lock a task, send this request:

HTTP Request
PUT /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock' \
    'Accept:application/json'

You will receive this empty response:

HTTP/1.1 204 No Content
Content-Language: en
Unlock task

To unlock a task, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/lock' \
    'Accept:application/json'

You will receive this empty response:

HTTP/1.1 204 No Content
Content-Language: en

Gate tasks

Add a condition to a gate task

To add a condition to a gate task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/conditions

{
  "title" : "this must be true to go on",
  "checked" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/conditions' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "this must be true to go on",
  "checked" : false
}'
HTTPie
$ echo '{
  "title" : "this must be true to go on",
  "checked" : false
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/conditions' \
    'Accept:application/json' \
    'Content-Type:application/json'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

Using the following parameters:

Table 29. /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-Language: en
Content-Type: application/json
Content-Length: 289

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition422f49db25f24d69847595056a957e56",
  "type" : "xlrelease.GateCondition",
  "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, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1

{
  "title" : "my first condition",
  "checked" : true
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "my first condition",
  "checked" : true
}'
HTTPie
$ echo '{
  "title" : "my first condition",
  "checked" : true
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1' \
    'Accept:application/json' \
    'Content-Type:application/json'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

Using the following parameters:

Table 30. /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-Language: en
Content-Type: application/json
Content-Length: 249

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1",
  "type" : "xlrelease.GateCondition",
  "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, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/GateCondition1'

Using the following parameters:

Table 31. /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
Content-Language: en
Add a dependency to a gate task

To add a dependency to a gate task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/dependencies/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/dependencies/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/dependencies/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 32. /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-Language: en
Content-Length: 688
Content-Type: application/json

{
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Dependency60ab4f25744c4708902ab620321f6052",
  "type" : "xlrelease.Dependency",
  "gateTask" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "target" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "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, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Dependency76ad0473a3a24ee1b961948db4532857
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Dependency76ad0473a3a24ee1b961948db4532857' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Dependency76ad0473a3a24ee1b961948db4532857'

Using the following parameters:

Table 33. /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
Content-Language: en

Attachments

Download an attachment

To download an attachment, send this request:

HTTP Request
GET /api/v1/releases/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment313f941a22104133bd7008a605cdaa65
Curl
$ curl 'http://localhost:5516/api/v1/releases/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment313f941a22104133bd7008a605cdaa65' -i -X GET \
    -H 'Accept: application/octet-stream'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment313f941a22104133bd7008a605cdaa65' \
    'Accept:application/octet-stream'

Using the following parameter:

Table 34. /api/v1/releases/attachments/{attachmentId}
Parameter Description

attachmentId

Full identifier of the attachment; for example, Applications/Release1/Attachment1

You will receive the attachment file in the response.

Add attachments to a task

To upload a list of attachments to a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments

-----011000010111000001101001
Content-Disposition: form-data; name="xlr"; filename="Dummy.xml"
Content-Type: application/xml


-----011000010111000001101001--
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments' -i -X POST \
    -H 'Content-Type: multipart/form-data;boundary=---011000010111000001101001' \
    -H 'Accept: multipart/form-data, application/json' \
    -d '-----011000010111000001101001
Content-Disposition: form-data; name="xlr"; filename="Dummy.xml"
Content-Type: application/xml


-----011000010111000001101001--
'
HTTPie
$ echo '-----011000010111000001101001
Content-Disposition: form-data; name="xlr"; filename="Dummy.xml"
Content-Type: application/xml


-----011000010111000001101001--
' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments' \
    'Content-Type:multipart/form-data;boundary=---011000010111000001101001' \
    'Accept:multipart/form-data, application/json'

Using the following parameter:

Table 35. /api/v1/tasks/{taskId}/attachments
Parameter Description

taskId

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

You will receive a response containing a list of uploaded attachments:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 466

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Attachmentd44c4931038149e4a57e2a55155dd9a9",
  "type" : "xlrelease.Attachment",
  "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "contentType" : "application/xml",
  "exportFilename" : "attachments/Attachmentd44c4931038149e4a57e2a55155dd9a9-Dummy.xml",
  "fileUri" : "sql:Applications%2FRelease162151faba694d03aa3065665cf26f21%2FAttachmentd44c4931038149e4a57e2a55155dd9a9"
} ]

Delete attachment from a task

To delete an attachment from a task, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment1a268c81f79a41cc8e7dbb954415f9f1
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment1a268c81f79a41cc8e7dbb954415f9f1' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachment1a268c81f79a41cc8e7dbb954415f9f1' \
    'Accept:application/json'

Using the following parameters:

Table 36. /api/v1/tasks/{taskId}/attachments/{attachmentId}
Parameter Description

taskId

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

attachmentId

Full identifier of the attachment; for example, Applications/Release1/Attachment1

You will receive this empty response:

HTTP/1.1 204 No Content
Content-Language: en

Properties

Update template properties

To update the properties of a template, send this request:

HTTP Request
PUT /api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.062+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.062+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.062+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.062+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.062+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.062+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http PUT 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 37. /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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

The response the updated template:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1216

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2021-03-15T11:23:19.062+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:23:19.062+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
}

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Update release properties

To update the properties of a release, send this request:

HTTP Request
PUT /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2021-03-15T11:24:12.928+01:00",
  "dueDate" : "2021-03-15T11:24:12.928+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:24:12.928+01:00",
  "queryableEndDate" : "2021-03-15T11:24:12.928+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2021-03-15T11:24:12.928+01:00",
  "dueDate" : "2021-03-15T11:24:12.928+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:24:12.928+01:00",
  "queryableEndDate" : "2021-03-15T11:24:12.928+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2021-03-15T11:24:12.928+01:00",
  "dueDate" : "2021-03-15T11:24:12.928+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:24:12.928+01:00",
  "queryableEndDate" : "2021-03-15T11:24:12.928+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

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

releaseId

Full identifier of the 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.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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

The response contains the updated release:

HTTP/1.1 200 OK
Content-Length: 1275
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "new title",
  "scheduledStartDate" : "2021-03-15T11:24:12.928+01:00",
  "dueDate" : "2021-03-15T11:24:12.928+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2021-03-15T11:24:12.928+01:00",
  "queryableEndDate" : "2021-03-15T11:24:12.928+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    }
  }
}

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

abortComment

String

The comment to associate with the action

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Delete commands for task, phase, template, or release

Delete a task

To delete a task, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726'

Using the following parameters:

Table 39. /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
Content-Language: en

Delete a phase

To delete a phase, send this request:

HTTP Request
DELETE /api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e'

Using the following parameters:

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

phaseId

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

You will receive this empty response:

HTTP/1.1 204 No Content
Content-Language: en

Delete template

To delete a template, send this request:

HTTP Request
DELETE /api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21'

Using the following parameters:

Table 41. /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
Content-Language: en

Delete release

To delete a release, it must be in aborted or done status.

To delete a release, send this request:

HTTP Request
DELETE /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21'

Using the following parameters:

Table 42. /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
Content-Language: en
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, send this request:

HTTP Request
GET /api/v1/folders/list?depth=4
Curl
$ curl 'http://localhost:5516/api/v1/folders/list?depth=4' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/list?depth=4' \
    'Accept:application/json'

You receive a response containing a list of folders:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2795

[ {
  "id" : "Applications/Folder15dfe5ef4d014eb2b5f6ee6e43d65156",
  "type" : "xlrelease.Folder",
  "$token" : "473f28af-b710-4af2-9011-004078fc782d",
  "title" : "Microservices",
  "children" : [ {
    "id" : "Applications/Folder15dfe5ef4d014eb2b5f6ee6e43d65156/Folder60c4b51d77af4decb148f0cad97b6c05",
    "type" : "xlrelease.Folder",
    "$token" : "4f27487d-7623-444f-bf01-9d70c2adb210",
    "title" : "Invoice processing service",
    "children" : [ ],
    "$metadata" : {
      "security" : {
        "permissions" : [ "folder#edit_variables", "release#edit_precondition", "release#edit", "folder#edit_configuration", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "group#edit", "template#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "dashboard#view", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "delivery_pattern#edit", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "release#view", "delivery#view", "delivery#edit_tracked_item", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "template#edit_triggers", "template#edit_precondition", "dashboard#edit", "folder#edit_security", "release#abort", "folder#edit", "template#edit_failure_handler" ],
        "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
      }
    }
  } ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "folder#edit_variables", "release#edit_precondition", "release#edit", "folder#edit_configuration", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "group#edit", "template#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "dashboard#view", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "delivery_pattern#edit", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "release#view", "delivery#view", "delivery#edit_tracked_item", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "template#edit_triggers", "template#edit_precondition", "dashboard#edit", "folder#edit_security", "release#abort", "folder#edit", "template#edit_failure_handler" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
} ]

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", send this request:

HTTP Request
POST /api/v1/folders/Applications

{
  "id" : null,
  "type" : "xlrelease.Folder",
  "title" : "New folder",
  "children" : [ ]
}
Curl
$ 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" : [ ]
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "xlrelease.Folder",
  "title" : "New folder",
  "children" : [ ]
}' | http POST 'http://localhost:5516/api/v1/folders/Applications' \
    'Content-Type:application/json'

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, send this request:

HTTP Request
GET /api/v1/folders/Applications/Folder233c3731eb6d43d7921fa487eae429f9/list
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder233c3731eb6d43d7921fa487eae429f9/list' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder233c3731eb6d43d7921fa487eae429f9/list' \
    '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 43. /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, send this request:

HTTP Request
GET /api/v1/folders/find?byPath=Microservices/QA
Curl
$ curl 'http://localhost:5516/api/v1/folders/find?byPath=Microservices/QA' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/find?byPath=Microservices/QA' \
    '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, send this request:

HTTP Request
GET /api/v1/folders/Applications/Folderb43bde9e52764dd58735e468a463fcd0/Folder41af0e132b4e4fb3b4dcfc08bca5823e
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderb43bde9e52764dd58735e468a463fcd0/Folder41af0e132b4e4fb3b4dcfc08bca5823e' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folderb43bde9e52764dd58735e468a463fcd0/Folder41af0e132b4e4fb3b4dcfc08bca5823e' \
    'Accept:application/json'

Using the following parameters:

Table 44. /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, send this request:

HTTP Request
GET /api/v1/folders/Applications/Folder66c46a595f1f4903b15d7082f75e996f/Folder82c2d3b6241c4dd79bb2a71b7cbb3a73/templates
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder66c46a595f1f4903b15d7082f75e996f/Folder82c2d3b6241c4dd79bb2a71b7cbb3a73/templates' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder66c46a595f1f4903b15d7082f75e996f/Folder82c2d3b6241c4dd79bb2a71b7cbb3a73/templates' \
    'Accept:application/json'

Using the following parameters:

Table 45. /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

If you want to search for releases:

HTTP Request
POST /api/v1/folders/Applications/Folder5635a1641eda49ad93db3665e6857731/Folderaa69e75f6358400aa1d4e9ac4df4ffcf/releases

{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "risk",
  "orderDirection" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder5635a1641eda49ad93db3665e6857731/Folderaa69e75f6358400aa1d4e9ac4df4ffcf/releases' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "risk",
  "orderDirection" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "timeFrame" : null,
  "from" : null,
  "to" : null,
  "active" : false,
  "planned" : true,
  "inProgress" : false,
  "paused" : false,
  "failing" : false,
  "failed" : false,
  "inactive" : false,
  "completed" : false,
  "aborted" : false,
  "onlyMine" : false,
  "onlyFlagged" : false,
  "onlyArchived" : false,
  "parentId" : null,
  "orderBy" : "risk",
  "orderDirection" : null
}' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder5635a1641eda49ad93db3665e6857731/Folderaa69e75f6358400aa1d4e9ac4df4ffcf/releases' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 46. /api/v1/folders/{folderId}/releases
Parameter Description

folderId

The id of the folder

Parameter Description

page

The (optional) page to search for; defaults at 0

numberbypage

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

depth

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

Path Type Description

title

String

Case-insensitive matches the part of the release title

tags

String

Matches the releases containing all of the specified tags

timeFrame

String

The time-frame to search releases in. Valid values: LAST_MONTH, LAST_THREE_MONTHS, LAST_SIX_MONTHS, LAST_YEAR. Specify RANGE to filter by a custom from-to date range

from

Long

Matches the releases with end date after or equal to this date

to

Long

Matches the releases with start date before this date

active

Boolean

Matches the releases with the IN_PROGRESS, FAILED, FAILING or PAUSED status

planned

Boolean

Matches the releases with the PLANNED status

inProgress

Boolean

Matches the releases with the IN_PROGRESS status

paused

Boolean

Matches the releases with the PAUSED status

failing

Boolean

Matches the releases with the FAILING status

failed

Boolean

Matches the releases with the FAILED status

inactive

Boolean

Matches the releases with the COMPLETED or ABORTED status

completed

Boolean

Matches the releases with the COMPLETED status

aborted

Boolean

Matches the releases with the ABORTED status

onlyMine

Boolean

Matches the releases with me as the owner

onlyFlagged

Boolean

Matches the releases which need attention or are at risk

onlyArchived

Boolean

Matches the releases which have been archived

parentId

String

Matches the releases stored under this folder

orderBy

String

The order of the returning set: risk, start_date, end_date, title (only available for templates)

orderDirection

String

The order direction of the returning set: ASC, DESC

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, send this request:

HTTP Request
POST /api/v1/folders/Applications/Foldere2a865706f434711998d3d6bbe4197d5/templates/Applications/Folderba6071316791454f8c0a06254586d136/Release1
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Foldere2a865706f434711998d3d6bbe4197d5/templates/Applications/Folderba6071316791454f8c0a06254586d136/Release1' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/folders/Applications/Foldere2a865706f434711998d3d6bbe4197d5/templates/Applications/Folderba6071316791454f8c0a06254586d136/Release1' \
    'Accept:application/json'

Using the following parameters:

Table 47. /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, send this request:

HTTP Request
POST /api/v1/folders/Applications/Foldere773d5e8fb3b472e851c89ac42b538ca

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

Using the following parameters:

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

folderId

The id of the folder to create the folder in

Delete folders

To delete a folder, send this request:

HTTP Request
DELETE /api/v1/folders/Applications/Folder578f785df52f4d838b624082f0804b43
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder578f785df52f4d838b624082f0804b43' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/folders/Applications/Folder578f785df52f4d838b624082f0804b43'

Using the following parameters:

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

folderId

The id of the folder to delete

Move folders

To move folders inside another folder, send this request:

HTTP Request
POST /api/v1/folders/Applications/Folder51a1fa2b92064829b3a3e5c43b8adbf0/move?newParentId=Applications/Folder3e5d7387f038421483b2a6d3cf5b838f

newParentId=Applications%2FFolder3e5d7387f038421483b2a6d3cf5b838f
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder51a1fa2b92064829b3a3e5c43b8adbf0/move?newParentId=Applications/Folder3e5d7387f038421483b2a6d3cf5b838f' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/folders/Applications/Folder51a1fa2b92064829b3a3e5c43b8adbf0/move?newParentId=Applications/Folder3e5d7387f038421483b2a6d3cf5b838f' \
    'Accept:application/json'

Using the following parameters:

Table 50. /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, send this request:

HTTP Request
POST /api/v1/folders/Applications/Folder1c17aec56ad14a4c88e0b9df2e416179/rename?newName=Microservices%20II

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

Using the following parameters:

Table 51. /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 52. 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"

Date

xlrelease.DateVariable

"2017-07-17T10:31:00+01:00"

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, send this request:

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' \
    'Accept:application/json'

Using the following path parameters:

Table 53. /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-Length: 294
Content-Language: en
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "value1",
  "multiline" : false
} ]

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

[].folderId

String

If set, this field contains the folder that this configuration belongs to.

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

[].inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

[].value

String

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

[].multiline

Boolean

If checked variable value will be multiline text

List all release/template variable values

To get the list of all interpolated variable values inside a template or release, send this request:

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variableValues
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variableValues' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variableValues' \
    'Accept:application/json'

Using the following path parameters:

Table 54. /api/v1/releases/{releaseId}/variableValues
Parameter Description

releaseId

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

The response contains map with interpolated variable values:

HTTP/1.1 200 OK
Content-Length: 53
Content-Language: en
Content-Type: application/json

{
  "${var1}" : "value1",
  "${var1ref}" : "value1"
}

Find release/template variable by ID

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

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' \
    'Accept:application/json'

Using the following path parameters:

Table 55. /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'.

folderId

String

If set, this field contains the folder that this configuration belongs to.

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

inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

value

String

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

multiline

Boolean

If checked variable value will be multiline text

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:

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables

{
  "id" : null,
  "key" : "newVar",
  "type" : "xlrelease.StringVariable",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value",
  "label" : null,
  "description" : null,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/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,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}'
HTTPie
$ echo '{
  "id" : null,
  "key" : "newVar",
  "type" : "xlrelease.StringVariable",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value",
  "label" : null,
  "description" : null,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' \
    'Content-Type:application/json'

Using the following path parameters:

Table 56. /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 send this request:

HTTP Request
DELETE /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' \
    'Accept:application/json'

Using the following path parameters:

Table 57. /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
Content-Language: en

Update variable

To update a single variable, send this request:

HTTP Request
PUT /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' \
    'Content-Type:application/json'

Using the following path parameters:

Table 58. /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:

HTTP Request
PUT /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
} ]
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
} ]' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' \
    'Content-Type:application/json'

Using the following path parameters:

Table 59. /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-Language: en
Content-Type: application/json
Content-Length: 301

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
} ]

Advanced

Variable values

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

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/possibleValues
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/possibleValues' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/possibleValues' \
    'Accept:application/json'

Using the following path parameters:

Table 60. /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-Length: 32
Content-Language: en
Content-Type: application/json

[ "value1", "value2", "value3" ]

Verify variable usage

To verify if a variable is used inside a release, send this request:

HTTP Request
GET /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/used
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/used' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/used' \
    'Accept:application/json'

Using the following path parameters:

Table 61. /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-Language: en
Content-Length: 5
Content-Type: application/json

false

Replacing a variable

To replace one or more variables, send this request:

HTTP Request
POST /api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/replace

{
  "variable" : "${var2}",
  "value" : "value2"
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/replace' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "variable" : "${var2}",
  "value" : "value2"
}'
HTTPie
$ echo '{
  "variable" : "${var2}",
  "value" : "value2"
}' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b/replace' \
    'Content-Type:application/json'

Using the following path parameters:

Table 62. /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
Content-Language: en

Variables used by a task

To get the variables used inside a task using the TaskApi, send this request:

HTTP Request
GET /api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/variables
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/variables' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/variables' \
    'Accept:application/json'

With the following path parameters:

Table 63. /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-Length: 295
Content-Language: en
Content-Type: application/json

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "title",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "value1",
  "multiline" : 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.StringVariable'.

[].folderId

String

If set, this field contains the folder that this configuration belongs to.

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

[].inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

[].value

String

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

[].multiline

Boolean

If checked variable value will be multiline text

Global variables

List global variables

To list all the global variables, send this request:

HTTP Request
GET /api/v1/config/Configuration/variables/global
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/variables/global' \
    'Accept:application/json'

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

HTTP/1.1 200 OK
Content-Length: 508
Content-Language: en
Content-Type: application/json

[ {
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}, {
  "id" : "Configuration/variables/global/Variable2",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1ref",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "${global.var1}",
  "multiline" : 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.StringVariable'.

[].folderId

String

If set, this field contains the folder that this configuration belongs to.

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

[].inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

[].value

String

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

[].multiline

Boolean

If checked variable value will be multiline text

List global variable values

To list all interpolated global variable values, send this request:

HTTP Request
GET /api/v1/config/Configuration/variableValues/global
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/variableValues/global' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/variableValues/global' \
    'Accept:application/json'

The response contains map with interpolated values of all the global variables defined in the system:

HTTP/1.1 200 OK
Content-Length: 65
Content-Language: en
Content-Type: application/json

{
  "${global.var1}" : "value",
  "${global.var1ref}" : "value"
}

Find global variable by ID

To obtain a specific global variable, send this request:

HTTP Request
GET /api/v1/config/Configuration/variables/global/Variable1
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' \
    'Accept:application/json'

Using the following path parameters:

Table 64. /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-Language: en
Content-Type: application/json
Content-Length: 245

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}

Create global variable

To add new global variable, send this request:

HTTP Request
POST /api/v1/config/Configuration/variables/global

{
  "id" : null,
  "key" : "global.newVar",
  "type" : "xlrelease.StringVariable",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value",
  "label" : null,
  "description" : null,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}
Curl
$ 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,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}'
HTTPie
$ echo '{
  "id" : null,
  "key" : "global.newVar",
  "type" : "xlrelease.StringVariable",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value",
  "label" : null,
  "description" : null,
  "multiline" : false,
  "inherited" : false,
  "valueProvider" : null
}' | http POST 'http://localhost:5516/api/v1/config/Configuration/variables/global' \
    'Content-Type:application/json'

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-Language: en
Content-Length: 282
Content-Type: application/json

{
  "id" : "Configuration/variables/global/Variable30eae3393ee4471fa9a78bdd0b828190",
  "type" : "xlrelease.StringVariable",
  "key" : "global.newVar",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "new value",
  "multiline" : false
}

Update global variable

To update a global variable, send this request:

HTTP Request
PUT /api/v1/config/Configuration/variables/global/Variable1

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}
Curl
$ 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,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}'
HTTPie
$ echo '{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}' | http PUT 'http://localhost:5516/api/v1/config/Configuration/variables/global/Variable1' \
    'Content-Type:application/json'

Using the following path parameters:

Table 65. /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'.

folderId

String

If set, this field contains the folder that this configuration belongs to.

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

inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

value

String

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

multiline

Boolean

If checked variable value will be multiline text

The response contains the updated global variable:

HTTP/1.1 200 OK
Content-Length: 253
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false
}

Delete global variable

To delete a global variable, send this request

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

Using the following path parameters:

Table 66. /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
Content-Language: en

Folder variables

List folder variables

To get the list of all the variables inside a folder, send this request:

HTTP Request
GET /api/v1/folders/Applications/Foldereac7ff711dc44d55bdc9214381f76200/Folder994424076ec641e6867ecfaabcc55d5b/variables?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Foldereac7ff711dc44d55bdc9214381f76200/Folder994424076ec641e6867ecfaabcc55d5b/variables?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Foldereac7ff711dc44d55bdc9214381f76200/Folder994424076ec641e6867ecfaabcc55d5b/variables?folderOnly=false' \
    'Accept:application/json'

The response contains all the variables defined in the folder:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 684

[ {
  "id" : "Variable0ce3ca7775bd4b9e90660201397997b9",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldereac7ff711dc44d55bdc9214381f76200",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}, {
  "id" : "Variable366f2b2683334adeaaee68da180715ab",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldereac7ff711dc44d55bdc9214381f76200/Folder994424076ec641e6867ecfaabcc55d5b",
  "key" : "folder.var2",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "${folder.var1}",
  "multiline" : 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.StringVariable'.

[].folderId

String

If set, this field contains the folder that this configuration belongs to.

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

[].inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

[].value

String

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

[].multiline

Boolean

If checked variable value will be multiline text

List folder variable values

To list all interpolated global variable values, send this request:

HTTP Request
GET /api/v1/folders/Applications/Folder2871d7d99bf14195b9b1e75afdefc873/Folder4c80d3f80f2149ae8aeb7a1979ac1d09/variableValues?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder2871d7d99bf14195b9b1e75afdefc873/Folder4c80d3f80f2149ae8aeb7a1979ac1d09/variableValues?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder2871d7d99bf14195b9b1e75afdefc873/Folder4c80d3f80f2149ae8aeb7a1979ac1d09/variableValues?folderOnly=false' \
    'Accept:application/json'

The response contains map with interpolated values of all the variables defined in the folder:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 62
Content-Type: application/json

{
  "${folder.var1}" : "value",
  "${folder.var2}" : "value"
}

Find folder variable by ID

To obtain a specific folder variable, send this request:

HTTP Request
GET /api/v1/folders/Applications/Folder091eed5e2dc44691abb04b1a462f56b0/Variable3017d802dfd24fca9531d6ae61696bae
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder091eed5e2dc44691abb04b1a462f56b0/Variable3017d802dfd24fca9531d6ae61696bae' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder091eed5e2dc44691abb04b1a462f56b0/Variable3017d802dfd24fca9531d6ae61696bae' \
    'Accept:application/json'

Using the following path parameters:

Table 67. /api/v1/folders/{folderId}/{variableId}
Parameter Description

folderId

The id of the folder

variableId

The id of the folder variable

The response contains the folder variable:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 315
Content-Type: application/json

{
  "id" : "Variable3017d802dfd24fca9531d6ae61696bae",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder091eed5e2dc44691abb04b1a462f56b0",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}

Create folder variable

To add new folder variable, send this request:

HTTP Request
POST /api/v1/folders/Applications/Folder3ec66885a5c14604942f025d6ca265c2/variables

{
  "id" : null,
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder3ec66885a5c14604942f025d6ca265c2",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder3ec66885a5c14604942f025d6ca265c2/variables' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : null,
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder3ec66885a5c14604942f025d6ca265c2",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder3ec66885a5c14604942f025d6ca265c2",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder3ec66885a5c14604942f025d6ca265c2/variables' \
    'Content-Type:application/json'

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 folder variable:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 315
Content-Type: application/json

{
  "id" : "Variableb4adc46bd2724c02946172681e66e628",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder3ec66885a5c14604942f025d6ca265c2",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}

Update folder variable

To update a folder variable, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d/Variableb4720bef31d147efa1a3d341365c8cbe

{
  "id" : "Variableb4720bef31d147efa1a3d341365c8cbe",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "new value",
  "multiline" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d/Variableb4720bef31d147efa1a3d341365c8cbe' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Variableb4720bef31d147efa1a3d341365c8cbe",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "new value",
  "multiline" : false
}'
HTTPie
$ echo '{
  "id" : "Variableb4720bef31d147efa1a3d341365c8cbe",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "new value",
  "multiline" : false
}' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d/Variableb4720bef31d147efa1a3d341365c8cbe' \
    'Content-Type:application/json'

Using the following path parameters:

Table 68. /api/v1/folders/{folderId}/{variableId}
Parameter Description

folderId

The id of the folder

variableId

The id of the folder variable

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

folderId

String

If set, this field contains the folder that this configuration belongs to.

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

inherited

Boolean

Determines whether the variable value is inherited from the template variable. Used in the Create Release Task only.

value

String

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

multiline

Boolean

If checked variable value will be multiline text

The response contains the updated folder variable:

HTTP/1.1 200 OK
Content-Length: 319
Content-Language: en
Content-Type: application/json

{
  "id" : "Variableb4720bef31d147efa1a3d341365c8cbe",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldercb2e9a3cc19544a8a5cc638ab208b10d",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "new value",
  "multiline" : false
}

Delete folder variable

To delete a folder variable, send this request

HTTP Request
DELETE /api/v1/folders/Applications/Folderc4ba95d4e8864a6290bfe9db0404f23f/Variableb1d97907f9344c05a7a20fadd6567075
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderc4ba95d4e8864a6290bfe9db0404f23f/Variableb1d97907f9344c05a7a20fadd6567075' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/folders/Applications/Folderc4ba95d4e8864a6290bfe9db0404f23f/Variableb1d97907f9344c05a7a20fadd6567075' \
    'Accept:application/json'

Using the following path parameters:

Table 69. /api/v1/folders/{folderId}/{variableId}
Parameter Description

folderId

The id of the folder

variableId

The id of the folder variable

You will receive this empty response:

HTTP/1.1 204 No Content
Content-Language: en

Shared configuration

All the configuration objects can be created globally or inside a folder. The folderId field in the configuration object stores the id of the folder where you can create the configuration.

Searching for configuration objects

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

HTTP Request
GET /api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server&folderId=Applications/Folder9c00a7c590084da1b9e37d2f478a25a6&folderOnly=true
Curl
$ curl 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server&folderId=Applications/Folder9c00a7c590084da1b9e37d2f478a25a6&folderOnly=true' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server&folderId=Applications/Folder9c00a7c590084da1b9e37d2f478a25a6&folderOnly=true' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

configurationType

Type of the Configuration object

title

The title of the Configuration object

folderId

The (optional) id of a possible folder that has configurations

folderOnly

The (optional) folderOnly gets the configurations of a folder (true), or a folder including all of its parents configurations (false)

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

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 211

[ {
  "id" : "Configuration/Custom/Configuration67a6551a43a44054942f0cf0ce979359",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder9c00a7c590084da1b9e37d2f478a25a6",
  "title" : "my JIRA server"
} ]

If the configuration is created globally, the folderId field will not be in the body of the response.

Get configuration object

To retrieve the configuration object for a given ID, execute the following command:

HTTP Request
GET /api/v1/config/Configuration/Custom/Configurationd71b18bf3f0c42b4ada593ed40d11d58
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationd71b18bf3f0c42b4ada593ed40d11d58' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationd71b18bf3f0c42b4ada593ed40d11d58' \
    'Accept:application/json'

Using the following parameters:

Table 70. /api/v1/config/{configurationId}
Parameter Description

configurationId

Full identifier of the configuration instance; for example, Configuration/Custom/Configuration1

The response contains the configuration object:

HTTP/1.1 200 OK
Content-Length: 560
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/Custom/Configurationd71b18bf3f0c42b4ada593ed40d11d58",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderc1fc25506d454fb5a73bc5fcbb32386e",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "{aes:v0}v2l4r0UoOZtZDfVBNCV3jVtbxdgWaVqne5M7NCqI0uY=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}Q8swNQpjGGAbCUn39bxWXpjBJfCUpWRahwnXZF3xtcejKvlUJTtAQT7oVsf46GP/"
}

If the configuration is created globally, the folderId field will not be in the body of the response.

Create configuration

To create a new configuration object, execute the following command:

HTTP Request
POST /api/v1/config

{
  "id" : "null",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder4b1dfa5cabd747cd82dbb0255769d8ce",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}
Curl
$ curl 'http://localhost:5516/api/v1/config' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "null",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder4b1dfa5cabd747cd82dbb0255769d8ce",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}'
HTTPie
$ echo '{
  "id" : "null",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder4b1dfa5cabd747cd82dbb0255769d8ce",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}' | http POST 'http://localhost:5516/api/v1/config' \
    'Accept:application/json' \
    'Content-Type:application/json'

The response contains the created configuration object:

HTTP/1.1 200 OK
Content-Length: 560
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/Custom/Configurationcff3493f935a422996902338485ec4a4",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder4b1dfa5cabd747cd82dbb0255769d8ce",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "{aes:v0}JwGVgv0gLnPJ1bY5voMccuOdcWBpUi1XVhEhkFcKhTE=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}/87Z/JRxBMpKA2UEdWMSgGdTmOnfVzm1KTGj3qhlch2ToxW9CYAd2QIVe3ii6Go0"
}

If a global configuration is needed, remove the folderId field from the body of the request.

Update configuration

To update a configuration object with a given ID, execute the following command:

HTTP Request
PUT /api/v1/config/Configuration/Custom/Configurationeba63be945f84600aaa23f7e69228a49

{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb9a6a047c596428d89a6ca4253d8f3ff",
  "title" : "Changed jira title",
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationeba63be945f84600aaa23f7e69228a49' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb9a6a047c596428d89a6ca4253d8f3ff",
  "title" : "Changed jira title",
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}'
HTTPie
$ echo '{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb9a6a047c596428d89a6ca4253d8f3ff",
  "title" : "Changed jira title",
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "jira password",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "proxyPassword value"
}' | http PUT 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationeba63be945f84600aaa23f7e69228a49' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following parameters:

Table 71. /api/v1/config/{configurationId}
Parameter Description

configurationId

Full identifier of the configuration instance; for example, Configuration/Custom/Configuration1

The response contains the updated configuration object:

HTTP/1.1 200 OK
Content-Length: 560
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/Custom/Configurationeba63be945f84600aaa23f7e69228a49",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb9a6a047c596428d89a6ca4253d8f3ff",
  "title" : "Changed jira title",
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "{aes:v0}aI3DleR7gMJVnlhoCB+PbH2Gkz8ckcP2Hm5OdZAKFJ8=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}A9+yHApcatKwEWKTXj4DSl3pW8ZBoK6HAhyrh5KBehSPFyprboLcwgZNDsAUtTyW"
}

Delete configuration

To delete a configuration object with a given ID, execute the following command:

HTTP Request
DELETE /api/v1/config/Configuration/Custom/Configuration2c4fb07b49c441a9aa89dc700891f11f
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration2c4fb07b49c441a9aa89dc700891f11f' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration2c4fb07b49c441a9aa89dc700891f11f' \
    'Accept:application/json'

Using the following parameters:

Table 72. /api/v1/config/{configurationId}
Parameter Description

configurationId

Full identifier of the configuration instance; for example, Configuration/Custom/Configuration1

The response is empty with the status code 204.

System message configuration

Get system message configuration

To retrieve the system message configuration, execute the following command:

HTTP Request
GET /api/v1/config/system-message
Curl
$ curl 'http://localhost:5516/api/v1/config/system-message' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/system-message' \
    'Accept:application/json'

The response contain system message configuration:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 149
Content-Type: application/json

{
  "id" : "Configuration/settings/SystemMessageSettings",
  "type" : "xlrelease.SystemMessageSettings",
  "enabled" : false,
  "automated" : false
}

Update an system message configuration

To update system message configuration, send the following request:

HTTP Request
PUT /api/v1/config/system-message

{
  "id" : "Configuration/settings/SystemMessageSettings",
  "type" : "xlrelease.SystemMessageSettings",
  "enabled" : true,
  "message" : "The system will be down from 11.12.2018 - 01.01.2019",
  "automated" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/config/system-message' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Configuration/settings/SystemMessageSettings",
  "type" : "xlrelease.SystemMessageSettings",
  "enabled" : true,
  "message" : "The system will be down from 11.12.2018 - 01.01.2019",
  "automated" : false
}'
HTTPie
$ echo '{
  "id" : "Configuration/settings/SystemMessageSettings",
  "type" : "xlrelease.SystemMessageSettings",
  "enabled" : true,
  "message" : "The system will be down from 11.12.2018 - 01.01.2019",
  "automated" : false
}' | http PUT 'http://localhost:5516/api/v1/config/system-message' \
    'Accept:application/json' \
    'Content-Type:application/json'

The response contain updated system message configuration:

HTTP/1.1 200 OK
Content-Length: 218
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/settings/SystemMessageSettings",
  "type" : "xlrelease.SystemMessageSettings",
  "enabled" : true,
  "message" : "The system will be down from 11.12.2018 - 01.01.2019",
  "automated" : false
}

Working with DSL

In XL Release you can use DSL code to define releases. It is possible to export DSL code from an existing template.

dashboards and activity logs are not exported.

Exporting template as DSL

To export DSL code of a template send this request:

HTTP Request
GET /api/v1/dsl/export/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false
Curl
$ curl 'http://localhost:5516/api/v1/dsl/export/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/dsl/export/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false'

Using the following parameters:

Table 73. /api/v1/dsl/export/{templateId}
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

Parameter Description

exportTemplate

The (optional) boolean to render the DSL as template, otherwise will render as release

You will receive a zip file with the name of the template. Inside of it will be the DSL file ("Releasefile.groovy") and attachments ("attachments/" directory) if any exist.

Previewing the template DSL

To preview the DSL code of a template send this request:

HTTP Request
GET /api/v1/dsl/preview/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false
Curl
$ curl 'http://localhost:5516/api/v1/dsl/preview/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/dsl/preview/Applications/Release162151faba694d03aa3065665cf26f21?exportTemplate=false'

Using the following parameters:

Table 74. /api/v1/dsl/preview/{templateId}
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

Parameter Description

exportTemplate

The (optional) boolean to render the DSL as template, otherwise will render as release

You will receive the DSL code that defines a template as string:

HTTP/1.1 200 OK
Content-Length: 1151
Content-Language: en
Content-Type: text/plain;charset=UTF-8

// Exported from:        http://jenkins-slave25-xlr.xebialabs.com:0/#/templates/Release162151faba694d03aa3065665cf26f21/releasefile
// XL Release version:   9.5.6-SNAPSHOT
// Date created:         Mon Mar 15 11:24:05 CET 2021

xlr {
  release('Sample XLR template') {
    variables {
      stringVariable('manualTaskTitle') {
        value 'Manual task title'
      }
      passwordVariable('jiraPassword') {
        value '{aes:v0}WqL49lMSak8BFRJmWnY9+2G6y2CZ1UbJZDjK7Y/LvAA='
      }
      mapVariable('foundIssues') {

      }
    }
    description 'XLR template to demonstrate DSL export functionality'
    phases {
      phase('Sample phase') {
        tasks {
          manual('${manualTaskTitle}') {

          }
          custom('Query JIRA') {
            script {
              type 'jira.Query'
              jiraServer 'XL JIRA test instance'
              username '${jiraUser}'
              password variable('jiraPassword')
              query 'project = "XL Release" AND status = "OPEN" ORDER BY createdDate DESC'
              issues variable('foundIssues')
            }
          }
        }
      }
    }
  }
}

Security API

User management

All API calls under User management require the security#edit global role. If you do not have that permission, you can still get information about your username, edit your profile and change password.

Finding users

To list all the users:

HTTP Request
GET /api/v1/users
Curl
$ curl 'http://localhost:5516/api/v1/users' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/users' \
    'Accept:application/json'

This will return a list of the first 100 users by default. You can use the parameters page and resultsPerPage to retrieve new users.

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 521

[ {
  "username" : "admin",
  "external" : false,
  "profileId" : "admin",
  "email" : "",
  "fullName" : "XL Release Administrator",
  "loginAllowed" : true,
  "dateFormat" : null,
  "timeFormat" : null,
  "firstDayOfWeek" : 0,
  "lastActive" : null
}, {
  "username" : "user1",
  "external" : false,
  "profileId" : "user1",
  "email" : "email@mail.com",
  "fullName" : "John Doe",
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "HH:mm",
  "firstDayOfWeek" : 0,
  "lastActive" : 1540378800000
} ]

You can also search for users using query parameters:

HTTP Request
GET /api/v1/users?email=email@mail.com&lastActiveBefore=1540380600000
Curl
$ curl 'http://localhost:5516/api/v1/users?email=email@mail.com&lastActiveBefore=1540380600000' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/users?email=email@mail.com&lastActiveBefore=1540380600000' \
    'Accept:application/json'

See the following table for all the different applicable query parameters:

Parameter Description

email

Email of the user.

fullName

Name of the user.

loginAllowed

Is login allowed for the user.

lastActiveAfter

Select users last active after this timestamp

lastActiveBefore

Select users last active before this timestamp

page

The (optional) page of results to return. Default value is 0.

resultsPerPage

The (optional) number of results per page. Default value is 100.

The response fields explained:

Path Type Description

[].username

String

The username.

[].external

Boolean

Flag that specifies if the user is coming from an external source.

[].profileId

String

The CI ID of the user profile.

[].email

Varies

The email of the user.

[].fullName

Varies

The full name of the user.

[].loginAllowed

Boolean

Whether user is allowed to login or not

[].dateFormat

Varies

The profile setting for the date format.

[].timeFormat

Varies

The profile setting for the time format.

[].firstDayOfWeek

Number

The profile setting for the first day of week.

[].lastActive

Number

The timestamp corresponding to the last time this user interacted with XL Release

Get a single user

If you know the username, you can get the user information as follows:

HTTP Request
GET /api/v1/users/user1
Curl
$ curl 'http://localhost:5516/api/v1/users/user1' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/users/user1' \
    'Accept:application/json'
Table 75. /api/v1/users/{username}
Parameter Description

username

The username to retrieve information from.

Create new users

You can create single users as follows:

HTTP Request
POST /api/v1/users/user2

{
  "password" : "mySuperPassword",
  "loginAllowed" : true,
  "fullName" : "My new User"
}
Curl
$ curl 'http://localhost:5516/api/v1/users/user2' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "password" : "mySuperPassword",
  "loginAllowed" : true,
  "fullName" : "My new User"
}'
HTTPie
$ echo '{
  "password" : "mySuperPassword",
  "loginAllowed" : true,
  "fullName" : "My new User"
}' | http POST 'http://localhost:5516/api/v1/users/user2' \
    'Content-Type:application/json'
Path Type Description

email

String

The email of the user.

fullName

String

The full name of the user.

loginAllowed

Boolean

The login permission for the user.

dateFormat

Varies

The profile setting for the date format.

timeFormat

Varies

The profile setting for the time format.

firstDayOfWeek

Number

The profile setting for the first day of week.

Table 76. /api/v1/users/{username}
Parameter Description

username

The username from the user to be created.

User preferences

Table 77. Dates
Option Possible values

dateFormat

Empty, "M/d/yy", "dd/MM/yy", "yy/MM/dd"

timeFormat

Empty, "HH:mm", "h:mm a"

firstDayOfWeek

-1, 0, 1

For more information about these settings, see Personal settings

Update users

To update a single user:

HTTP Request
PUT /api/v1/users/user1

{
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
}
Curl
$ curl 'http://localhost:5516/api/v1/users/user1' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
}'
HTTPie
$ echo '{
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
}' | http PUT 'http://localhost:5516/api/v1/users/user1' \
    'Content-Type:application/json'
Path Type Description

email

String

The email of the user.

fullName

String

The full name of the user.

loginAllowed

Boolean

The login permission for the user.

dateFormat

Varies

The profile setting for the date format.

timeFormat

Varies

The profile setting for the time format.

firstDayOfWeek

Number

The profile setting for the first day of week.

Table 78. /api/v1/users/{username}
Parameter Description

username

The username from the user to be updated.

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 236
Content-Type: application/json

{
  "username" : "user1",
  "external" : false,
  "profileId" : null,
  "email" : null,
  "fullName" : null,
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0,
  "lastActive" : null
}
You cannot set or change the password with this operation, see Change password section.

It is also possible to do a multiple user update by passing a list of users to update:

HTTP Request
PUT /api/v1/users

[ {
  "username" : "user1",
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
} ]
Curl
$ curl 'http://localhost:5516/api/v1/users' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ {
  "username" : "user1",
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
} ]'
HTTPie
$ echo '[ {
  "username" : "user1",
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0
} ]' | http PUT 'http://localhost:5516/api/v1/users' \
    'Content-Type:application/json'

Change password

HTTP Request
POST /api/v1/users/user1/password

{
  "currentPassword" : "myPassword",
  "newPassword" : "myNewPassword"
}
Curl
$ curl 'http://localhost:5516/api/v1/users/user1/password' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "currentPassword" : "myPassword",
  "newPassword" : "myNewPassword"
}'
HTTPie
$ echo '{
  "currentPassword" : "myPassword",
  "newPassword" : "myNewPassword"
}' | http POST 'http://localhost:5516/api/v1/users/user1/password' \
    'Content-Type:application/json'
Path Type Description

currentPassword

String

The current password of the user, only required if you change your own password.

newPassword

String

The new password of the user.

Table 79. /api/v1/users/{username}/password
Parameter Description

username

The username from the user to change password.

You cannot change the password for an external user, it will return a 400 Bad request HTTP code.

Delete a user

If you want to delete a user:

HTTP Request
DELETE /api/v1/users/user3
Curl
$ curl 'http://localhost:5516/api/v1/users/user3' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/users/user3'
Table 80. /api/v1/users/{username}
Parameter Description

username

The username of the user to be deleted.

You can also use this API call to delete user profiles of external users.

Global Roles & Permissions

List all permissions

To list global permissions, execute this command:

HTTP Request
GET /api/v1/global-permissions
Curl
$ curl 'http://localhost:5516/api/v1/global-permissions' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/global-permissions' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Length: 335
Content-Type: application/json

[ "admin", "security#edit", "report#view", "template#create", "release#create", "reports#view", "all#audit", "dashboard#create", "global_variables#edit", "folder#create_top_level", "global_calendar#edit_blackout", "risk_profile#edit", "environment#edit", "environment#view", "application#edit", "application#view", "reservation#edit" ]

List all roles

To list global roles, execute this command:

HTTP Request
GET /api/v1/roles?page=0&resultsPerPage=2
Curl
$ curl 'http://localhost:5516/api/v1/roles?page=0&resultsPerPage=2' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/roles?page=0&resultsPerPage=2' \
    'Accept:application/json'

which returns:

HTTP/1.1 200 OK
Content-Length: 294
Content-Language: en
Content-Type: application/json

[ {
  "name" : "Developers",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}, {
  "name" : "RoleWithAdminPermission",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "admin",
    "fullname" : "XL Release Administrator"
  } ]
} ]

Get a single role

To retrieve information for a single role, execute this command:

HTTP Request
GET /api/v1/roles/Developers
Curl
$ curl 'http://localhost:5516/api/v1/roles/Developers' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/roles/Developers' \
    'Accept:application/json'

with the following path parameters:

Table 81. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

which returns:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 127
Content-Type: application/json
X-Total-Count: 1

{
  "name" : "Developers",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}

Response fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

principals[0].username

String

This field contains principals username.

principals[0].fullname

Null

This field contains principals fullname.

Create a new role

To create a single role, execute this command:

HTTP Request
POST /api/v1/roles/Testers

{
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}
Curl
$ curl 'http://localhost:5516/api/v1/roles/Testers' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}'
HTTPie
$ echo '{
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}' | http POST 'http://localhost:5516/api/v1/roles/Testers' \
    'Accept:application/json' \
    'Content-Type:application/json'

with the following path parameters:

Table 82. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

Request fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

principals[0].username

String

This field contains principals username.

principals[0].fullname

String

This field contains principals fullname.

Create a list of roles

To create multiple roles, execute this command:

HTTP Request
POST /api/v1/roles

[ {
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Admins",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "jcoltrane",
    "fullname" : "jcoltrane Smith"
  } ]
} ]
Curl
$ curl 'http://localhost:5516/api/v1/roles' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '[ {
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Admins",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "jcoltrane",
    "fullname" : "jcoltrane Smith"
  } ]
} ]'
HTTPie
$ echo '[ {
  "name" : "Testers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Admins",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "jcoltrane",
    "fullname" : "jcoltrane Smith"
  } ]
} ]' | http POST 'http://localhost:5516/api/v1/roles' \
    'Accept:application/json' \
    'Content-Type:application/json'

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]permissions

Array

This field contains permissions granted to the role.

[]principals

Array

This field contains principals.

[]principals[0].username

String

This field contains principals username.

[]principals[0].fullname

String

This field contains principals fullname.

Update a role

To update a role, execute this command:

HTTP Request
PUT /api/v1/roles/Developers

{
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}
Curl
$ curl 'http://localhost:5516/api/v1/roles/Developers' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}'
HTTPie
$ echo '{
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}' | http PUT 'http://localhost:5516/api/v1/roles/Developers' \
    'Accept:application/json' \
    'Content-Type:application/json'

with the following path parameters:

Table 83. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

Request fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

principals[0].username

String

This field contains principals username.

principals[0].fullname

String

This field contains principals fullname.

Update a list of roles

To update a list of roles, execute this command:

HTTP Request
PUT /api/v1/roles

[ {
  "name" : "Developers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Operations",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "mdavis",
    "fullname" : "mdavis Smith"
  } ]
} ]
Curl
$ curl 'http://localhost:5516/api/v1/roles' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '[ {
  "name" : "Developers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Operations",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "mdavis",
    "fullname" : "mdavis Smith"
  } ]
} ]'
HTTPie
$ echo '[ {
  "name" : "Developers",
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}, {
  "name" : "Operations",
  "permissions" : [ "admin" ],
  "principals" : [ {
    "username" : "mdavis",
    "fullname" : "mdavis Smith"
  } ]
} ]' | http PUT 'http://localhost:5516/api/v1/roles' \
    'Accept:application/json' \
    'Content-Type:application/json'

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]permissions

Array

This field contains permissions granted to the role.

[]principals

Array

This field contains principals.

[]principals[0].username

String

This field contains principals username.

[]principals[0].fullname

String

This field contains principals fullname.

Rename role

To rename a role, execute this command:

HTTP Request
POST /api/v1/roles/Developers/rename?newName=New%20Developers

newName=New+Developers
Curl
$ curl 'http://localhost:5516/api/v1/roles/Developers/rename?newName=New%20Developers' -i -X POST
HTTPie
$ http POST 'http://localhost:5516/api/v1/roles/Developers/rename?newName=New%20Developers'

with the following path parameters:

Table 84. /api/v1/roles/{roleName}/rename
Parameter Description

roleName

Name of the role

and request parameters and their description:

Parameter Description

newName

New name of the role

Delete role

To delete a role, execute this command:

HTTP Request
DELETE /api/v1/roles/Developers
Curl
$ curl 'http://localhost:5516/api/v1/roles/Developers' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/roles/Developers'

with the following path parameters:

Table 85. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

Folder / template / release permissions

Note that:

  • Call to folders returns permissions for folders, templates and releases.

  • Call to templates returns permissions for templates and releases.

  • Call to releases returns permissions for releases only.

List possible permissions on a folder

To list permissions that can be used on a folder, execute this command:

HTTP Request
GET /api/v1/folders/permissions
Curl
$ curl 'http://localhost:5516/api/v1/folders/permissions' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/permissions' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Length: 859
Content-Type: application/json

[ "folder#view", "folder#edit", "folder#edit_security", "folder#edit_teams", "folder#edit_configuration", "folder#edit_variables", "template#create_release", "template#view", "template#edit", "template#edit_security", "template#edit_triggers", "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#edit_task_script", "release#edit_task_input_output_properties", "release#edit_task_configuration_facet", "release#reassign_task", "release#edit_blackout", "release#task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#lock_task", "template#lock_task", "release#edit_failure_handler", "template#edit_failure_handler", "release#edit_precondition", "template#edit_precondition" ]

List possible permissions on a template

To list permissions that can be used on a folder, execute this command:

HTTP Request
GET /api/v1/templates/permissions
Curl
$ curl 'http://localhost:5516/api/v1/templates/permissions' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/permissions' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 730

[ "template#create_release", "template#view", "template#edit", "template#edit_security", "template#edit_triggers", "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#edit_task_script", "release#edit_task_input_output_properties", "release#edit_task_configuration_facet", "release#reassign_task", "release#edit_blackout", "release#task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#lock_task", "template#lock_task", "release#edit_failure_handler", "template#edit_failure_handler", "release#edit_precondition", "template#edit_precondition" ]

List possible permissions on a release

To list permissions that can be used on a folder, execute this command:

HTTP Request
GET /api/v1/releases/permissions
Curl
$ curl 'http://localhost:5516/api/v1/releases/permissions' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/permissions' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 532

[ "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#edit_task_script", "release#edit_task_input_output_properties", "release#edit_task_configuration_facet", "release#reassign_task", "release#edit_blackout", "release#task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#lock_task", "release#edit_failure_handler", "release#edit_precondition" ]

List all teams

Get all teams and permissions on a folder

To list teams and permissions on a folder, execute this command:

HTTP Request
GET /api/v1/folders/Applications/Folder39797da816c149cbb46a2e4025bcc676/teams
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder39797da816c149cbb46a2e4025bcc676/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder39797da816c149cbb46a2e4025bcc676/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Length: 2006
Content-Type: application/json

[ {
  "id" : "Applications/Folder39797da816c149cbb46a2e4025bcc676/Team899219a91aa74ac38134d12a37a10787",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder39797da816c149cbb46a2e4025bcc676/Team5bcc97b5c01d4ce0b46cd436b355ec82",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder39797da816c149cbb46a2e4025bcc676/Teamf402defe071a4579a01d913938c55c25",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 86. /api/v1/folders/{folderId}/teams
Parameter Description

folderId

The folder Id

The response fields explained:

Path Type Description

[]id

String

Id of the team

[]teamName

String

Name of the team

[]members

Array

Team members. Can be roles and principals.

[]members[].name

String

Team member username.

[]members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[]members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[]members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Get all teams and permissions on a template

To list teams and permissions on a template, execute this command:

HTTP Request
GET /api/v1/templates/Applications/Releasebb95d4949cf04118a456182e2534a76b/teams
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Releasebb95d4949cf04118a456182e2534a76b/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/Applications/Releasebb95d4949cf04118a456182e2534a76b/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1900

[ {
  "id" : "Applications/Releasebb95d4949cf04118a456182e2534a76b/Teamf0964dd2ef0a47f9a64299df2bf8958a",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Releasebb95d4949cf04118a456182e2534a76b/Team64f6d07403914f52908dcbdb987c96d2",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Releasebb95d4949cf04118a456182e2534a76b/Team38b557f03850462db9a192d5e05dcad8",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Releasebb95d4949cf04118a456182e2534a76b/Team23569e32fb1841c5afdd14d6b68d49fe",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

Table 87. /api/v1/templates/{templateId}/teams
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

The response fields explained:

Path Type Description

[]id

String

Id of the team

[]teamName

String

Name of the team

[]members

Array

Team members. Can be roles and principals.

[]members[].name

String

Team member username.

[]members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[]members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[]members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Get all teams and permissions on a release

To list teams and permissions on a release, execute this command:

HTTP Request
GET /api/v1/releases/Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/teams
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1900

[ {
  "id" : "Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/Teamc89b2684d8be464b82a809abe5d04f95",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/Team3cf545e16d4944e5b3d15439626769ef",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/Team222e38b608664057b69c3a188280d6a6",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Releasedc7cba6f20c848c1a98b6f33b0a0f7df/Team951a9ca17aa149a3bcedc1c82478f692",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 88. /api/v1/releases/{releaseId}/teams
Parameter Description

releaseId

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

The response fields explained:

Path Type Description

[].id

String

Id of the team

[].teamName

String

Name of the team

[].members

Array

Team members. Can be roles and principals.

[].members[].name

String

Team member username.

[].members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[].members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[].members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[].permissions

Array

Names of the team permissions.

[].systemTeam

Boolean

Marks teams provided by the system.

Update teams

Set all teams and permissions on a folder

This API does not support partial updates. You must include all teams and the system teams (Template Owner, Release Admin, and Folder Owner). To set all teams and permissions on a folder, execute this command:

HTTP Request
POST /api/v1/folders/Applications/Folder678d12697e694e11bc2849cfeb70af7e/teams

[ {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team5c6bcd18ec864646b830601bba8a5430",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team745d0a754dc44322a87e42ae44259616",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Teamb3947ee8274148b2a18f4db513f4148c",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view", "release#edit" ],
  "systemTeam" : true
} ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder678d12697e694e11bc2849cfeb70af7e/teams' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '[ {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team5c6bcd18ec864646b830601bba8a5430",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team745d0a754dc44322a87e42ae44259616",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Teamb3947ee8274148b2a18f4db513f4148c",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view", "release#edit" ],
  "systemTeam" : true
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team5c6bcd18ec864646b830601bba8a5430",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team745d0a754dc44322a87e42ae44259616",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Teamb3947ee8274148b2a18f4db513f4148c",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view", "release#edit" ],
  "systemTeam" : true
} ]' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder678d12697e694e11bc2849cfeb70af7e/teams' \
    'Accept:application/json' \
    'Content-Type:application/json'
HTTP/1.1 200 OK
Content-Length: 2022
Content-Language: en
Content-Type: application/json

[ {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team5c6bcd18ec864646b830601bba8a5430",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Team745d0a754dc44322a87e42ae44259616",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "release#edit_failure_handler", "folder#view", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder678d12697e694e11bc2849cfeb70af7e/Teamb3947ee8274148b2a18f4db513f4148c",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "group#view", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "dashboard#edit", "folder#edit_security", "folder#edit", "dashboard#view", "release#edit" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 89. /api/v1/folders/{folderId}/teams
Parameter Description

folderId

The folder Id

The response fields explained:

Path Type Description

[]id

String

Id of the team

[]teamName

String

Name of the team

[]members

Array

Team members. Can be roles and principals.

[]members[].name

String

Team member username.

[]members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[]members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[]members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Set all teams and permissions on a template

This API does not support partial updates. You must include all teams and the system teams (Template Owner and Release Admin). To set all teams and permissions on a template

HTTP Request
POST /api/v1/templates/Applications/Release8ec7e1982d1c4b7e933891b324a663e7/teams

[ {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team967b327bc0064ac181ef58b55702d54a",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamd1a68061ba254ee9b1220d73077cec8f",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamc5f423481a5249bc9343953acfca376d",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team47e32c5ef7de40dfb818350d6ad7a4f9",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
} ]
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release8ec7e1982d1c4b7e933891b324a663e7/teams' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '[ {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team967b327bc0064ac181ef58b55702d54a",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamd1a68061ba254ee9b1220d73077cec8f",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamc5f423481a5249bc9343953acfca376d",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team47e32c5ef7de40dfb818350d6ad7a4f9",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team967b327bc0064ac181ef58b55702d54a",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamd1a68061ba254ee9b1220d73077cec8f",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamc5f423481a5249bc9343953acfca376d",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team47e32c5ef7de40dfb818350d6ad7a4f9",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
} ]' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release8ec7e1982d1c4b7e933891b324a663e7/teams' \
    'Accept:application/json' \
    'Content-Type:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1998

[ {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team967b327bc0064ac181ef58b55702d54a",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamd1a68061ba254ee9b1220d73077cec8f",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Teamc5f423481a5249bc9343953acfca376d",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release8ec7e1982d1c4b7e933891b324a663e7/Team47e32c5ef7de40dfb818350d6ad7a4f9",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 90. /api/v1/templates/{templateId}/teams
Parameter Description

templateId

Full template identifier; for example, Applications/Release1

The response fields explained:

Path Type Description

[]id

String

Id of the team

[]teamName

String

Name of the team

[]members

Array

Team members. Can be roles and principals.

[]members[].name

String

Team member username.

[]members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[]members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[]members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Set all teams and permissions on a release

This API does not support partial updates. You must include all teams and the system teams (Template Owner and Release Admin).

To set all teams and permissions on a release, execute this command:

HTTP Request
POST /api/v1/releases/Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/teams

[ {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamc947ded5fe2a430a8aa9ec709e86217c",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Team20057abe06e94e36a5301ad4ca9f4a3a",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamd1f4253b98214b37ac2665a40db38f21",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamdee0b6a98a6049a08dfd19255bd457c2",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/teams' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '[ {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamc947ded5fe2a430a8aa9ec709e86217c",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Team20057abe06e94e36a5301ad4ca9f4a3a",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamd1f4253b98214b37ac2665a40db38f21",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamdee0b6a98a6049a08dfd19255bd457c2",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamc947ded5fe2a430a8aa9ec709e86217c",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Team20057abe06e94e36a5301ad4ca9f4a3a",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamd1f4253b98214b37ac2665a40db38f21",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamdee0b6a98a6049a08dfd19255bd457c2",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/teams' \
    'Accept:application/json' \
    'Content-Type:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1999

[ {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamc947ded5fe2a430a8aa9ec709e86217c",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#edit", "template#lock_task", "template#view", "template#edit_triggers", "template#edit_precondition", "template#edit_security", "template#create_release", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Team20057abe06e94e36a5301ad4ca9f4a3a",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamd1f4253b98214b37ac2665a40db38f21",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release58741f3d1b0b435d8c008d0a7e467a4d/Teamdee0b6a98a6049a08dfd19255bd457c2",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#task_transition", "release#edit_task_attachments", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_security", "release#edit_task_description", "release#view", "release#lock_task", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 91. /api/v1/releases/{releaseId}/teams
Parameter Description

releaseId

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

The response fields explained:

Path Type Description

[].id

String

Id of the team

[].teamName

String

Name of the team

[].members

Array

Team members. Can be roles and principals.

[].members[].name

String

Team member username.

[].members[].fullName

Varies

Team member full name. Can be null (for roles or users with just username).

[].members[].type

String

Team member type. Can be ROLE or PRINCIPAL.

[].members[].roleId

String

Id of the role. Can be null (for member type PRINCIPAL).

[].permissions

Array

Names of the team permissions.

[].systemTeam

Boolean

Marks teams provided by the system.

Risk

The risk score is a calculation for the health of a release and how critical are the issues.

Release risk score

To retrieve the release risk score, send this request:

HTTP Request
GET /api/v1/risks/Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk
Curl
$ curl 'http://localhost:5516/api/v1/risks/Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk' \
    'Accept:application/json'

Using the following path parameters:

Table 92. /api/v1/risks/{releaseId}/Risk
Parameter Description

releaseId

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

The response contains the risk score for the release:

HTTP/1.1 200 OK
Content-Length: 6569
Content-Language: en
Content-Type: application/json

{
  "id" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
  "type" : "xlrelease.Risk",
  "score" : 30,
  "totalScore" : 30,
  "riskAssessments" : [ {
    "id" : "70366726",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseDueDateRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 30,
    "headline" : "Release is overdue",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21 is overdue since 2021-03-15T11:23:55.379" ]
  }, {
    "id" : "725004211",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailedRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2091557377",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/MoreThanOneTaskOverDueRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1220906810",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor3Retries",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1103991202",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor5Retries",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1595467039",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1988882007",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/OneTaskOverDueRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "315823075",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessorMoreThan5Retries",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1069469850",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAttentionNeededRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "664205935",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "247878044",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor4Retries",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "67110828",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1307786678",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1562829797",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1641026412",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailingRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1709790621",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAtRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "832821787",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor2Retries",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1542471169",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "987372896",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagNeedsAttentionRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "355529243",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagAtRiskRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "988578212",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Releasec961f05e40ee4bc2b773f681b3dae87f/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  } ]
}

Global risk thresholds

Global risk thresholds are configurable thresholds that the risk score will be calculated based on. To retrieve the global risk thresholds configuration, send this request:

HTTP Request
GET /api/v1/risks/config
Curl
$ curl 'http://localhost:5516/api/v1/risks/config' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/config' \
    'Accept:application/json'

The response contains the global risk thresholds configuration:

HTTP/1.1 200 OK
Content-Length: 151
Content-Language: en
Content-Type: application/json

{
  "id" : "Configuration/risks/RiskGlobalThresholds",
  "type" : "xlrelease.RiskGlobalThresholds",
  "atRiskFrom" : 50,
  "attentionNeededFrom" : 10
}

Risk profile

Create a risk profile

To create a new risk profile, send this request:

HTTP Request
POST /api/v1/risks/profiles

{
  "id" : null,
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 3",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "66",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "54",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "39",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "86",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "56",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "75",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33"
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : null,
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 3",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "66",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "54",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "39",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "86",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "56",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "75",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33"
  }
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 3",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "66",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "54",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "39",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "86",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "56",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "75",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33"
  }
}' | http POST 'http://localhost:5516/api/v1/risks/profiles' \
    'Accept:application/json' \
    'Content-Type:application/json'

The response contains the created risk profile object:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1205

{
  "id" : "Configuration/riskProfiles/RiskProfile4f64d7922a3b4e6db5515cc8d8e28207",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 3",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "66",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "54",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.OneTaskOverDueRiskAssessor" : "39",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "86",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "56",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "75",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69"
  }
}

Listing all risk profiles

Table 93. Risk Profile Assessors
Property name Description Default value

xlrelease.ReleaseFlaggedAtRiskAssessor

Release flag red

80

xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor

Release flag amber

30

xlrelease.ReleaseStatusFailedRiskAssessor

Release state failed

90

xlrelease.ReleaseStatusFailingRiskAssessor

Release state failing

70

xlrelease.ReleaseDueDateRiskAssessor

Release past due date

30

xlrelease.TaskWithOneFlagAtRiskRiskAssessor

Task flag red (1)

65

xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor

Task flag red (2-3)

70

xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor

Task flag red (4-6)

75

xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor

Task flag red (6+)

80

xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor

Task flag amber (1)

10

xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor

Task flag amber (2-3)

20

xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor

Task flag amber (4-6)

30

xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor

Task flag amber (6+)

40

xlrelease.OneTaskOverDueRiskAssessor

Current task past due

25

xlrelease.MoreThanOneTaskOverDueRiskAssessor

Multiple tasks past due

35

xlrelease.TaskRetriesRiskAssessor

1 retry for a failed task

50

xlrelease.TaskRetriesRiskAssessor2Retries

2 retries for a failed task

60

xlrelease.TaskRetriesRiskAssessor3Retries

3 retries for a failed task

70

xlrelease.TaskRetriesRiskAssessor4Retries

4 retries for a failed task

80

xlrelease.TaskRetriesRiskAssessor5Retries

5 retries for a failed task

90

xlrelease.TaskRetriesRiskAssessorMoreThan5Retries

6+ retries for a failed task

100

To retrieve the list of all risk profiles, send this request:

HTTP Request
GET /api/v1/risks/profiles
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/profiles' \
    'Accept:application/json'

The response contains all the risk profiles defined in the system:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 3892
Content-Type: application/json

[ {
  "id" : "Configuration/riskProfiles/RiskProfileDefault",
  "type" : "xlrelease.RiskProfile",
  "title" : "Default risk profile",
  "defaultProfile" : true,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor4Retries" : "80",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor5Retries" : "90",
    "xlrelease.TaskRetriesRiskAssessor3Retries" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.TaskRetriesRiskAssessorMoreThan5Retries" : "100",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskRetriesRiskAssessor2Retries" : "60",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75"
  }
}, {
  "id" : "Configuration/riskProfiles/RiskProfile64c96fdb57cf43a183ed0909e5e144d3",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 1",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75"
  }
}, {
  "id" : "Configuration/riskProfiles/RiskProfile66f7b44427624e389190e802748731f8",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 2",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "86",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "59",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "75",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69"
  }
} ]

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

[].folderId

String

If set, this field contains the folder that this configuration belongs to.

[].title

String

The name of risk profile.

[].defaultProfile

Boolean

Is this default risk profile.

[].riskProfileAssessors

Object

Risk Profile Assessors

Find risk profile by ID

To find a risk profile using a specific ID, send this request:

HTTP Request
GET /api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileb1de46fdd61443409e69326d0caabd34
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileb1de46fdd61443409e69326d0caabd34' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileb1de46fdd61443409e69326d0caabd34' \
    'Accept:application/json'

Using the following path parameters:

Table 94. /api/v1/risks/profiles/{riskProfileId}
Parameter Description

riskProfileId

Full identifier of the risk profile; for example, Configuration/riskProfiles/RiskProfile150970630496129498

The response contains the risk profile:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1205

{
  "id" : "Configuration/riskProfiles/RiskProfileb1de46fdd61443409e69326d0caabd34",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 1",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75"
  }
}

Update risk profile

To update a risk profile, send this request:

HTTP Request
PUT /api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c

{
  "id" : "Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk profile 2 updated",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "38",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "28",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "47",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "87",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "45",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "71",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "66",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "63"
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk profile 2 updated",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "38",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "28",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "47",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "87",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "45",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "71",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "66",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "63"
  }
}'
HTTPie
$ echo '{
  "id" : "Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk profile 2 updated",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "38",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "28",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "47",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "87",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "45",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "71",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "66",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "63"
  }
}' | http PUT 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following path parameters:

Table 95. /api/v1/risks/profiles/{riskProfileId}
Parameter Description

riskProfileId

Full identifier of the risk profile; for example, Configuration/riskProfiles/RiskProfile150970630496129498

Request fields 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.RiskProfile'.

folderId

String

If set, this field contains the folder that this configuration belongs to.

title

String

The name of risk profile.

defaultProfile

Boolean

Is this default risk profile.

riskProfileAssessors

Object

Risk Profile Assessors

The response contains the updated risk profile object:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 1213
Content-Type: application/json

{
  "id" : "Configuration/riskProfiles/RiskProfile9dd0d5a0dfff45efad2647da4959a48c",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk profile 2 updated",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseDueDateRiskAssessor" : "38",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "28",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "47",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "87",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "45",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "71",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "66",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "63",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69"
  }
}

Delete risk profile

To delete risk profile, send this request:

HTTP Request
DELETE /api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile3fc07256570e4b6b9fd21b7c856b56a0
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile3fc07256570e4b6b9fd21b7c856b56a0' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile3fc07256570e4b6b9fd21b7c856b56a0' \
    'Accept:application/json'

Using the following path parameters:

Table 96. /api/v1/risks/profiles/{riskProfileId}
Parameter Description

riskProfileId

Full identifier of the risk profile; for example, Configuration/riskProfiles/RiskProfile150970630496129498

The response is empty with the status code 204.

Risk profiles that are currently in use cannot be deleted and a 409 error will be returned if there is a call to delete such a risk profile.

Copy risk profile

To copy a risk profile, send this request:

HTTP Request
POST /api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileDefault/copy
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileDefault/copy' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfileDefault/copy' \
    'Accept:application/json'

Using the following path parameters:

Table 97. /api/v1/risks/profiles/{riskProfileId}/copy
Parameter Description

riskProfileId

Full identifier of the risk profile; for example, Configuration/riskProfiles/RiskProfile150970630496129498

The response contains the copied risk profile object:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 1504

{
  "id" : "Configuration/riskProfiles/RiskProfile4ffacc7a620640f7b9c5de1f2ef2b9b9",
  "type" : "xlrelease.RiskProfile",
  "title" : "Default risk profile (2)",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor4Retries" : "80",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor5Retries" : "90",
    "xlrelease.TaskRetriesRiskAssessor3Retries" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.TaskRetriesRiskAssessorMoreThan5Retries" : "100",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskRetriesRiskAssessor2Retries" : "60",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75"
  }
}

Listing all risk assessors

To retrieve the list of all risk assessors, send this request:

HTTP Request
GET /api/v1/risks/assessors
Curl
$ curl 'http://localhost:5516/api/v1/risks/assessors' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/assessors' \
    'Accept:application/json'

The response contains all risk assessors defined in the system:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 6017

[ {
  "id" : "Applications/ReleaseDueDateRiskAssessor",
  "type" : "xlrelease.ReleaseDueDateRiskAssessor",
  "title" : "Release past due date",
  "weight" : 1,
  "score" : 30,
  "order" : "4-pd-00",
  "group" : "Release past due date"
}, {
  "id" : "Applications/ReleaseStatusFailedRiskAssessor",
  "type" : "xlrelease.ReleaseStatusFailedRiskAssessor",
  "title" : "Release state failed",
  "weight" : 1,
  "score" : 90,
  "order" : "2-sf-00",
  "group" : "Release state failed"
}, {
  "id" : "Applications/MoreThanOneTaskOverDueRiskAssessor",
  "type" : "xlrelease.MoreThanOneTaskOverDueRiskAssessor",
  "title" : "> 1 task",
  "weight" : 1,
  "score" : 35,
  "order" : "7-od-01",
  "group" : "Current task(s) past due date"
}, {
  "id" : "Applications/TaskRetriesRiskAssessor3Retries",
  "type" : "xlrelease.TaskRetriesRiskAssessor3Retries",
  "weight" : 1,
  "group" : "Retries for a failed task",
  "order" : "8-rt-02",
  "minRetries" : 3,
  "maxRetries" : 3,
  "score" : 70,
  "title" : "3 retries"
}, {
  "id" : "Applications/TaskRetriesRiskAssessor5Retries",
  "type" : "xlrelease.TaskRetriesRiskAssessor5Retries",
  "weight" : 1,
  "group" : "Retries for a failed task",
  "order" : "8-rt-04",
  "minRetries" : 5,
  "maxRetries" : 5,
  "score" : 90,
  "title" : "5 retries"
}, {
  "id" : "Applications/TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
  "type" : "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
  "weight" : 1,
  "group" : "Task flag red",
  "icon" : "xl-icon flag-risk-icon",
  "score" : 75,
  "order" : "5-ar-03",
  "minFlags" : 4,
  "maxFlags" : 6,
  "title" : "4 - 6 flags"
}, {
  "id" : "Applications/OneTaskOverDueRiskAssessor",
  "type" : "xlrelease.OneTaskOverDueRiskAssessor",
  "title" : "1 task",
  "weight" : 1,
  "score" : 25,
  "order" : "7-od-00",
  "group" : "Current task(s) past due date"
}, {
  "id" : "Applications/TaskRetriesRiskAssessorMoreThan5Retries",
  "type" : "xlrelease.TaskRetriesRiskAssessorMoreThan5Retries",
  "weight" : 1,
  "group" : "Retries for a failed task",
  "order" : "8-rt-05",
  "minRetries" : 6,
  "maxRetries" : 9999999,
  "score" : 100,
  "title" : "> 5 retries"
}, {
  "id" : "Applications/ReleaseFlaggedAttentionNeededRiskAssessor",
  "type" : "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor",
  "title" : "Release flag amber",
  "weight" : 1,
  "score" : 30,
  "order" : "1-fa-00",
  "group" : "Release flag amber"
}, {
  "id" : "Applications/TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
  "type" : "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
  "weight" : 1,
  "group" : "Task flag red",
  "icon" : "xl-icon flag-risk-icon",
  "score" : 70,
  "order" : "5-ar-02",
  "minFlags" : 2,
  "maxFlags" : 3,
  "title" : "2 - 3 flags"
}, {
  "id" : "Applications/TaskRetriesRiskAssessor4Retries",
  "type" : "xlrelease.TaskRetriesRiskAssessor4Retries",
  "weight" : 1,
  "group" : "Retries for a failed task",
  "order" : "8-rt-03",
  "minRetries" : 4,
  "maxRetries" : 4,
  "score" : 80,
  "title" : "4 retries"
}, {
  "id" : "Applications/TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
  "type" : "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
  "weight" : 1,
  "group" : "Task flag red",
  "icon" : "xl-icon flag-risk-icon",
  "score" : 80,
  "order" : "6-ar-04",
  "minFlags" : 7,
  "maxFlags" : 999999999,
  "title" : "> 6 flags"
}, {
  "id" : "Applications/TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
  "type" : "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
  "weight" : 1,
  "group" : "Task flag amber",
  "icon" : "xl-icon flag-attention-icon",
  "score" : 30,
  "order" : "6-na-03",
  "minFlags" : 4,
  "maxFlags" : 6,
  "title" : "4 - 6 flags"
}, {
  "id" : "Applications/TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
  "type" : "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
  "weight" : 1,
  "group" : "Task flag amber",
  "icon" : "xl-icon flag-attention-icon",
  "score" : 40,
  "order" : "6-na-04",
  "minFlags" : 7,
  "maxFlags" : 999999999,
  "title" : "> 6 flags"
}, {
  "id" : "Applications/ReleaseStatusFailingRiskAssessor",
  "type" : "xlrelease.ReleaseStatusFailingRiskAssessor",
  "title" : "Release state failing",
  "weight" : 1,
  "score" : 70,
  "order" : "3-sf-00",
  "group" : "Release state failing"
}, {
  "id" : "Applications/ReleaseFlaggedAtRiskAssessor",
  "type" : "xlrelease.ReleaseFlaggedAtRiskAssessor",
  "title" : "Release flag red",
  "weight" : 1,
  "score" : 80,
  "order" : "0-fr-00",
  "group" : "Release flag red"
}, {
  "id" : "Applications/TaskRetriesRiskAssessor2Retries",
  "type" : "xlrelease.TaskRetriesRiskAssessor2Retries",
  "weight" : 1,
  "group" : "Retries for a failed task",
  "order" : "8-rt-01",
  "minRetries" : 2,
  "maxRetries" : 2,
  "score" : 60,
  "title" : "2 retries"
}, {
  "id" : "Applications/TaskRetriesRiskAssessor",
  "type" : "xlrelease.TaskRetriesRiskAssessor",
  "title" : "1 retry",
  "weight" : 1,
  "score" : 50,
  "order" : "8-rt-00",
  "group" : "Retries for a failed task",
  "minRetries" : 1,
  "maxRetries" : 1
}, {
  "id" : "Applications/TaskWithOneFlagNeedsAttentionRiskAssessor",
  "type" : "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor",
  "weight" : 1,
  "group" : "Task flag amber",
  "icon" : "xl-icon flag-attention-icon",
  "score" : 10,
  "order" : "6-na-01",
  "minFlags" : 1,
  "maxFlags" : 1,
  "title" : "1 flag"
}, {
  "id" : "Applications/TaskWithOneFlagAtRiskRiskAssessor",
  "type" : "xlrelease.TaskWithOneFlagAtRiskRiskAssessor",
  "weight" : 1,
  "group" : "Task flag red",
  "icon" : "xl-icon flag-risk-icon",
  "score" : 65,
  "order" : "5-ar-01",
  "minFlags" : 1,
  "maxFlags" : 1,
  "title" : "1 flag"
}, {
  "id" : "Applications/TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor",
  "type" : "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor",
  "weight" : 1,
  "group" : "Task flag amber",
  "icon" : "xl-icon flag-attention-icon",
  "score" : 20,
  "order" : "6-na-02",
  "minFlags" : 2,
  "maxFlags" : 3,
  "title" : "2 - 3 flags"
} ]

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

[].title

String

The title of the risk assessor.

[].description

String

The description of the item.

[].weight

Number

The weight of the assessor in the total calculation.

[].score

Number

Score given when assessor decides it needs scoring.

[].order

String

A value used for ordering the assessors within a risk profile.

[].group

String

Define a group to which this risk assessor belongs. Used for UI. Default is: Risk Assessors

[].icon

String

Define an icon for the risk assessor

[].minRetries

Number

Minimum amount of retries to have to score

[].maxRetries

Number

Maximum amount of retries to have to score

[].minFlags

Number

Minimum amount of flags to have to score

[].maxFlags

Number

Maximum amount of retries to have to score

[].icon

String

The css icon class of the flag

Environment management

Environments

Create a new environment

To create a new environment, send this request:

HTTP Request
POST /api/v1/environments

{
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage7bf219346185439081486cef963a5169",
  "labelIds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/environments' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage7bf219346185439081486cef963a5169",
  "labelIds" : null
}'
HTTPie
$ echo '{
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage7bf219346185439081486cef963a5169",
  "labelIds" : null
}' | http POST 'http://localhost:5516/api/v1/environments' \
    'Accept:application/json' \
    'Content-Type:application/json'

The response contains the created environment:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 326
Content-Type: application/json

{
  "id" : "Configuration/environmentManagement/Environmenta3a1df49e3864b3ea760e2eee5bb6f0b",
  "title" : "New environment",
  "description" : "Environment description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage7bf219346185439081486cef963a5169",
    "title" : "DEV"
  },
  "labels" : [ ]
}

Find an environment by ID

To find an environment by its ID, send this request:

HTTP Request
GET /api/v1/environments/Configuration/environmentManagement/Environmenteeb04da2693946ca91a55ace986e20d4
Curl
$ curl 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmenteeb04da2693946ca91a55ace986e20d4' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmenteeb04da2693946ca91a55ace986e20d4' \
    'Accept:application/json'

Using the following path parameters:

Table 98. /api/v1/environments/{environmentId}
Parameter Description

environmentId

Environment ID

The response contains the found environment:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 474

{
  "id" : "Configuration/environmentManagement/Environmenteeb04da2693946ca91a55ace986e20d4",
  "title" : "Environment1",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage669324fa985243b092d69f9105927810",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel789ddd8a08d04024be5f52ec8d591871",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Update an environment

To update an existing environment, send this request:

HTTP Request
PUT /api/v1/environments/Configuration/environmentManagement/Environmente846925fcf4f45a6ad9ee2b8fa59e800

{
  "title" : "New environment title",
  "description" : "New description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStagefbcc19338eea416480558f1e624c5658",
  "labelIds" : [ "Configuration/environmentManagement/EnvironmentLabelbdd628958df746f0832a6209afca7ebe" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmente846925fcf4f45a6ad9ee2b8fa59e800' -i -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "New environment title",
  "description" : "New description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStagefbcc19338eea416480558f1e624c5658",
  "labelIds" : [ "Configuration/environmentManagement/EnvironmentLabelbdd628958df746f0832a6209afca7ebe" ]
}'
HTTPie
$ echo '{
  "title" : "New environment title",
  "description" : "New description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStagefbcc19338eea416480558f1e624c5658",
  "labelIds" : [ "Configuration/environmentManagement/EnvironmentLabelbdd628958df746f0832a6209afca7ebe" ]
}' | http PUT 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmente846925fcf4f45a6ad9ee2b8fa59e800' \
    'Accept:application/json' \
    'Content-Type:application/json'

Using the following path parameters:

Table 99. /api/v1/environments/{environmentId}
Parameter Description

environmentId

Environment ID

The response contains the updated environment:

HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 474

{
  "id" : "Configuration/environmentManagement/Environmente846925fcf4f45a6ad9ee2b8fa59e800",
  "title" : "New environment title",
  "description" : "New description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStagefbcc19338eea416480558f1e624c5658",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabelbdd628958df746f0832a6209afca7ebe",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Delete an environment

To delete an existing environment, send this request:

HTTP Request
DELETE /api/v1/environments/Configuration/environmentManagement/Environmentc2d00ee09b8148d2a8aa573787fb7567
Curl
$ curl 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmentc2d00ee09b8148d2a8aa573787fb7567' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environmentc2d00ee09b8148d2a8aa573787fb7567' \
    'Accept:application/json'

Using the following path parameters:

Table 100. /api/v1/environments/{environmentId}
Parameter Description

environmentId

Environment ID

The response is empty with the status code 204 if the operation was successful.

Search environments

To search environments, send this request:

HTTP Request
POST /api/v1/environments/search

{
  "title" : "Env",
  "stage" : "DEV",
  "labels" : [ "AWS" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/search' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "title" : "Env",
  "stage" : "DEV",
  "labels" : [ "AWS" ]
}'
HTTPie
$ echo '{
  "title" : "Env",
  "stage" : "DEV",
  "labels" : [ "AWS" ]
}' | http POST 'http://localhost:5516/api/v1/environments/search' \
    'Accept:application/json' \
    'Content-Type:application/json'

The response contains a list of the found environments:

HTTP/1.1 200 OK
Content-Language: en
Content-Length: 478
Content-Type: application/json

[ {
  "id" : "Configuration/environmentManagement/Environment38cb13fd02974735b147c428be027e1c",
  "title" : "Environment1",
  "description" : "Environment1 description",
  "stag