These are the public REST services exposed by the Digital.ai Release server.

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

For example:

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

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

Identifiers

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

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

To get the identifiers of phases and tasks, first do a REST call to get the contents of a release, and then inspect the results to find the IDs.
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. There are several ways you can authenticate with the Digital.ai Release API.

HTTP Basic Authentication

Users can send username and password via the standard HTTP Basic fields.

$ curl -u username:password 'http://localhost:5516/api/v1/releases' -i -X GET

Users who authenticate in web application through an OIDC provider, for instance Okta or Keycloak, don’t have credentials and can’t use HTTP Basic Authentication. They must generate and use OAuth2 tokens.

Using personal access tokens

Personal access tokens are currently only supported for internal users. Users can send their personal access token via the login field of HTTP basic authentication, without any username.

$ curl -u :password 'http://localhost:5516/api/v1/releases' -i -X GET

Users can also send it via x-release-personal-token header.

$ curl --header 'x-release-personal-token: <your_token>' 'http://localhost:5516/api/v1/releases' -i -X GET

Users who authenticate in web application through an external provider, for instance LDAP, Okta or Keycloak, can’t use personal access tokens.

OAuth2 tokens

You can use an OAuth2 token to authenticate with the API by passing it in either the Authorization header.

$ curl 'http://localhost:5516/api/v1/releases' -i -X GET \
    -H 'Authorization: Bearer OAUTH2-TOKEN'

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:

You do not have template#edit on APPLICATIONS permission on Applications/Release126975871.
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 Digital.ai 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
Parameter Description

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: 1277

{
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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.

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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
Parameter Description

roleIds

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

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-Type: application/json
Content-Length: 1213

[ {
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

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" ],
  "taskTags" : null,
  "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",
  "riskStatusWithThresholds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/search?page=0&resultsPerPage=100&pageIsOffset=false' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Find me",
  "tags" : [ "foo", "bar" ],
  "taskTags" : null,
  "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",
  "riskStatusWithThresholds" : null
}'
HTTPie
$ echo '{
  "title" : "Find me",
  "tags" : [ "foo", "bar" ],
  "taskTags" : null,
  "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",
  "riskStatusWithThresholds" : null
}' | http POST 'http://localhost:5516/api/v1/releases/search?page=0&resultsPerPage=100&pageIsOffset=false' \
    'Content-Type:application/json' \
    'Accept: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-Type: application/json
Content-Length: 1445

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Find me",
  "scheduledStartDate" : "2022-07-14T17:05:24.116+02:00",
  "dueDate" : "2022-07-14T17:05:24.116+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:24.116+02:00",
  "queryableEndDate" : "2022-07-14T17:05:24.116+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ "foo", "bar" ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

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,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/fullSearch?page=0&resultsPerPage=25&archivePage=0&archiveResultsPerPage=25' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}' | http POST 'http://localhost:5516/api/v1/releases/fullSearch?page=0&resultsPerPage=25&archivePage=0&archiveResultsPerPage=25' \
    'Content-Type:application/json' \
    'Accept: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: 6753

{
  "live" : {
    "page" : 0,
    "size" : 3,
    "releases" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Planned Release",
      "scheduledStartDate" : "2022-07-14T17:05:25.819+02:00",
      "dueDate" : "2022-07-15T01:05:25.819+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2022-07-14T17:05:25.819+02:00",
      "queryableEndDate" : "2022-07-15T01:05:25.819+02:00",
      "realFlagStatus" : "OK",
      "status" : "PLANNED",
      "tags" : [ "foo", "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "archiveRelease" : true,
      "allowPasswordsInAllFields" : false,
      "disableNotifications" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "variableMapping" : { },
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Running Release",
      "dueDate" : "2022-07-15T01:00:25.819+02:00",
      "startDate" : "2022-07-14T17:00:25.819+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2022-07-14T17:00:25.819+02:00",
      "queryableEndDate" : "2022-07-15T01:00:25.819+02:00",
      "realFlagStatus" : "OK",
      "status" : "IN_PROGRESS",
      "tags" : [ "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "archiveRelease" : true,
      "allowPasswordsInAllFields" : false,
      "disableNotifications" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "variableMapping" : { },
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Release9303b354aba041eea4e2486ed81f80c2",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Failed Release",
      "dueDate" : "2022-07-15T00:55:25.819+02:00",
      "startDate" : "2022-07-14T16:55:25.819+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2022-07-14T16:55:25.819+02:00",
      "queryableEndDate" : "2022-07-15T00:55:25.819+02:00",
      "realFlagStatus" : "OK",
      "status" : "FAILED",
      "tags" : [ "foo" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "archiveRelease" : true,
      "allowPasswordsInAllFields" : false,
      "disableNotifications" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "variableMapping" : { },
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    } ]
  },
  "archived" : {
    "page" : 0,
    "size" : 2,
    "releases" : [ {
      "id" : "Applications/Release4c0a37c875694c97b30fa971fc1ee03c",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Completed Release",
      "startDate" : "2022-07-14T09:05:25.819+02:00",
      "endDate" : "2022-07-14T17:05:25.819+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2022-07-14T09:05:25.819+02:00",
      "queryableEndDate" : "2022-07-14T17:05:25.819+02:00",
      "realFlagStatus" : "OK",
      "status" : "COMPLETED",
      "tags" : [ "bar" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "archiveRelease" : true,
      "allowPasswordsInAllFields" : false,
      "disableNotifications" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "variableMapping" : { },
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Release18a1237a6df6409b941ab62a245141cc",
      "type" : "xlrelease.Release",
      "$scmTraceabilityDataId" : "0",
      "title" : "Aborted Release",
      "startDate" : "2022-07-14T08:05:25.819+02:00",
      "endDate" : "2022-07-14T16:05:25.819+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2022-07-14T08:05:25.819+02:00",
      "queryableEndDate" : "2022-07-14T16:05:25.819+02:00",
      "realFlagStatus" : "OK",
      "status" : "ABORTED",
      "tags" : [ "foo" ],
      "variables" : [ ],
      "calendarPublished" : false,
      "tutorial" : false,
      "abortOnFailure" : false,
      "archiveRelease" : true,
      "allowPasswordsInAllFields" : false,
      "disableNotifications" : false,
      "allowConcurrentReleasesFromTrigger" : true,
      "createdFromTrigger" : false,
      "extensions" : [ ],
      "autoStart" : false,
      "automatedResumeCount" : 0,
      "variableMapping" : { },
      "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    } ]
  }
}

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,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/count' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}' | http POST 'http://localhost:5516/api/v1/releases/count' \
    'Content-Type:application/json' \
    'Accept: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-Type: application/json
Content-Length: 402

{
  "live" : {
    "total" : 3,
    "byStatus" : {
      "FAILED" : 1,
      "IN_PROGRESS" : 1,
      "PLANNED" : 1
    }
  },
  "archived" : {
    "total" : 2,
    "byStatus" : {
      "ABORTED" : 1,
      "COMPLETED" : 1
    }
  },
  "all" : {
    "total" : 5,
    "byStatus" : {
      "COMPLETED" : 1,
      "IN_PROGRESS" : 1,
      "FAILED" : 1,
      "PLANNED" : 1,
      "ABORTED" : 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-Language: en
Content-Type: application/json
Content-Length: 427

{
  "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 '#3D6C9E'

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:04:46.538+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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-Type: application/json
Content-Length: 971

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "find me",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:04:18.854+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false
} ]

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

[ {
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}, {
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

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: 2480

[ {
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}, {
  "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,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

Release life cycle

For a detailed description about the release and task life cycle, refer to Digital.ai 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,
  "startedFromTaskId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "releaseOwner" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "variables" : { },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "startedFromTaskId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "releaseOwner" : null
}'
HTTPie
$ echo '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "variables" : { },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "startedFromTaskId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "releaseOwner" : null
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' \
    'Content-Type:application/json' \
    'Accept: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.

startedFromTaskId

String

If not null, specifies the id the task that created the release, useful when creating releases from scripts
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: 3379

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Release3d2f8c6aa629433780f52d1dc870536d",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2022-07-14T17:05:58.851+02:00",
  "dueDate" : "2022-07-15T01:05:58.851+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "rootReleaseId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:58.851+02:00",
  "queryableEndDate" : "2022-07-15T01:05:58.851+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarLinkToken" : "-4125362121176038190",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "startedFromTaskId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    }
  }
}

All the variables in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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 Digital.ai 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" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "startedFromTaskId" : null,
  "releaseOwner" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder16471301a63401435604e56d1303c451",
  "variables" : {
    "listVar" : [ "a", "b" ],
    "stringVar" : "providedValue",
    "passwordVar" : "providedValue"
  },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "startedFromTaskId" : null,
  "releaseOwner" : null
}'
HTTPie
$ echo '{
  "releaseTitle" : "release from api",
  "folderId" : "Applications/Folder16471301a63401435604e56d1303c451",
  "variables" : {
    "listVar" : [ "a", "b" ],
    "stringVar" : "providedValue",
    "passwordVar" : "providedValue"
  },
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false,
  "startedFromTaskId" : null,
  "releaseOwner" : null
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/create' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 4208

{
  "id" : "Applications/Folder16471301a63401435604e56d1303c451/Release5775a9a04ac9478d9837cbedaf0a928b",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2022-07-14T17:06:15.796+02:00",
  "dueDate" : "2022-07-15T01:06:15.796+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:15.796+02:00",
  "queryableEndDate" : "2022-07-15T01:06:15.796+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Release5775a9a04ac9478d9837cbedaf0a928b/Variable645470b1af3b486ca347828dad48c67d",
    "type" : "xlrelease.StringVariable",
    "key" : "stringVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "providedValue",
    "multiline" : false
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Release5775a9a04ac9478d9837cbedaf0a928b/Variable942866cc68f347f4878a93f9d080f746",
    "type" : "xlrelease.PasswordStringVariable",
    "key" : "passwordVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "********",
    "multiline" : false
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Release5775a9a04ac9478d9837cbedaf0a928b/Variable9c534ad640a94c8a8db142721438a598",
    "type" : "xlrelease.ListStringVariable",
    "key" : "listVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : [ "a", "b" ]
  } ],
  "calendarLinkToken" : "1966749782619539841",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder16471301a63401435604e56d1303c451/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    }
  }
}

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-Type: application/json
Content-Length: 1070

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "startDate" : "2022-07-14T17:05:19.253+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

[].watchers

Array

The watchers assigned to this task.

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

[].failuresCount

Number

The number of times this task has failed.

[].variableMapping

Object

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

[].externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/assign/admin' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 1034

{
  "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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 1405

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment99d9f14a3d2245df91ca7d0347d38ced",
    "type" : "xlrelease.Comment",
    "text" : "Important step in our pipeline",
    "author" : "admin",
    "date" : "2022-07-14T17:05:03.758+02:00",
    "creationDate" : "2022-07-14T17:05:03.757+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false
}

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 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "comment" : "Task completed!"
}'
HTTPie
$ echo '{
  "comment" : "Task completed!"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/complete' \
    'Content-Type:application/json' \
    'Accept: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-Type: application/json
Content-Length: 1531

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:04:35.191+02:00",
  "endDate" : "2022-07-14T17:04:35.809+02:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Commentea0da1162ba14ce395d1644b732db2ac",
    "type" : "xlrelease.Comment",
    "text" : "Task completed!",
    "author" : "admin",
    "date" : "2022-07-14T17:04:35.843+02:00",
    "creationDate" : "2022-07-14T17:04:35.843+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "COMPLETED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept: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: 1445

{
  "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/Commentb876bdc9c4754a0584605f1c7d208149",
    "type" : "xlrelease.Comment",
    "text" : "Reopen a task that has been completed in advance.",
    "author" : "admin",
    "date" : "2022-07-14T17:04:52.452+02:00",
    "creationDate" : "2022-07-14T17:04:52.452+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "comment" : "Task failed :-("
}'
HTTPie
$ echo '{
  "comment" : "Task failed :-("
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/fail' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 1459

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:04:50.375+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment9bd651b2610e49bd8d9710ee9c6c4e6d",
    "type" : "xlrelease.Comment",
    "text" : "Task failed :-(",
    "author" : "admin",
    "date" : "2022-07-14T17:04:51.144+02:00",
    "creationDate" : "2022-07-14T17:04:51.144+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "FAILED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 1,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 1467

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:04:25.884+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment2f32c4a6a2a14cdf8538b2d1869bafb5",
    "type" : "xlrelease.Comment",
    "text" : "Retry failed task.",
    "author" : "admin",
    "date" : "2022-07-14T17:04:25.942+02:00",
    "creationDate" : "2022-07-14T17:04:25.942+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "comment" : "Task skipped"
}'
HTTPie
$ echo '{
  "comment" : "Task skipped"
}' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/skip' \
    'Content-Type:application/json' \
    'Accept: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-Language: en
Content-Type: application/json
Content-Length: 1526

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2022-07-14T17:05:04.515+02:00",
  "endDate" : "2022-07-14T17:05:05.244+02:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Commentbc93613e8a8f4165a6844f5fa1fd95a1",
    "type" : "xlrelease.Comment",
    "text" : "Task skipped",
    "author" : "admin",
    "date" : "2022-07-14T17:05:05.256+02:00",
    "creationDate" : "2022-07-14T17:05:05.256+02:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "SKIPPED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : 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.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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept: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: 1040

{
  "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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "abortComment" : "Abort comment"
}'
HTTPie
$ echo '{
  "abortComment" : "Abort comment"
}' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/abort' \
    'Content-Type:application/json' \
    'Accept: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: 1321

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Running release, don't abort me",
  "endDate" : "2022-07-14T17:04:54.113+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableEndDate" : "2022-07-14T17:04:54.113+02:00",
  "realFlagStatus" : "OK",
  "status" : "ABORTED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "abortComment" : "Abort comment",
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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: 4560

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2022-07-14T17:04:50.386+02: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" : "2022-07-14T17:04:49.362+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "watchers" : [ ],
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "postponedUntilEnvironmentsAreReserved" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "externalVariableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
    "startDate" : "2022-07-14T17:04:50.389+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2022-07-14T17:04:50.396+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "watchers" : [ ],
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "postponedUntilEnvironmentsAreReserved" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "externalVariableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "IN_PROGRESS"
  } ],
  "queryableStartDate" : "2022-07-14T17:04:50.386+02:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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
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-Type: application/json
Content-Length: 4828

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2022-07-14T17:05:03.903+02: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" : "2022-07-14T17:05:03.767+02:00",
    "endDate" : "2022-07-14T17:05:03.767+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2022-07-14T17:05:02.915+02:00",
      "endDate" : "2022-07-14T17:05:03.768+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "watchers" : [ ],
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "postponedUntilEnvironmentsAreReserved" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "externalVariableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase380bf5b6165e4150adc8e982d287e9c4",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (1)",
    "startDate" : "2022-07-14T17:05:03.903+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase380bf5b6165e4150adc8e982d287e9c4/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2022-07-14T17:05:03.903+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase380bf5b6165e4150adc8e982d287e9c4",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "watchers" : [ ],
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "postponedUntilEnvironmentsAreReserved" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "taskFailureHandlerEnabled" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "externalVariableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false,
      "locked" : false,
      "checkAttributes" : false
    } ],
    "release" : "Applications/Release162151faba694d03aa3065665cf26f21",
    "status" : "IN_PROGRESS",
    "originId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e"
  } ],
  "queryableStartDate" : "2022-07-14T17:05:03.903+02:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 1,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

Building templates and releases

For a details description on templates and releases, refer to Core concepts of Digital.ai 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" : "2022-07-14T17:06:05.246+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:05.246+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/?folderId=Applications/Folder01345a690c16b345168751d62934e912' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:05.246+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:05.246+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:05.246+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:05.246+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http POST 'http://localhost:5516/api/v1/templates/?folderId=Applications/Folder01345a690c16b345168751d62934e912' \
    'Content-Type:application/json' \
    'Accept: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.

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Releasebd1e2999daaf4b6db257931f9347388b",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:05.246+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Team85bfb762128e47d0b438ee79e8a40723",
    "type" : "xlrelease.Team",
    "teamName" : "Template Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "template#create_release_other_folder", "template#edit", "trigger#view_trigger", "template#lock_task", "template#view", "folder#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Team7e722befdb894e20ad81425bcca36263",
    "type" : "xlrelease.Team",
    "teamName" : "Release Admin",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#edit_task_attachments", "release#task_transition", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "release#edit_failure_handler", "release#abort" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teamd402523f47da4ff2b89bcf68048ea8b8",
    "type" : "xlrelease.Team",
    "teamName" : "Folder Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "folder#view_versions", "folder#apply_changes", "group#view", "folder#edit_versions", "folder#edit_notifications", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "folder#edit_security", "dashboard#edit", "folder#edit", "dashboard#view", "folder#generate_configuration" ]
  } ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Releasebd1e2999daaf4b6db257931f9347388b/Phase9631446c7ea34ddda6db19ee1e8e090f",
    "type" : "xlrelease.Phase",
    "title" : "New Phase",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ ],
    "release" : "Applications/Folder01345a690c16b345168751d62934e912/Releasebd1e2999daaf4b6db257931f9347388b",
    "status" : "PLANNED"
  } ],
  "queryableStartDate" : "2022-07-14T17:06:05.246+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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 Digital.ai 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

Make a template copy

It’s possible to duplicate a template in the same folder where it lives:

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

{
  "title" : "My template copy title",
  "description" : "My template copy description"
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/copy' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "My template copy title",
  "description" : "My template copy description"
}'
HTTPie
$ echo '{
  "title" : "My template copy title",
  "description" : "My template copy description"
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21/copy' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following request:

Table 21. /api/v1/templates/{templateId}/copy
Parameter Description

templateId

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

title

String

The new title of the template. Mandatory

description

String

The new description. Optional

The response contains the template JSON:

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

{
  "id" : "Applications/Release2b144d8d20934b569e2a7a865253bef9",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "My template copy title",
  "description" : "My template copy description",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Table 22. /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 '#3D6C9E'

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase916e168bd0ed42ceb59d7664e92f5c45",
  "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 '#3D6C9E'

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
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 23. /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: 1554

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase3eb6316679794a1aa362dae696041925",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase3eb6316679794a1aa362dae696041925/Task97c27091a9b342599e1b631dc6d44726",
    "type" : "xlrelease.GateTask",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "comments" : [ ],
    "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase3eb6316679794a1aa362dae696041925",
    "facets" : [ ],
    "attachments" : [ ],
    "status" : "PLANNED",
    "watchers" : [ ],
    "waitForScheduledStartDate" : true,
    "delayDuringBlackout" : false,
    "postponedDueToBlackout" : false,
    "postponedUntilEnvironmentsAreReserved" : false,
    "hasBeenFlagged" : false,
    "hasBeenDelayed" : false,
    "taskFailureHandlerEnabled" : false,
    "failuresCount" : 0,
    "variableMapping" : { },
    "externalVariableMapping" : { },
    "tags" : [ ],
    "dueSoonNotified" : false,
    "locked" : false,
    "checkAttributes" : false,
    "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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 24. /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 '#3D6C9E'

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-Type: application/json
Content-Length: 346

{
  "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 '#3D6C9E'

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

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

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks?position=0' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: 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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false
}'
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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false
}' | http POST 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/tasks?position=0' \
    'Content-Type:application/json' \
    'Accept: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 26. /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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

The response contains the created task:

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

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

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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
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 27. /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-Type: application/json
Content-Length: 1070

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task9f0e7439f8d342c99c159acc1eab7181",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726 (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

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

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

Task types

In Digital.ai 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 Digital.ai 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
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/changeType?targetType=xlrelease.GateTask' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/changeType?targetType=xlrelease.GateTask' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

targetType

Target task type; for example, targetType=xlrelease.Task or targetType=jenkins.Build
Table 29. /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-Language: en
Content-Type: application/json
Content-Length: 1063

{
  "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",
  "watchers" : [ ],
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "postponedUntilEnvironmentsAreReserved" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "taskFailureHandlerEnabled" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "externalVariableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "locked" : false,
  "checkAttributes" : false,
  "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.

watchers

Array

The watchers assigned to this task.

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.

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

externalVariableMapping

Object

Similar to variableMapping, but only for password variables with external values and it is managed internally.

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

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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

Using the following parameters:

Table 30. /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/GateCondition21066ece84114d72a3761fdbb20b7e1e",
  "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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'
Path Type Description

title

String

Title of condition

checked

Boolean

Condition checked

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

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 32. /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 'Content-Type: application/json' \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/dependencies/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

{
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Dependencyc6c32410653b43449f45ace9c35c197b",
  "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 34. /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 35. /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 36. /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: 396

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

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/Attachmente312ac710aee4a3181312757fc5639a4
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachmente312ac710aee4a3181312757fc5639a4' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments/Applications/Release162151faba694d03aa3065665cf26f21/Attachmente312ac710aee4a3181312757fc5639a4' \
    'Accept:application/json'

Using the following parameters:

Table 37. /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" : "2022-07-14T17:06:03.100+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:03.100+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:03.100+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:03.100+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:03.100+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:03.100+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http PUT 'http://localhost:5516/api/v1/templates/Applications/Release162151faba694d03aa3065665cf26f21' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

The response the updated template:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2022-07-14T17:06:03.100+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:06:03.100+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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.

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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" : "2022-07-14T17:05:08.506+02:00",
  "dueDate" : "2022-07-14T17:05:08.506+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:08.506+02:00",
  "queryableEndDate" : "2022-07-14T17:05:08.506+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2022-07-14T17:05:08.506+02:00",
  "dueDate" : "2022-07-14T17:05:08.506+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:08.506+02:00",
  "queryableEndDate" : "2022-07-14T17:05:08.506+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2022-07-14T17:05:08.506+02:00",
  "dueDate" : "2022-07-14T17:05:08.506+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:08.506+02:00",
  "queryableEndDate" : "2022-07-14T17:05:08.506+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

The response contains the updated release:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$scmTraceabilityDataId" : "0",
  "title" : "new title",
  "scheduledStartDate" : "2022-07-14T17:05:08.506+02:00",
  "dueDate" : "2022-07-14T17:05:08.506+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2022-07-14T17:05:08.506+02:00",
  "queryableEndDate" : "2022-07-14T17:05:08.506+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

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.

archiveRelease

Boolean

Archive release

allowPasswordsInAllFields

Boolean

Allows the usage of passwords in non-password fields. Passwords values are masked in the UI and logging output but are decrypted before the task execution.

disableNotifications

Boolean

Disable all notifications for this release.

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

variableMapping

Object

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

riskProfile

Varies

Risk profile used in risk calculations

riskScore

String

Risk score

totalRiskScore

String

Total risk score

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 40. /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 41. /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 42. /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 43. /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.

Export template

To export template in .xlr format, send this request:

Do not use -i with curl
HTTP Request
GET /api/v1/templates/zip/Applications/Releasec9cb23392fb34342af897293aeb1759b
Curl
$ curl 'http://localhost:5516/api/v1/templates/zip/Applications/Releasec9cb23392fb34342af897293aeb1759b' -i -X GET \
    -H 'Accept: */*'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/zip/Applications/Releasec9cb23392fb34342af897293aeb1759b' \
    'Accept:*/*'

The response contains the zip file content:

HTTP/1.1 200 OK
Content-Language: en
Content-Disposition: attachment; filename="Test template 1.xlr"
Content-Type: application/zip
We didn’t display response of the zip file in this example.

Folders

In Digital.ai 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: 1643

[ {
  "id" : "Applications/Folderfa6c19e6836b4af3be96dde2b3a4120f",
  "type" : "xlrelease.Folder",
  "$token" : "144bd7c7-644c-4976-aac4-44d98ca9aaa6",
  "title" : "Microservices",
  "children" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "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/Folder8367cb5d182d43e09649ebfb7f70e6c8/list
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder8367cb5d182d43e09649ebfb7f70e6c8/list' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder8367cb5d182d43e09649ebfb7f70e6c8/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 44. /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/Folder62eac3a68ca04b918eec9c1107515e05/Folder1a19e6eb8f1f4c0a9c1586770355cb87
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder62eac3a68ca04b918eec9c1107515e05/Folder1a19e6eb8f1f4c0a9c1586770355cb87' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder62eac3a68ca04b918eec9c1107515e05/Folder1a19e6eb8f1f4c0a9c1586770355cb87' \
    'Accept:application/json'

Using the following parameters:

Table 45. /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/Folderb9554ec52b464ebd9cee70eaa8b99558/Folder52c5ab00920844009092263f426d1a02/templates
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderb9554ec52b464ebd9cee70eaa8b99558/Folder52c5ab00920844009092263f426d1a02/templates' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folderb9554ec52b464ebd9cee70eaa8b99558/Folder52c5ab00920844009092263f426d1a02/templates' \
    'Accept:application/json'

Using the following parameters:

Table 46. /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/Folder3803dded349246deaa3bfccbae545310/Folder39c2e85ca73c447a88dd91db338fffaf/releases

{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder3803dded349246deaa3bfccbae545310/Folder39c2e85ca73c447a88dd91db338fffaf/releases' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}'
HTTPie
$ echo '{
  "title" : null,
  "tags" : null,
  "taskTags" : 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,
  "riskStatusWithThresholds" : null
}' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder3803dded349246deaa3bfccbae545310/Folder39c2e85ca73c447a88dd91db338fffaf/releases' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Table 47. /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/Folder4270df87cef14ff79bc6c32bc257f27e/templates/Applications/Folder5178bc518352427aa39d2619246be2c2/Release1
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder4270df87cef14ff79bc6c32bc257f27e/templates/Applications/Folder5178bc518352427aa39d2619246be2c2/Release1' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/folders/Applications/Folder4270df87cef14ff79bc6c32bc257f27e/templates/Applications/Folder5178bc518352427aa39d2619246be2c2/Release1' \
    'Accept:application/json'

Using the following parameters:

Table 48. /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/Folder5620ce567751481a9c880ee131d69df5

{
  "id" : null,
  "type" : "xlrelease.Folder",
  "title" : "QA",
  "children" : [ ]
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder5620ce567751481a9c880ee131d69df5' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: 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/Folder5620ce567751481a9c880ee131d69df5' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Table 49. /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/Folder91bd0576c7294ffb87c48a0bdd6bb0a4
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder91bd0576c7294ffb87c48a0bdd6bb0a4' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/folders/Applications/Folder91bd0576c7294ffb87c48a0bdd6bb0a4'

Using the following parameters:

Table 50. /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/Folder080c31feb57f4c23a05cce099503dbef/move?newParentId=Applications/Foldere3d04062d7c1415a839370cadef8c47e
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder080c31feb57f4c23a05cce099503dbef/move?newParentId=Applications/Foldere3d04062d7c1415a839370cadef8c47e' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/folders/Applications/Folder080c31feb57f4c23a05cce099503dbef/move?newParentId=Applications/Foldere3d04062d7c1415a839370cadef8c47e' \
    'Accept:application/json'

Using the following parameters:

Table 51. /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/Folder31a92af53b444c899de7b0f149fd21b1/rename?newName=Microservices%20II
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder31a92af53b444c899de7b0f149fd21b1/rename?newName=Microservices%20II' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/folders/Applications/Folder31a92af53b444c899de7b0f149fd21b1/rename?newName=Microservices%20II' \
    'Accept:application/json'

Using the following parameters:

Table 52. /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 Digital.ai Release

Types of variables

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

[ {
  "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 55. /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-Language: en
Content-Type: application/json
Content-Length: 53

{
  "${var1ref}" : "value1",
  "${var1}" : "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 56. /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,
  "externalVariableValue" : null,
  "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,
  "externalVariableValue" : null,
  "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,
  "externalVariableValue" : null,
  "valueProvider" : null
}' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' \
    'Content-Type:application/json'

Using the following path parameters:

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

[ "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 62. /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-Type: application/json
Content-Length: 5

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

[ {
  "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-Language: en
Content-Type: application/json
Content-Length: 508

[ {
  "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-Language: en
Content-Type: application/json
Content-Length: 65

{
  "${global.var1ref}" : "value",
  "${global.var1}" : "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 65. /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,
  "externalVariableValue" : null,
  "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,
  "externalVariableValue" : null,
  "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,
  "externalVariableValue" : null,
  "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-Type: application/json
Content-Length: 282

{
  "id" : "Configuration/variables/global/Variable67565dd3097a4b9f8736111a54cd81b4",
  "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 66. /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-Language: en
Content-Type: application/json
Content-Length: 253

{
  "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 67. /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/Folder554d2f0b109144c1a773416ec7b4bf6b/Foldere18f8bb8998e4936b05429bfd9ec3271/variables?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder554d2f0b109144c1a773416ec7b4bf6b/Foldere18f8bb8998e4936b05429bfd9ec3271/variables?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder554d2f0b109144c1a773416ec7b4bf6b/Foldere18f8bb8998e4936b05429bfd9ec3271/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" : "Variable38d03f8b74ed4a3ab5f92702307d03dd",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder554d2f0b109144c1a773416ec7b4bf6b",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false
}, {
  "id" : "Variable333abb5673724bd0b369866e1884997c",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder554d2f0b109144c1a773416ec7b4bf6b/Foldere18f8bb8998e4936b05429bfd9ec3271",
  "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/Folder62aacfdc3d2c41d680e77a7fe3b9b056/Folder3df995b9572f41388c17407b8f7e26a6/variableValues?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder62aacfdc3d2c41d680e77a7fe3b9b056/Folder3df995b9572f41388c17407b8f7e26a6/variableValues?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder62aacfdc3d2c41d680e77a7fe3b9b056/Folder3df995b9572f41388c17407b8f7e26a6/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-Type: application/json
Content-Length: 62

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

Find folder variable by ID

To obtain a specific folder variable, send this request:

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

The response contains the folder variable:

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

{
  "id" : "Variable9d4aeb9a62ba4964b14e33b54695ab5c",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder0f5f6ddeea0d478b8e1c19d64be35bd2",
  "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/Foldera45a22821e5c452a9c82274429e279ba/variables

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

{
  "id" : "Variable5934f0158cf4419ea1a99c2e93f0f034",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Foldera45a22821e5c452a9c82274429e279ba",
  "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/Folder8a4ecc8b9c384794988098da0d296df5/Variable0c99bd8371c2472a9907f286a30f6f7d

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

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

{
  "id" : "Variable0c99bd8371c2472a9907f286a30f6f7d",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder8a4ecc8b9c384794988098da0d296df5",
  "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/Folderf600b8d5d3b84885b60eaf3bd42f2019/Variablea0ace364232a466693e0dc316def8bc2
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderf600b8d5d3b84885b60eaf3bd42f2019/Variablea0ace364232a466693e0dc316def8bc2' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/folders/Applications/Folderf600b8d5d3b84885b60eaf3bd42f2019/Variablea0ace364232a466693e0dc316def8bc2' \
    'Accept:application/json'

Using the following path parameters:

Table 70. /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/Folderac1a9f5e640c4a0f94c511d876aa72e7&folderOnly=true
Curl
$ curl 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server&folderId=Applications/Folderac1a9f5e640c4a0f94c511d876aa72e7&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/Folderac1a9f5e640c4a0f94c511d876aa72e7&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: 413

[ {
  "id" : "Configuration/Custom/Configuration921d68771dbd44e6834787539f9d3ae8",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderac1a9f5e640c4a0f94c511d876aa72e7",
  "title" : "my JIRA server",
  "variableMapping" : { },
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value"
} ]

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/Configuration9495726e5cd8454c80d1eb23114a30d7
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration9495726e5cd8454c80d1eb23114a30d7' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration9495726e5cd8454c80d1eb23114a30d7' \
    'Accept: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 configuration object:

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

{
  "id" : "Configuration/Custom/Configuration9495726e5cd8454c80d1eb23114a30d7",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder68f56f4c5df042e3b4d330aa86a6ffb6",
  "title" : "Jira server configuration",
  "variableMapping" : { },
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "********",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "********"
}

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/Folder560b9b68a4d149c9b91b8c11f6862a7d",
  "title" : "Jira server configuration",
  "variableMapping" : { },
  "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 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "null",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder560b9b68a4d149c9b91b8c11f6862a7d",
  "title" : "Jira server configuration",
  "variableMapping" : { },
  "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/Folder560b9b68a4d149c9b91b8c11f6862a7d",
  "title" : "Jira server configuration",
  "variableMapping" : { },
  "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' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created configuration object:

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

{
  "id" : "Configuration/Custom/Configuration39bb4d47e72e42dc85b79b3b817277da",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder560b9b68a4d149c9b91b8c11f6862a7d",
  "title" : "Jira server configuration",
  "variableMapping" : { },
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "********",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "********"
}

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/Configurationdda5f6e36a134de6838bd8c1eba7b7c5

{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder8e084b210a234bb89520c412d79091a9",
  "title" : "Changed jira title",
  "variableMapping" : { },
  "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/Configurationdda5f6e36a134de6838bd8c1eba7b7c5' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder8e084b210a234bb89520c412d79091a9",
  "title" : "Changed jira title",
  "variableMapping" : { },
  "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/Folder8e084b210a234bb89520c412d79091a9",
  "title" : "Changed jira title",
  "variableMapping" : { },
  "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/Configurationdda5f6e36a134de6838bd8c1eba7b7c5' \
    'Content-Type:application/json' \
    '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 contains the updated configuration object:

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

{
  "id" : "Configuration/Custom/Configurationdda5f6e36a134de6838bd8c1eba7b7c5",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder8e084b210a234bb89520c412d79091a9",
  "title" : "Changed jira title",
  "variableMapping" : { },
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "********",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "********"
}

Delete configuration

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

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

Using the following parameters:

Table 73. /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-Type: application/json
Content-Length: 149

{
  "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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contain updated system message configuration:

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

{
  "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 Digital.ai 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 74. /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 75. /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-Language: en
Content-Type: text/plain;charset=UTF-8
Content-Length: 1132

// Exported from:        http://jenkins-slave20-xlr:0/#/templates/Release162151faba694d03aa3065665cf26f21/code
// Release version:      22.2.2-SNAPSHOT
// Date created:         Thu Jul 14 17:04:35 CEST 2022

xlr {
  release('Sample XLR template') {
    variables {
      stringVariable('manualTaskTitle') {
        value 'Manual task title'
      }
      passwordVariable('jiraPassword') {
        value '{aes:v0}jtPw/VI1ixKNGXqT4wT3KE0t7t6ZTHNTyPmowi/xwPk='
      }
      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: 622

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

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.

[].externalId

String

The external id 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 Digital.ai Release

[].analyticsEnabled

Boolean

The profile settings for opt-out from anonymous product usage analytics and guides

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 76. /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" : "Passw0rd!",
  "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" : "Passw0rd!",
  "loginAllowed" : true,
  "fullName" : "My new User"
}'
HTTPie
$ echo '{
  "password" : "Passw0rd!",
  "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 77. /api/v1/users/{username}
Parameter Description

username

The username from the user to be created.

User preferences

Table 78. 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 79. /api/v1/users/{username}
Parameter Description

username

The username from the user to be updated.

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

{
  "username" : "user1",
  "external" : false,
  "profileId" : null,
  "email" : null,
  "fullName" : null,
  "externalId" : null,
  "loginAllowed" : false,
  "dateFormat" : "M/d/yy",
  "timeFormat" : "h:mm a",
  "firstDayOfWeek" : 0,
  "lastActive" : null,
  "analyticsEnabled" : true
}
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" : "Passw0rd!"
}
Curl
$ curl 'http://localhost:5516/api/v1/users/user1/password' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "currentPassword" : "myPassword",
  "newPassword" : "Passw0rd!"
}'
HTTPie
$ echo '{
  "currentPassword" : "myPassword",
  "newPassword" : "Passw0rd!"
}' | 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 80. /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 81. /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-Type: application/json
Content-Length: 361

[ "admin", "login", "security#edit", "security#view", "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-Language: en
Content-Type: application/json
Content-Length: 354

[ {
  "name" : "Developers",
  "id" : "ec492bda-8d67-4020-9fc7-a917d5a4b20e",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}, {
  "name" : "RoleWithAdminPermission",
  "id" : "0",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "admin",
    "fullname" : "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 82. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

which returns:

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

{
  "name" : "Developers",
  "id" : "7b00f2c0-c4b3-44bb-a8b9-d59f6dc0a184",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}

Response fields and their description:

Path Type Description

name

String

This field contains name of the role.

id

String

This field contains id 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",
  "id" : null,
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}
Curl
$ curl 'http://localhost:5516/api/v1/roles/Testers' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "name" : "Testers",
  "id" : null,
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}'
HTTPie
$ echo '{
  "name" : "Testers",
  "id" : null,
  "permissions" : [ "release#create", "template#create" ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : "devans Smith"
  } ]
}' | http POST 'http://localhost:5516/api/v1/roles/Testers' \
    'Content-Type:application/json' \
    'Accept: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.

id

String

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

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]id

String

This field contains id 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

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

with the following path parameters:

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

id

String

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

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]id

String

This field contains id 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
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 85. /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 86. /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-Type: application/json
Content-Length: 1093

[ "folder#view", "folder#edit", "folder#edit_security", "folder#edit_teams", "folder#edit_notifications", "folder#edit_configuration", "folder#edit_variables", "folder#view_versions", "folder#edit_versions", "folder#apply_changes", "folder#generate_configuration", "template#create_release", "template#create_release_other_folder", "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#advance_task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#restart_phase", "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: 830

[ "template#create_release", "template#create_release_other_folder", "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#advance_task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#restart_phase", "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: 592

[ "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#advance_task_transition", "release#edit_task_tags", "release#edit_task_attachments", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_flag", "release#restart_phase", "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/Folder4184d7b5e46b4211a4a275c33dc59143/teams
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder4184d7b5e46b4211a4a275c33dc59143/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder4184d7b5e46b4211a4a275c33dc59143/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2303

[ {
  "id" : "Applications/Folder4184d7b5e46b4211a4a275c33dc59143/Teamcfd99f09b09e470ebbbe066a1df6c295",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#edit_task_attachments", "release#task_transition", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder4184d7b5e46b4211a4a275c33dc59143/Team43efe6e7a50f443f8485c17b0b3c0480",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "trigger#view_trigger", "template#lock_task", "template#view", "folder#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder4184d7b5e46b4211a4a275c33dc59143/Team6d55db333734464591b89b3c2f838fb6",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "folder#view_versions", "folder#apply_changes", "group#view", "folder#edit_versions", "folder#edit_notifications", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "folder#edit_security", "dashboard#edit", "folder#edit", "dashboard#view", "folder#generate_configuration" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 87. /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/Released3f3c60249df4bb1851d078c31a91ab9/teams
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Released3f3c60249df4bb1851d078c31a91ab9/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/Applications/Released3f3c60249df4bb1851d078c31a91ab9/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2045

[ {
  "id" : "Applications/Released3f3c60249df4bb1851d078c31a91ab9/Teamccd5430497824b6780aa24fe3cc71fe8",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Released3f3c60249df4bb1851d078c31a91ab9/Team63f8bee0b1e542ac8d9cfe361b10ae07",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Released3f3c60249df4bb1851d078c31a91ab9/Team5020bae120224f9697dffc546ef2a6f8",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "template#lock_task", "template#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Released3f3c60249df4bb1851d078c31a91ab9/Teama1b3f574970f498fb260069de313a417",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 88. /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/Release19fe067c5a254ecaa5aaaaf0369f37f5/teams
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2045

[ {
  "id" : "Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/Teamc80fff9535004a05842f3b2074987b0d",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/Team4f6b8cde3be94c87bb0a8520f3613c52",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "template#lock_task", "template#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/Teamb1912189f66e4992a6631346be63bbaf",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release19fe067c5a254ecaa5aaaaf0369f37f5/Team18a4608d5aba475c85cbc5adb7d79c05",
  "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 89. /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/Folder9e36431977eb45edb488cca6b79054a2/teams

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

[ {
  "id" : "Applications/Folder9e36431977eb45edb488cca6b79054a2/Teamfcd0e3c80c404bff8a707ad7eadbd35c",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#edit_task_attachments", "release#task_transition", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder9e36431977eb45edb488cca6b79054a2/Teama683c4876c664ef7aaf0d78de1111afc",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "delivery#edit", "folder#view_versions", "folder#apply_changes", "group#view", "folder#edit_versions", "folder#edit_notifications", "delivery_pattern#view", "group#edit", "delivery#view", "delivery#edit_tracked_item", "folder#view", "folder#edit_security", "dashboard#edit", "folder#edit", "dashboard#view", "folder#generate_configuration", "release#edit" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder9e36431977eb45edb488cca6b79054a2/Teamdd187dbc1d8549e0abffdfc9d0588cc2",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "trigger#view_trigger", "template#lock_task", "template#view", "folder#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 90. /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/Release89df8ae322994391ac94fd0ca151ea70/teams

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

[ {
  "id" : "Applications/Release89df8ae322994391ac94fd0ca151ea70/Teamd1c46dbce3ee44b892241c6750f0e0c8",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "template#lock_task", "template#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release89df8ae322994391ac94fd0ca151ea70/Team403b2588ab574eccbc6e99f93c3ff7fb",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release89df8ae322994391ac94fd0ca151ea70/Team3ce23287533445bfb203308daf7ca1ea",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release89df8ae322994391ac94fd0ca151ea70/Teambad49d3e5f5447b4820d3ee66c38d551",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

Table 91. /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/Release67070a53c6d14d619c994fb7de9813ef/teams

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

[ {
  "id" : "Applications/Release67070a53c6d14d619c994fb7de9813ef/Team81f3bc43d7514421b3c387e594797673",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#create_release_other_folder", "template#edit", "template#lock_task", "template#view", "template#edit_security", "template#create_release", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release67070a53c6d14d619c994fb7de9813ef/Team79fb365cf5014e028dba7fa89ed6456a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release67070a53c6d14d619c994fb7de9813ef/Teama9d784d161b744bba2953397990a228f",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "release#edit_precondition", "release#edit", "release#advance_task_transition", "release#edit_security", "release#restart_phase", "release#lock_task", "release#edit_task_script", "release#edit_task_configuration_facet", "release#edit_task_flag", "release#edit_task_dates", "release#edit_task", "release#task_transition", "release#edit_task_attachments", "trigger#view_trigger", "release#reassign_task", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#start", "release#edit_blackout", "template#view", "release#edit_failure_handler", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release67070a53c6d14d619c994fb7de9813ef/Team78260968498c428096f567954e78db88",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

Table 92. /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/Release162151faba694d03aa3065665cf26f21/Risk
Curl
$ curl 'http://localhost:5516/api/v1/risks/Applications/Release162151faba694d03aa3065665cf26f21/Risk' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/Applications/Release162151faba694d03aa3065665cf26f21/Risk' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
  "type" : "xlrelease.Risk",
  "score" : 90,
  "totalScore" : 170,
  "riskAssessments" : [ {
    "id" : "520024268",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailedRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 90,
    "headline" : "Release has failed",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21 has failed" ]
  }, {
    "id" : "1015244898",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/MoreThanOneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1204235875",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor5Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1134853470",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessorMoreThan5Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "716541302",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAttentionNeededRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "223486010",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1939387333",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "322334309",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailingRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "367955784",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAtRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "161558079",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 50,
    "headline" : "Release contains failed tasks",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726 has failed 1 time" ]
  }, {
    "id" : "1066512981",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseDueDateRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 30,
    "headline" : "Release is overdue",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21 is overdue since 2022-07-14T17:05:08.118" ]
  }, {
    "id" : "527742596",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor3Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2122448621",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2119296980",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/OneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1289806161",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor4Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1981464287",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "127750247",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1988323335",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor2Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1025701359",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "510478546",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1931361552",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/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-Language: en
Content-Type: application/json
Content-Length: 151

{
  "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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept: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/RiskProfiled4b511b83b60401c8d95b1ffe9f01222",
  "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.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "28",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "73",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "63",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "33",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "69"
  }
}

Listing all risk profiles

Table 94. 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-Type: application/json
Content-Length: 3892

[ {
  "id" : "Configuration/riskProfiles/RiskProfileDefault",
  "type" : "xlrelease.RiskProfile",
  "title" : "Default risk profile",
  "defaultProfile" : true,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "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.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskRetriesRiskAssessor2Retries" : "60",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75"
  }
}, {
  "id" : "Configuration/riskProfiles/RiskProfile1515e6168a1d4d639b84400fc1523910",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 1",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "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/RiskProfile45e41ef43f99446883769db9000743d9",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 2",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "67",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "37",
    "xlrelease.ReleaseDueDateRiskAssessor" : "42",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "55",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "32",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "27",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "22",
    "xlrelease.OneTaskOverDueRiskAssessor" : "40",
    "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/RiskProfiledf168eb987444c77a83ba4307bf382fd
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfiledf168eb987444c77a83ba4307bf382fd' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfiledf168eb987444c77a83ba4307bf382fd' \
    'Accept: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

The response contains the risk profile:

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

{
  "id" : "Configuration/riskProfiles/RiskProfiledf168eb987444c77a83ba4307bf382fd",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 1",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "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/RiskProfile3f2683a52904471191434a8e6770920e

{
  "id" : "Configuration/riskProfiles/RiskProfile3f2683a52904471191434a8e6770920e",
  "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/RiskProfile3f2683a52904471191434a8e6770920e' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Configuration/riskProfiles/RiskProfile3f2683a52904471191434a8e6770920e",
  "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/RiskProfile3f2683a52904471191434a8e6770920e",
  "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/RiskProfile3f2683a52904471191434a8e6770920e' \
    'Content-Type:application/json' \
    '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

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-Type: application/json
Content-Length: 1213

{
  "id" : "Configuration/riskProfiles/RiskProfile3f2683a52904471191434a8e6770920e",
  "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.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/RiskProfile2d9451f4d9e74852b9502b04f60211de
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile2d9451f4d9e74852b9502b04f60211de' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile2d9451f4d9e74852b9502b04f60211de' \
    'Accept:application/json'

Using the following path parameters:

Table 97. /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 98. /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/RiskProfile6d592094345446f79d3613401db8a8df",
  "type" : "xlrelease.RiskProfile",
  "title" : "Default risk profile (1)",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "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.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "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/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/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/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/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/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/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/ReleaseDueDateRiskAssessor",
  "type" : "xlrelease.ReleaseDueDateRiskAssessor",
  "title" : "Release past due date",
  "weight" : 1,
  "score" : 30,
  "order" : "4-pd-00",
  "group" : "Release 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/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/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/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/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/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/EnvironmentStage521d3b9b16994433ba2a89689f569ecd",
  "labelIds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/environments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage521d3b9b16994433ba2a89689f569ecd",
  "labelIds" : null
}'
HTTPie
$ echo '{
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage521d3b9b16994433ba2a89689f569ecd",
  "labelIds" : null
}' | http POST 'http://localhost:5516/api/v1/environments' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created environment:

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

{
  "id" : "Configuration/environmentManagement/Environmentb7f3086b25d447ed96654afaee3e789b",
  "title" : "New environment",
  "description" : "Environment description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage521d3b9b16994433ba2a89689f569ecd",
    "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/Environment7e245832615241a1b59b69beda4c8983
Curl
$ curl 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environment7e245832615241a1b59b69beda4c8983' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environment7e245832615241a1b59b69beda4c8983' \
    'Accept:application/json'

Using the following path parameters:

Table 99. /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/Environment7e245832615241a1b59b69beda4c8983",
  "title" : "Environment1",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage30ce6d46dec54058ae4525479a5e6270",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel09369b93ca274a1090532e0ad5210d39",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Update an environment

To update an existing environment, send this request:

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

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

Using the following path parameters:

Table 100. /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/Environment69af27223e834017bb66fc6fcf27ce5e",
  "title" : "New environment title",
  "description" : "New description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage65a5c7bda1914d9785c896a0c3335751",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel2d55854ae3ed4c578ea6e40de58ff33b",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Delete an environment

To delete an existing environment, send this request:

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

Using the following path parameters:

Table 101. /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 'Content-Type: application/json' \
    -H 'Accept: 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' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains a list of the found environments:

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

[ {
  "id" : "Configuration/environmentManagement/Environmentcdbd21f22eb340839b5e1ec6079e9bdc",
  "title" : "Environment1",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage2e211a84e10443338a00d1d363f08dca",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabela6b69d7ff8a24321bec58dace74dad1c",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
} ]

Get all environment reservations for environment

To get all reservations for environment, send this request:

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

Using the following path parameters:

Table 102. /api/v1/environments/{environmentId}/reservations
Parameter Description

environmentId

Environment ID

The response contains a list of reservations for this environment:

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

[ {
  "id" : "Configuration/environmentManagement/EnvironmentReservation3a6732b1c8c74092925c2b0b34c0db5b",
  "startDate" : 1657811133016,
  "endDate" : 1657818333016,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/Environment575fbec94518433db181e17ef402b6b0",
    "title" : "Environment1",
    "description" : "Environment1 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage00557eb9baf04130994edba4ad81bab8",
      "title" : "DEV"
    },
    "labels" : [ {
      "id" : "Configuration/environmentManagement/EnvironmentLabel0caa71858cb146ba92c232d6e38c726d",
      "title" : "AWS",
      "color" : "#ff00ff"
    } ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Applicationce7aae43194f442d88b9d9b945d027be",
    "title" : "APP1"
  } ]
} ]

Get deployable applications for environment

To get all deployable applications for environment, send this request:

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

Using the following path parameters:

Table 103. /api/v1/environments/{environmentId}/applications
Parameter Description

environmentId

Environment ID

The response contains a list of applications that are allowed to be deployed on this environment:

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

[ {
  "id" : "Configuration/environmentManagement/Application8eaaa91ead874a1aac4a49728173a04a",
  "title" : "APP2"
}, {
  "id" : "Configuration/environmentManagement/Applicationdffe38fe63864cd9bcc0864c9733703f",
  "title" : "APP1"
} ]

Environment reservations

Create a new environment reservation

To create a new environment reservation, send this request:

HTTP Request
POST /api/v1/environments/reservations

{
  "startDate" : 1657811196629,
  "endDate" : 1657818396629,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/Environment4116aac2293340d780fcede824f699f7",
  "applicationIds" : [ "Configuration/environmentManagement/Application7ec38ca11197429eb94f3e2d15877342" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "startDate" : 1657811196629,
  "endDate" : 1657818396629,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/Environment4116aac2293340d780fcede824f699f7",
  "applicationIds" : [ "Configuration/environmentManagement/Application7ec38ca11197429eb94f3e2d15877342" ]
}'
HTTPie
$ echo '{
  "startDate" : 1657811196629,
  "endDate" : 1657818396629,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/Environment4116aac2293340d780fcede824f699f7",
  "applicationIds" : [ "Configuration/environmentManagement/Application7ec38ca11197429eb94f3e2d15877342" ]
}' | http POST 'http://localhost:5516/api/v1/environments/reservations' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created reservation:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentReservation9933686dfeaf4e0ba846e1de83b90ea7",
  "startDate" : 1657811196629,
  "endDate" : 1657818396629,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/Environment4116aac2293340d780fcede824f699f7",
    "title" : "Environment1",
    "description" : "Environment1 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage0dbc41e72edc41a8b8041de9ea7350f6",
      "title" : "DEV"
    },
    "labels" : [ {
      "id" : "Configuration/environmentManagement/EnvironmentLabelf832fab4ef024280b891577b7bbdbd21",
      "title" : "AWS",
      "color" : "#ff00ff"
    } ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application7ec38ca11197429eb94f3e2d15877342",
    "title" : "APP1"
  } ]
}

Find an environment reservation by ID

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

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

Using the following path parameters:

Table 104. /api/v1/environments/reservations/{environmentReservationId}
Parameter Description

environmentReservationId

ID of the environment reservation

The response contains the found reservation:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentReservationea955aabc1db495d8453d1d29cece05e",
  "startDate" : 1657811197253,
  "endDate" : 1657814797253,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/Environmentebab6420a03b45d89918265acf834f6e",
    "title" : "Environment1",
    "description" : "Environment1 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStagec544fbdc45f64a08b1b39890563ece34",
      "title" : "DEV"
    },
    "labels" : [ {
      "id" : "Configuration/environmentManagement/EnvironmentLabel9568dfcbe93e4d188752ca040fd77d0b",
      "title" : "AWS",
      "color" : "#ff00ff"
    } ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application38b7aee76403415f80699ef7df89e960",
    "title" : "APP1"
  } ]
}

Update an environment reservation

To update an existing enviornment reservation, send this request:

HTTP Request
PUT /api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationdd8d9d7a455645abb640cec1fcca9c60

{
  "startDate" : 1657811196752,
  "endDate" : 1657814796752,
  "note" : "New note",
  "environmentId" : "Configuration/environmentManagement/Environmentcc29c83ed5fb4eb4acc2ef9fd8bc9a37",
  "applicationIds" : [ "Configuration/environmentManagement/Application41c341f3d35c448ba9151219aaef1fd7" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationdd8d9d7a455645abb640cec1fcca9c60' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "startDate" : 1657811196752,
  "endDate" : 1657814796752,
  "note" : "New note",
  "environmentId" : "Configuration/environmentManagement/Environmentcc29c83ed5fb4eb4acc2ef9fd8bc9a37",
  "applicationIds" : [ "Configuration/environmentManagement/Application41c341f3d35c448ba9151219aaef1fd7" ]
}'
HTTPie
$ echo '{
  "startDate" : 1657811196752,
  "endDate" : 1657814796752,
  "note" : "New note",
  "environmentId" : "Configuration/environmentManagement/Environmentcc29c83ed5fb4eb4acc2ef9fd8bc9a37",
  "applicationIds" : [ "Configuration/environmentManagement/Application41c341f3d35c448ba9151219aaef1fd7" ]
}' | http PUT 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationdd8d9d7a455645abb640cec1fcca9c60' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 105. /api/v1/environments/reservations/{environmentReservationId}
Parameter Description

environmentReservationId

ID of the environment reservation

The response contains the updated reservation:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentReservationdd8d9d7a455645abb640cec1fcca9c60",
  "startDate" : 1657811196752,
  "endDate" : 1657814796752,
  "note" : "New note",
  "environment" : {
    "id" : "Configuration/environmentManagement/Environmentcc29c83ed5fb4eb4acc2ef9fd8bc9a37",
    "title" : "Environment2",
    "description" : "Environment2 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage76d1f7366bfd4bc2a84ef271b7d7425b",
      "title" : "DEV"
    },
    "labels" : [ ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application41c341f3d35c448ba9151219aaef1fd7",
    "title" : "APP1"
  } ]
}

Delete an environment reservation

To delete an existing environment reservation, send this request:

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

Using the following path parameters:

Table 106. /api/v1/environments/reservations/{environmentReservationId}
Parameter Description

environmentReservationId

ID of the environment reservation

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

Search environment reservations

To search environment reservations, send this request:

HTTP Request
POST /api/v1/environments/reservations/search

{
  "environmentTitle" : "Env",
  "stages" : [ "DEV" ],
  "labels" : [ "AWS" ],
  "applications" : [ "APP1" ],
  "from" : 1657811195725,
  "to" : 1657836395725
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations/search' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "environmentTitle" : "Env",
  "stages" : [ "DEV" ],
  "labels" : [ "AWS" ],
  "applications" : [ "APP1" ],
  "from" : 1657811195725,
  "to" : 1657836395725
}'
HTTPie
$ echo '{
  "environmentTitle" : "Env",
  "stages" : [ "DEV" ],
  "labels" : [ "AWS" ],
  "applications" : [ "APP1" ],
  "from" : 1657811195725,
  "to" : 1657836395725
}' | http POST 'http://localhost:5516/api/v1/environments/reservations/search' \
    'Content-Type:application/json' \
    'Accept:application/json'
The difference between start and end date in search filter is maximum of 90 days.

The response contains a list of environments and reservations created on them:

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

[ {
  "id" : "Configuration/environmentManagement/Environmentc6d7f66ced954835bf4187308ff4820f",
  "title" : "Environment1",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage5ab241f742c240e18881969d7ba51b60",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel4e3bfd2136354fc49a3b1e13ca806b5d",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ],
  "reservations" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentReservationf801db1545e942228f232efea5753b1f",
    "startDate" : 1657811195725,
    "endDate" : 1657814795725,
    "note" : "Note",
    "applications" : [ {
      "id" : "Configuration/environmentManagement/Applicationcad74336efc04a63b931127d7a8331fc",
      "title" : "APP1"
    } ]
  }, {
    "id" : "Configuration/environmentManagement/EnvironmentReservation3808a3dca0064112b71e514cab86df69",
    "startDate" : 1657811195725,
    "endDate" : 1657836395725,
    "note" : null,
    "applications" : [ {
      "id" : "Configuration/environmentManagement/Applicationcad74336efc04a63b931127d7a8331fc",
      "title" : "APP1"
    } ]
  } ]
} ]

Add an application to an environment reservation

To add an application to an environemt reservation, send this request:

HTTP Request
POST /api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationa6679aec0961433e94a30c0f53328a75?applicationId=Configuration/environmentManagement/Application02d9da15a4684cef862223fa3fbd9cf9
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationa6679aec0961433e94a30c0f53328a75?applicationId=Configuration/environmentManagement/Application02d9da15a4684cef862223fa3fbd9cf9' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationa6679aec0961433e94a30c0f53328a75?applicationId=Configuration/environmentManagement/Application02d9da15a4684cef862223fa3fbd9cf9' \
    'Accept:application/json'

Using the following path parameters:

Table 107. /api/v1/environments/reservations/{environmentReservationId}
Parameter Description

environmentReservationId

ID of the environment reservation

and request parameters and their description:

Parameter Description

applicationId

The ID of the application to be added to the environment reservation

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

Environment stages

Create a new environment stage

To create a new environment stage, send this request:

HTTP Request
POST /api/v1/environments/stages

{
  "title" : "PROD1"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/stages' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "PROD1"
}'
HTTPie
$ echo '{
  "title" : "PROD1"
}' | http POST 'http://localhost:5516/api/v1/environments/stages' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created stage:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentStageee7745db2c6f420191184ad0ebf94a00",
  "title" : "PROD1"
}

Find an environment stage by ID

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

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

Using the following path parameters:

Table 108. /api/v1/environments/stages/{environmentStageId}
Parameter Description

environmentStageId

Environment stage ID

The response contains the found stage:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentStage76afc803e40e40f8993ba5195e5df8b7",
  "title" : "DEV1"
}

Update an environment stage

To update an existing environment stage, send this request:

HTTP Request
PUT /api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStage7212a1085ebb471cbe1b5ea8dcbe879f

{
  "title" : "TEST1"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStage7212a1085ebb471cbe1b5ea8dcbe879f' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "TEST1"
}'
HTTPie
$ echo '{
  "title" : "TEST1"
}' | http PUT 'http://localhost:5516/api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStage7212a1085ebb471cbe1b5ea8dcbe879f' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 109. /api/v1/environments/stages/{environmentStageId}
Parameter Description

environmentStageId

Environment stage ID

The response contains the updated stage:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentStage7212a1085ebb471cbe1b5ea8dcbe879f",
  "title" : "TEST1"
}

Delete an environment stage

To delete an existing environment stage, send this request:

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

Using the following path parameters:

Table 110. /api/v1/environments/stages/{environmentStageId}
Parameter Description

environmentStageId

Environment stage ID

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

Search environment stages

To search environment stages, send this request:

HTTP Request
POST /api/v1/environments/stages/search

{
  "title" : "TE"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/stages/search' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "TE"
}'
HTTPie
$ echo '{
  "title" : "TE"
}' | http POST 'http://localhost:5516/api/v1/environments/stages/search' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains a list of the found stages:

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

[ {
  "id" : "Configuration/environmentManagement/EnvironmentStagec921a23eba6f4e90b000d24bdd81d870",
  "title" : "TEST1"
} ]

Environment labels

Create a new environment label

To create a new environment label, send this request:

HTTP Request
POST /api/v1/environments/labels

{
  "title" : "Azure",
  "color" : "#11aabb"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/labels' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Azure",
  "color" : "#11aabb"
}'
HTTPie
$ echo '{
  "title" : "Azure",
  "color" : "#11aabb"
}' | http POST 'http://localhost:5516/api/v1/environments/labels' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created label:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentLabelcfb461c6f742486d9b3ee5ef29d5e562",
  "title" : "Azure",
  "color" : "#11aabb"
}

Find an environment label by ID

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

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

Using the following path parameters:

Table 111. /api/v1/environments/labels/{environmentLabelId}
Parameter Description

environmentLabelId

Environment label ID

The response contains the found label:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentLabel1c4d936bff474913a5e82cbc2d9bd6dc",
  "title" : "AWS",
  "color" : "#ff00ff"
}

Update an environment label

To update an existing environment label, send this request:

HTTP Request
PUT /api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabelcd4a393d55b84e22bbd5367be14891b8

{
  "title" : "RDS",
  "color" : "#ff00ff"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabelcd4a393d55b84e22bbd5367be14891b8' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "RDS",
  "color" : "#ff00ff"
}'
HTTPie
$ echo '{
  "title" : "RDS",
  "color" : "#ff00ff"
}' | http PUT 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabelcd4a393d55b84e22bbd5367be14891b8' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 112. /api/v1/environments/labels/{environmentLabelId}
Parameter Description

environmentLabelId

Environment label ID

The response contains the updated label:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentLabelcd4a393d55b84e22bbd5367be14891b8",
  "title" : "RDS",
  "color" : "#ff00ff"
}

Delete an environment label

To delete an existing environment label, send this request:

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

Using the following path parameters:

Table 113. /api/v1/environments/labels/{environmentLabelId}
Parameter Description

environmentLabelId

Environment label ID

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

Search environment labels

To search environment labels, send this request:

HTTP Request
POST /api/v1/environments/labels/search

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

The response contains a list of the found labels:

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

[ {
  "id" : "Configuration/environmentManagement/EnvironmentLabel9bc22810c8db44df898bd4a3cfeef945",
  "title" : "Openshift",
  "color" : "#aaaaaa"
} ]

Applications

Create a new application

To create a new application, send this request:

HTTP Request
POST /api/v1/applications

{
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment7a11c5cbe9c740baace4eea10ed9e7b6" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/applications' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment7a11c5cbe9c740baace4eea10ed9e7b6" ]
}'
HTTPie
$ echo '{
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment7a11c5cbe9c740baace4eea10ed9e7b6" ]
}' | http POST 'http://localhost:5516/api/v1/applications' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created application:

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

{
  "id" : "Configuration/environmentManagement/Application56f49cda94cb4851869e8f417ff9178e",
  "title" : "New application",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment7a11c5cbe9c740baace4eea10ed9e7b6",
    "title" : "ENV1"
  } ]
}

Find an application by ID

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

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

Using the following path parameters:

Table 114. /api/v1/applications/{applicationId}
Parameter Description

applicationId

Application ID

The response contains the found application:

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

{
  "id" : "Configuration/environmentManagement/Application0dfc85074ee24b14b327a61661ffa68b",
  "title" : "Application1",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment962a1761f2c74a758ec367b049a82f81",
    "title" : "ENV1"
  } ]
}

Update an application

To update an existing application, send this request:

HTTP Request
PUT /api/v1/applications/Configuration/environmentManagement/Applicationcf174bfe5dbb4c17bc8c8d28951c49f6

{
  "title" : "New application title",
  "environmentIds" : [ "Configuration/environmentManagement/Environment1a50dc79786a4c94a4e803e89fd1d4c4" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/applications/Configuration/environmentManagement/Applicationcf174bfe5dbb4c17bc8c8d28951c49f6' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "New application title",
  "environmentIds" : [ "Configuration/environmentManagement/Environment1a50dc79786a4c94a4e803e89fd1d4c4" ]
}'
HTTPie
$ echo '{
  "title" : "New application title",
  "environmentIds" : [ "Configuration/environmentManagement/Environment1a50dc79786a4c94a4e803e89fd1d4c4" ]
}' | http PUT 'http://localhost:5516/api/v1/applications/Configuration/environmentManagement/Applicationcf174bfe5dbb4c17bc8c8d28951c49f6' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 115. /api/v1/applications/{applicationId}
Parameter Description

applicationId

Application ID

The response contains the updated environment:

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

{
  "id" : "Configuration/environmentManagement/Applicationcf174bfe5dbb4c17bc8c8d28951c49f6",
  "title" : "New application title",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment1a50dc79786a4c94a4e803e89fd1d4c4",
    "title" : "ENV1"
  } ]
}

Delete an application

To delete an existing application, send this request:

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

Using the following path parameters:

Table 116. /api/v1/applications/{applicationId}
Parameter Description

applicationId

Application ID

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

Search applications

To search applications, send this request:

HTTP Request
POST /api/v1/applications/search

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

The response contains a list of the found applications:

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

[ {
  "id" : "Configuration/environmentManagement/Application53e7b587fe074d3bb7dacc30dc743401",
  "title" : "Application1",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment77ed1dd574a5410fab1a6732189620ac",
    "title" : "ENV1"
  } ]
}, {
  "id" : "Configuration/environmentManagement/Application69a004535cdb4fa5a7e1c84a99141905",
  "title" : "Application2",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment77ed1dd574a5410fab1a6732189620ac",
    "title" : "ENV1"
  } ]
} ]

Triggers

Search Triggers

To search triggers, send this request:

HTTP Request
GET /api/v1/triggers?triggerTitle=new%20trigger&templateTitle=new%20template&sort=triggerTitle,asc&page=0&resultsPerPage=100
Curl
$ curl 'http://localhost:5516/api/v1/triggers?triggerTitle=new%20trigger&templateTitle=new%20template&sort=triggerTitle,asc&page=0&resultsPerPage=100' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/triggers?triggerTitle=new%20trigger&templateTitle=new%20template&sort=triggerTitle,asc&page=0&resultsPerPage=100' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Parameter Description

triggerTitle

The (optional) case-insensitive title matches the part of the trigger title.

templateTitle

The (optional) case-insensitive title matches the part of the release template title.

sort

The (optional) sort column with asc or desc order

page

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

resultsPerPage

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

The response contains a list of the found triggers:

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

{
  "totalElements" : 1,
  "totalPages" : 1,
  "size" : 100,
  "number" : 0,
  "numberOfElements" : 1,
  "content" : [ {
    "triggerId" : "Applications/Folder01345a690c16b345168751d62934e912/Trigger321",
    "triggerTitle" : "new trigger",
    "triggerType" : "unit.TestTrigger",
    "triggerEnabled" : false,
    "templateTitle" : "new template",
    "templateId" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
    "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
    "folderTitle" : "Folder 7",
    "description" : "new trigger's description!",
    "editable" : true,
    "lastRunDate" : null,
    "lastRunStatus" : null
  } ],
  "first" : true,
  "last" : true
}

All the fields in the response and their description:

Path Type Description

totalElements

Number

The total amount of elements.

totalPages

Number

The number of total pages.

size

Number

The size of the Slice.

number

Number

The number of the current Slice.

numberOfElements

Number

The number of elements currently on this Slice.

first

Boolean

The current Slice is the first one.

last

Boolean

The current Slice is the last one.

content[].triggerId

String

This field contains ID of trigger.

content[].triggerTitle

String

The title of the trigger.

content[].description

String

The description of the trigger.

content[].triggerType

String

The type of the trigger.

content[].triggerEnabled

Boolean

The trigger is enabled.

content[].templateId

String

This field contains ID of template.

content[].templateTitle

String

The title of the template.

content[].folderId

String

This field contains ID of folder.

content[].folderTitle

String

The title of the folder

content[].lastRunDate

String

The last run date of the trigger.

content[].lastRunStatus

String

The last run status of the trigger.

Create Trigger

To create a trigger send this request:

HTTP Request
POST /api/v1/triggers

{
  "id" : null,
  "type" : "unit.TestTrigger",
  "title" : "Test trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "releaseFolder" : "Applications/Folder01345a690c16b345168751d62934e912",
  "count" : 0,
  "username" : "admin",
  "password" : "admin"
}
Curl
$ curl 'http://localhost:5516/api/v1/triggers' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "unit.TestTrigger",
  "title" : "Test trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "releaseFolder" : "Applications/Folder01345a690c16b345168751d62934e912",
  "count" : 0,
  "username" : "admin",
  "password" : "admin"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "unit.TestTrigger",
  "title" : "Test trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "releaseFolder" : "Applications/Folder01345a690c16b345168751d62934e912",
  "count" : 0,
  "username" : "admin",
  "password" : "admin"
}' | http POST 'http://localhost:5516/api/v1/triggers' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following patameters:

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

title

String

Symbolic name for the trigger

description

String

The description of the trigger.

enabled

Boolean

Enabled

triggerState

String

Trigger State

folderId

String

Folder that the trigger belongs to.

allowParallelExecution

Boolean

Allows parallel execution of triggers (ie parallel processing of execute requests/scripts).

lastRunDate

String

Last run date.

lastRunStatus

String

Last run execution status.

pollType

String

Type of polling to use; this is a repeatable period in seconds (for example, every 10 seconds) or a cron expression

periodicity

String

Interval in seconds (REPEAT) or as a cron expression (CRON). The cron pattern is a list of six fields separated by a single space; these fields represent second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of their English names. For example: 0 0 * * * * = the top of every hour of every day; */10 * * * * * = every ten seconds; 0 0 9-17 * * MON-FRI = on the hour nine-to-five weekdays

initialFire

Boolean

Set this property to true to trigger a new release on the initial trigger fire. Otherwise, the first release will be triggered on the next state change

releaseTitle

String

Name given to releases created by this trigger. This field can contain variables.

executionId

String

Not in Use. Keep it for backwards compatibility.

variables

Array

Variables

template

String

Template

tags

Array

Tags

releaseFolder

String

Folder where releases generated by the trigger will be created.

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

Create event-based Trigger

To create an event-based trigger send this request:

HTTP Request
POST /api/v1/triggers

{
  "id" : null,
  "type" : "events.EventBasedTrigger",
  "title" : "Webhook trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "mappedProperties" : [ {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "templateId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912/Release123"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseTitle",
    "value" : "Created release from webhook trigger"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "tags",
    "variableKey" : "event.pull_request.tags"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "variables[prTitle]",
    "variableKey" : "event.pull_request.title"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseFolderId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912"
  } ],
  "triggerActionType" : "xlrelease.CreateReleaseFromTemplateAction",
  "eventSource" : "Applications/Folder01345a690c16b345168751d62934e912/ConfigurationTest_source_1",
  "eventType" : "events.HttpRequestEvent",
  "eventFilter" : {
    "id" : null,
    "type" : "events.GroovyEventFilter",
    "trigger" : null,
    "expr" : "headers['X-GitHub-Event'] == 'pull_request'"
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/triggers' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "events.EventBasedTrigger",
  "title" : "Webhook trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "mappedProperties" : [ {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "templateId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912/Release123"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseTitle",
    "value" : "Created release from webhook trigger"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "tags",
    "variableKey" : "event.pull_request.tags"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "variables[prTitle]",
    "variableKey" : "event.pull_request.title"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseFolderId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912"
  } ],
  "triggerActionType" : "xlrelease.CreateReleaseFromTemplateAction",
  "eventSource" : "Applications/Folder01345a690c16b345168751d62934e912/ConfigurationTest_source_1",
  "eventType" : "events.HttpRequestEvent",
  "eventFilter" : {
    "id" : null,
    "type" : "events.GroovyEventFilter",
    "trigger" : null,
    "expr" : "headers['X-GitHub-Event'] == 'pull_request'"
  }
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "events.EventBasedTrigger",
  "title" : "Webhook trigger",
  "enabled" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "mappedProperties" : [ {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "templateId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912/Release123"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseTitle",
    "value" : "Created release from webhook trigger"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "tags",
    "variableKey" : "event.pull_request.tags"
  }, {
    "id" : null,
    "type" : "xlrelease.VariableValue",
    "targetProperty" : "variables[prTitle]",
    "variableKey" : "event.pull_request.title"
  }, {
    "id" : null,
    "type" : "xlrelease.StringValue",
    "targetProperty" : "releaseFolderId",
    "value" : "Applications/Folder01345a690c16b345168751d62934e912"
  } ],
  "triggerActionType" : "xlrelease.CreateReleaseFromTemplateAction",
  "eventSource" : "Applications/Folder01345a690c16b345168751d62934e912/ConfigurationTest_source_1",
  "eventType" : "events.HttpRequestEvent",
  "eventFilter" : {
    "id" : null,
    "type" : "events.GroovyEventFilter",
    "trigger" : null,
    "expr" : "headers['X-GitHub-Event'] == 'pull_request'"
  }
}' | http POST 'http://localhost:5516/api/v1/triggers' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following patameters:

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

title

String

Symbolic name for the trigger

description

String

The description of the trigger.

enabled

Boolean

Enabled

triggerState

String

Trigger State

folderId

String

Folder that the trigger belongs to.

allowParallelExecution

Boolean

Allows parallel execution of triggers (ie parallel processing of execute requests/scripts).

lastRunDate

String

Last run date.

lastRunStatus

String

Last run execution status.

mappedProperties

Array

Trigger action property mappings

triggerActionType

String

The action to execute when the trigger fires

eventSource

Varies

The HTTP endpoint or the typed event source on which the trigger listens

eventType

String

The type of the event to listen for

eventFilter

Varies

Filter expression to conditionally execute the trigger depending on the data inside the event

You receive the created event-based trigger as a response containing its normal fields.

Update Trigger

To update a trigger send this request:

HTTP Request
PUT /api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084",
  "type" : "unit.TestTrigger",
  "title" : "Updated trigger title",
  "enabled" : false,
  "triggerState" : "",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "count" : 0,
  "username" : "admin",
  "password" : "********"
}
Curl
$ curl 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084",
  "type" : "unit.TestTrigger",
  "title" : "Updated trigger title",
  "enabled" : false,
  "triggerState" : "",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "count" : 0,
  "username" : "admin",
  "password" : "********"
}'
HTTPie
$ echo '{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084",
  "type" : "unit.TestTrigger",
  "title" : "Updated trigger title",
  "enabled" : false,
  "triggerState" : "",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "allowParallelExecution" : false,
  "pollType" : "REPEAT",
  "periodicity" : "10",
  "initialFire" : false,
  "releaseTitle" : "Created release from test trigger",
  "variables" : [ ],
  "template" : "Applications/Folder01345a690c16b345168751d62934e912/Release123",
  "tags" : [ ],
  "count" : 0,
  "username" : "admin",
  "password" : "********"
}' | http PUT 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger9873234084' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following patameters:

Table 117. /api/v1/triggers/{triggerId}
Parameter Description

triggerId

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

title

String

Symbolic name for the trigger

description

String

The description of the trigger.

enabled

Boolean

Enabled

triggerState

String

Trigger State

folderId

String

Folder that the trigger belongs to.

allowParallelExecution

Boolean

Allows parallel execution of triggers (ie parallel processing of execute requests/scripts).

lastRunDate

String

Last run date.

lastRunStatus

String

Last run execution status.

pollType

String

Type of polling to use; this is a repeatable period in seconds (for example, every 10 seconds) or a cron expression

periodicity

String

Interval in seconds (REPEAT) or as a cron expression (CRON). The cron pattern is a list of six fields separated by a single space; these fields represent second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of their English names. For example: 0 0 * * * * = the top of every hour of every day; */10 * * * * * = every ten seconds; 0 0 9-17 * * MON-FRI = on the hour nine-to-five weekdays

initialFire

Boolean

Set this property to true to trigger a new release on the initial trigger fire. Otherwise, the first release will be triggered on the next state change

releaseTitle

String

Name given to releases created by this trigger. This field can contain variables.

executionId

String

Not in Use. Keep it for backwards compatibility.

variables

Array

Variables

template

String

Template

tags

Array

Tags

releaseFolder

String

Folder where releases generated by the trigger will be created.

You receive the updated trigger as a response containing its normal fields.

Enable Trigger

To enable trigger, send this request:

HTTP Request
PUT /api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/enable
Curl
$ curl 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/enable' -i -X PUT
HTTPie
$ http PUT 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/enable'

Using the following path parameters:

Table 118. /api/v1/triggers/{triggerId}/enable
Parameter Description

triggerId

Full identifier of the trigger.

To enable multiple triggers, send this request:

HTTP Request
POST /api/v1/triggers/enable

[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]
Curl
$ curl 'http://localhost:5516/api/v1/triggers/enable' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]'
HTTPie
$ echo '[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]' | http POST 'http://localhost:5516/api/v1/triggers/enable' \
    'Content-Type:application/json' \
    'Accept:application/json'

All the fields in the response and their description:

Path Type Description

updatedIds

Array

This fields contains IDs of updated triggers.

To enable multiple triggers which user has access to, send this request:

HTTP Request
POST /api/v1/triggers/enable/all
Curl
$ curl 'http://localhost:5516/api/v1/triggers/enable/all' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/triggers/enable/all' \
    'Accept:application/json'

All the fields in the response and their description:

Path Type Description

updatedIds

Array

This fields contains IDs of updated triggers.

Disable Trigger

To disable trigger, send this request:

HTTP Request
PUT /api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/disable
Curl
$ curl 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/disable' -i -X PUT
HTTPie
$ http PUT 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/disable'

Using the following path parameters:

Table 119. /api/v1/triggers/{triggerId}/disable
Parameter Description

triggerId

Full identifier of the trigger.

To disable multiple triggers, send this request:

HTTP Request
POST /api/v1/triggers/disable

[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]
Curl
$ curl 'http://localhost:5516/api/v1/triggers/disable' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]'
HTTPie
$ echo '[ "Applications/Folder01345a690c16b345168751d62934e912/Trigger321" ]' | http POST 'http://localhost:5516/api/v1/triggers/disable' \
    'Content-Type:application/json' \
    'Accept:application/json'

All the fields in the response and their description:

Path Type Description

updatedIds

Array

This fields contains IDs of updated triggers.

To disable multiple triggers which user has access to, send this request:

HTTP Request
POST /api/v1/triggers/disable/all
Curl
$ curl 'http://localhost:5516/api/v1/triggers/disable/all' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/triggers/disable/all' \
    'Accept:application/json'

All the fields in the response and their description:

Path Type Description

updatedIds

Array

This fields contains IDs of updated triggers.

Delete Trigger

To delete trigger, send this request:

HTTP Request
DELETE /api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321
Curl
$ curl 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321'

Using the following path parameters:

Table 120. /api/v1/triggers/{triggerId}
Parameter Description

triggerId

Full identifier of the trigger.

Execute Trigger

To execute trigger, send this request:

HTTP Request
POST /api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/run
Curl
$ curl 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/run' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/triggers/Applications/Folder01345a690c16b345168751d62934e912/Trigger321/run' \
    'Accept:application/json'

Using the following path parameters:

Table 121. /api/v1/triggers/{triggerId}/run
Parameter Description

triggerId

Full identifier of the trigger.

Get Trigger

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

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

Using the following path parameters:

Table 122. /api/v1/triggers/{triggerId}
Parameter Description

triggerId

Full identifier of the trigger.

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

title

String

Symbolic name for the trigger

description

String

The description of the trigger.

enabled

Boolean

Enabled

triggerState

String

Trigger State

folderId

String

Folder that the trigger belongs to.

allowParallelExecution

Boolean

Allows parallel execution of triggers (ie parallel processing of execute requests/scripts).

lastRunDate

String

Last run date.

lastRunStatus

String

Last run execution status.

pollType

String

Type of polling to use; this is a repeatable period in seconds (for example, every 10 seconds) or a cron expression

periodicity

String

Interval in seconds (REPEAT) or as a cron expression (CRON). The cron pattern is a list of six fields separated by a single space; these fields represent second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of their English names. For example: 0 0 * * * * = the top of every hour of every day; */10 * * * * * = every ten seconds; 0 0 9-17 * * MON-FRI = on the hour nine-to-five weekdays

initialFire

Boolean

Set this property to true to trigger a new release on the initial trigger fire. Otherwise, the first release will be triggered on the next state change

releaseTitle

String

Name given to releases created by this trigger. This field can contain variables.

executionId

String

Not in Use. Keep it for backwards compatibility.

variables

Array

Variables

template

String

Template

tags

Array

Tags

releaseFolder

String

Folder where releases generated by the trigger will be created.

Delivery Patterns

Create a delivery pattern

To create a new delivery pattern, send this request:

HTTP Request
POST /api/v1/delivery-patterns

{
  "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage3b4878a790f142bb937f7af02081e73a",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage0628f525f1bd42cbb5622efa74b789c0",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage6e7e6e92ae86444c9e328e7bfa216e83",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage8482a1814ccb4965b37d29592d1b174a",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage3b4878a790f142bb937f7af02081e73a",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage0628f525f1bd42cbb5622efa74b789c0",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage6e7e6e92ae86444c9e328e7bfa216e83",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage8482a1814ccb4965b37d29592d1b174a",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage3b4878a790f142bb937f7af02081e73a",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage0628f525f1bd42cbb5622efa74b789c0",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage6e7e6e92ae86444c9e328e7bfa216e83",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryd59ccaba41504b729032e3ad3effd709/Stage8482a1814ccb4965b37d29592d1b174a",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns' \
    'Content-Type:application/json' \
    'Accept:application/json'

The response contains the created pattern:

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

{
  "id" : "Deliveries/Delivery2dd84550bdad48999df409e8e7c26924",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery2dd84550bdad48999df409e8e7c26924/Stage3b4878a790f142bb937f7af02081e73a",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery2dd84550bdad48999df409e8e7c26924/Stage0628f525f1bd42cbb5622efa74b789c0",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery2dd84550bdad48999df409e8e7c26924/Stage6e7e6e92ae86444c9e328e7bfa216e83",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery2dd84550bdad48999df409e8e7c26924/Stage8482a1814ccb4965b37d29592d1b174a",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}

Find a delivery pattern by ID

To find a delivery pattern by its ID, send this request:

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

Using the following path parameters:

Table 123. /api/v1/delivery-patterns/{patternId}
Parameter Description

patternId

The id of the pattern

The response contains the found pattern:

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

{
  "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27/Staged244e48b2a394ad7b0f3eb77c8755893",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27/Stagef4e5285cd13b43369f3e0904ae279e18",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27/Stage85a77b8f51f9455d9a7301bb2cfb4abf",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27/Stageccb0b48c3df0495faf7df61ffb9eba41",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliveryce8e826690744baf95aa19027ce0bf27/TrackedItem968e037b57194e00bcb7922a43c13d42",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:48.859+02:00",
    "modifiedDate" : "2022-07-14T17:05:48.859+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : false,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Find a delivery pattern by ID or title

To find a delivery pattern by its ID or title, send this request:

HTTP Request
GET /api/v1/delivery-patterns/Test%20pattern
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Test%20pattern' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Test%20pattern' \
    'Accept:application/json'

Using the following path parameters:

Table 124. /api/v1/delivery-patterns/{patternIdOrTitle}
Parameter Description

patternIdOrTitle

The id or title of the pattern

The response contains the found pattern:

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

{
  "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7/Staged796d70548554b41ab149dbb1365e833",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7/Staged079f0e8bd6348b6b718cb49e59bfe1a",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7/Stage1112581c8bdd4eba9949db8e3e959442",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7/Stagee20b855ce5f249038d32f601f24b5f52",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery5a72a23eb13446b69f2947472add95e7/TrackedItemf41e2fe33c904d1287f9dfc717e2b089",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:44.180+02:00",
    "modifiedDate" : "2022-07-14T17:05:44.180+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : false,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Update a delivery pattern

To update an existing delivery pattern, send this request:

HTTP Request
PUT /api/v1/delivery-patterns/Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a

{
  "id" : "Deliveries/Delivery3612e9f2145f453fa92a6cf75e975fca",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 72,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Deliveries/Delivery3612e9f2145f453fa92a6cf75e975fca",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 72,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : "Deliveries/Delivery3612e9f2145f453fa92a6cf75e975fca",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 72,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}' | http PUT 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 125. /api/v1/delivery-patterns/{patternId}
Parameter Description

patternId

The id of the pattern

The response contains the updated pattern:

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

{
  "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "startDate" : "2022-07-14T17:05:54.808+02:00",
  "endDate" : "2022-07-17T17:05:54.808+02:00",
  "plannedDuration" : 72,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a/Stage531fede77d574016b61483a642994982",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a/Stage9d30ccb01330454d9af36c93521ea264",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a/Staged43c97ef4d414f32beedbefccee791a2",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a/Stage90ef3ee1db324735b9083c77be1bad69",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery9689b44ea59845faaf3e8cee4cac8d0a/TrackedIteme860c350c3504b818aa44503db2ba7ad",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:54.694+02:00",
    "modifiedDate" : "2022-07-14T17:05:54.694+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : false,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Delete a delivery pattern

To delete an existing delivery pattern, send this request:

HTTP Request
DELETE /api/v1/delivery-patterns/Deliveries/Deliveryf517bacd09034ff4b9f6d1208dea98aa
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryf517bacd09034ff4b9f6d1208dea98aa' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryf517bacd09034ff4b9f6d1208dea98aa'

Using the following path parameters:

Table 126. /api/v1/delivery-patterns/{patternId}
Parameter Description

patternId

The id of the pattern

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

Create a delivery from a pattern

To create a delivery from a pattern, send this request:

HTTP Request
POST /api/v1/delivery-patterns/Deliveries/Delivery45a1655d66dc4213abac50a954bcf9de/create

{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "duration" : 0,
  "startDate" : 1657811145648,
  "endDate" : 1657839945648,
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery45a1655d66dc4213abac50a954bcf9de/create' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "duration" : 0,
  "startDate" : 1657811145648,
  "endDate" : 1657839945648,
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "duration" : 0,
  "startDate" : 1657811145648,
  "endDate" : 1657839945648,
  "autoComplete" : false
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery45a1655d66dc4213abac50a954bcf9de/create' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Table 127. /api/v1/delivery-patterns/{patternId}/create
Parameter Description

patternId

The id of the pattern
Path Type Description

folderId

String

The folder ID where the delivery will be stored

title

String

The title of the delivery

description

String

The description of the delivery

duration

Number

The duration of the delivery. Will be used only if start and end date are null

startDate

Number

The start date of the delivery

endDate

Number

The end date of the delivery

autoComplete

Boolean

Complete delivery when all items are completed, skipped or de-scoped in all stages

The response contains the created delivery:

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

{
  "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:05:45.648+02:00",
  "endDate" : "2022-07-15T01:05:45.648+02:00",
  "plannedDuration" : 8,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Delivery45a1655d66dc4213abac50a954bcf9de",
  "stages" : [ {
    "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stageff9bcfe1c6804261bcaee7696ffe4318",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stageff9bcfe1c6804261bcaee7696ffe4318/StageTrackedItem7cbaa8730bed437f973ad568ba48f667",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/TrackedItem3f6a0c8134e74b9fbc27dd3a31fba099",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stage5c0c324b01ac4560bbd220d83c5c8e87",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stage5c0c324b01ac4560bbd220d83c5c8e87/StageTrackedItem427a2b9c9b2c4444aa9fcbc2fd02aa47",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/TrackedItem3f6a0c8134e74b9fbc27dd3a31fba099",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stagecc25251009144566b135942624c5325f",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stagecc25251009144566b135942624c5325f/StageTrackedItemb9427e2f7d1748278e16fe8ca7384efc",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/TrackedItem3f6a0c8134e74b9fbc27dd3a31fba099",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stage9fbbcbe7c51349c0a68226bad50dcc60",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/Stage9fbbcbe7c51349c0a68226bad50dcc60/StageTrackedItem6ae74d51c84541e98481593fa9ed1c35",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/TrackedItem3f6a0c8134e74b9fbc27dd3a31fba099",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliverye86431c268c14327a5c472f5bfd676ce/TrackedItem3f6a0c8134e74b9fbc27dd3a31fba099",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:45.747+02:00",
    "modifiedDate" : "2022-07-14T17:05:45.747+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : false,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Search delivery patterns

To search delivery patterns, send this request:

HTTP Request
POST /api/v1/delivery-patterns/search?page=0&resultsPerPage=100

{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912"
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/search?page=0&resultsPerPage=100' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912"
}'
HTTPie
$ echo '{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912"
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/search?page=0&resultsPerPage=100' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Path Type Description

title

String

Case-insensitive matches the part of the pattern title

strictTitleMatch

Boolean

Set to true to exact match the pattern title (case-insensitive)

folderId

String

ID of the folder containing the patterns

The response contains a list of the found patterns:

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

[ {
  "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4/Stage81fffa12ea264f718d18ec458fe4b2b7",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4/Stage5448d8acd4a34900855786f05bde8d2d",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4/Stagef231720af07541aabcc5812b27e260d0",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4/Staged5fc5a8d4b4742889b56352bf6c2bb2d",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery7d45d63a34d148149b07f1de63efd2a4/TrackedItem6245337c17ca4fed9066d65cf10a1b40",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:40.171+02:00",
    "modifiedDate" : "2022-07-14T17:05:40.171+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false
}, {
  "id" : "Deliveries/Deliveryaf064573101a4a4d909c9dfab91c1b20",
  "type" : "delivery.Delivery",
  "title" : "Test pattern 2",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryaf064573101a4a4d909c9dfab91c1b20/Stage7703953c5f494c21b512ae9f67226127",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryaf064573101a4a4d909c9dfab91c1b20/Stage7e94fda2dcd54bd1bc8339b8270aa265",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryaf064573101a4a4d909c9dfab91c1b20/Stage3449315c984f46369ba66bb9ad356d86",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryaf064573101a4a4d909c9dfab91c1b20/Stageef3b0df1be3a40d38a87a3ed1ac1f791",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
} ]

Create a stage

To create a stage in a delivery pattern, send this request:

HTTP Request
POST /api/v1/delivery-patterns/Deliveries/Delivery61772455b7634940827669f5a1af904a/stages/4

{
  "id" : "1905006737",
  "type" : "delivery.Stage",
  "title" : "New stage",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Owner user",
  "team" : "Owner team"
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery61772455b7634940827669f5a1af904a/stages/4' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "1905006737",
  "type" : "delivery.Stage",
  "title" : "New stage",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Owner user",
  "team" : "Owner team"
}'
HTTPie
$ echo '{
  "id" : "1905006737",
  "type" : "delivery.Stage",
  "title" : "New stage",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Owner user",
  "team" : "Owner team"
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery61772455b7634940827669f5a1af904a/stages/4' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 128. /api/v1/delivery-patterns/{patternId}/stages/{position}
Parameter Description

patternId

The id of the pattern

position

The (optional) position on which the new stage will be inserted on; Zero to insert at the very beginning of the flow; default at the the end of flow

The response contains the created stage:

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

{
  "id" : "Deliveries/Delivery61772455b7634940827669f5a1af904a/Stagea496f015a1814c31aa1559668020c77d",
  "type" : "delivery.Stage",
  "title" : "New stage",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Owner user",
  "team" : "Owner team"
}

Get stages

To get a list of stages in a delivery pattern, send this request:

HTTP Request
GET /api/v1/delivery-patterns/Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/stages
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/stages' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/stages' \
    'Accept:application/json'

Using the following path parameters:

Table 129. /api/v1/delivery-patterns/{patternId}/stages
Parameter Description

patternId

The id of the pattern

The response contains the list of stages:

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

[ {
  "id" : "Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/Stageb36f19a78a604e3588fb2736e4c5dbce",
  "type" : "delivery.Stage",
  "title" : "Feature in Dev",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User Dev",
  "team" : "Team Dev"
}, {
  "id" : "Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/Stageff49b39081cc4a7b97fe036b8d2d0412",
  "type" : "delivery.Stage",
  "title" : "Feature in QA",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User QA",
  "team" : "Team QA"
}, {
  "id" : "Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/Stage46942ac98e40497497b9e6365037908c",
  "type" : "delivery.Stage",
  "title" : "Feature in Pre-Prod",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User Pre-Prod",
  "team" : "Team Pre-Prod"
}, {
  "id" : "Deliveries/Delivery7a7a2d1b23144acdb8ff166ab7e0b3f8/Stage932ba355ceb841dcb3d85c982027526c",
  "type" : "delivery.Stage",
  "title" : "Feature in Prod",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User Prod",
  "team" : "Team Prod"
} ]

Update a stage

To update an existing stage in a delivery pattern, send this request:

HTTP Request
PUT /api/v1/delivery-patterns/Deliveries/Deliveryd1f91416d4ec493cbd11866eba163cd6/Stage5d5ffe62278f402a99917aac12c3d5f4

{
  "id" : null,
  "type" : "delivery.Stage",
  "title" : "Updated stage title",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Updated owner",
  "team" : "Updated team"
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryd1f91416d4ec493cbd11866eba163cd6/Stage5d5ffe62278f402a99917aac12c3d5f4' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.Stage",
  "title" : "Updated stage title",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Updated owner",
  "team" : "Updated team"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.Stage",
  "title" : "Updated stage title",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Updated owner",
  "team" : "Updated team"
}' | http PUT 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryd1f91416d4ec493cbd11866eba163cd6/Stage5d5ffe62278f402a99917aac12c3d5f4' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 130. /api/v1/delivery-patterns/{stageId}
Parameter Description

stageId

The full id of the stage

The response contains the updated stage:

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

{
  "id" : "Deliveries/Deliveryd1f91416d4ec493cbd11866eba163cd6/Stage5d5ffe62278f402a99917aac12c3d5f4",
  "type" : "delivery.Stage",
  "title" : "Updated stage title",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Updated owner",
  "team" : "Updated team"
}

Delete a stage

To delete an existing stage in a delivery pattern, send this request:

HTTP Request
DELETE /api/v1/delivery-patterns/Deliveries/Delivery4cb9c0a82723481c9394b7085e6bd8da/Stage80360cb3ee1a46f98ce3f320638b1727
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery4cb9c0a82723481c9394b7085e6bd8da/Stage80360cb3ee1a46f98ce3f320638b1727' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery4cb9c0a82723481c9394b7085e6bd8da/Stage80360cb3ee1a46f98ce3f320638b1727'

Using the following path parameters:

Table 131. /api/v1/delivery-patterns/{stageId}
Parameter Description

stageId

The full id of the stage

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

Create a transition

To creaate a transition in a delivery pattern, send this request:

HTTP Request
POST /api/v1/delivery-patterns/Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276/transitions

{
  "id" : "1888980457",
  "type" : "delivery.Transition",
  "title" : "New transition",
  "stage" : "Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276",
  "conditions" : [ ],
  "automated" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276/transitions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "1888980457",
  "type" : "delivery.Transition",
  "title" : "New transition",
  "stage" : "Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276",
  "conditions" : [ ],
  "automated" : false
}'
HTTPie
$ echo '{
  "id" : "1888980457",
  "type" : "delivery.Transition",
  "title" : "New transition",
  "stage" : "Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276",
  "conditions" : [ ],
  "automated" : false
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276/transitions' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 132. /api/v1/delivery-patterns/{stageId}/transitions
Parameter Description

stageId

The full id of the stage

The response contains the updated transition:

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

{
  "id" : "Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276/Transition3987ee9f9ee34dffaef585a70c23436b",
  "type" : "delivery.Transition",
  "title" : "New transition",
  "stage" : "Deliveries/Delivery9fb4b32573744abba9f552f454031a04/Stage28a98adb60334537be80ef137846d276",
  "conditions" : [ ],
  "automated" : false
}

Update a transition

To update an existing transition in a delivery pattern, send this request:

HTTP Request
PUT /api/v1/delivery-patterns/Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6

{
  "id" : null,
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54",
  "conditions" : [ {
    "id" : null,
    "type" : "delivery.ConditionGroup",
    "satisfied" : false,
    "operator" : "AND",
    "conditions" : [ {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.ItemsCompletionCondition",
        "satisfied" : false
      } ]
    }, {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.TimeCondition",
        "satisfied" : false,
        "startDateOffset" : 24
      } ]
    } ]
  } ],
  "automated" : true
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54",
  "conditions" : [ {
    "id" : null,
    "type" : "delivery.ConditionGroup",
    "satisfied" : false,
    "operator" : "AND",
    "conditions" : [ {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.ItemsCompletionCondition",
        "satisfied" : false
      } ]
    }, {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.TimeCondition",
        "satisfied" : false,
        "startDateOffset" : 24
      } ]
    } ]
  } ],
  "automated" : true
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54",
  "conditions" : [ {
    "id" : null,
    "type" : "delivery.ConditionGroup",
    "satisfied" : false,
    "operator" : "AND",
    "conditions" : [ {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.ItemsCompletionCondition",
        "satisfied" : false
      } ]
    }, {
      "id" : null,
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : null,
        "type" : "delivery.TimeCondition",
        "satisfied" : false,
        "startDateOffset" : 24
      } ]
    } ]
  } ],
  "automated" : true
}' | http PUT 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 133. /api/v1/delivery-patterns/{transitionId}
Parameter Description

transitionId

The full id of the transition

The response contains the updated transition:

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

{
  "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6",
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54",
  "conditions" : [ {
    "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6/Condition0de94f1a43424397ba8bf7386206fa39",
    "type" : "delivery.ConditionGroup",
    "satisfied" : false,
    "operator" : "AND",
    "conditions" : [ {
      "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6/Conditionb0bdf942bdd142b9a19d3ae5328e1450",
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6/Condition0e19a8fc1f504d12936bacd8822e649a",
        "type" : "delivery.ItemsCompletionCondition",
        "satisfied" : false
      } ]
    }, {
      "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6/Condition1cbb78f765454ba18143249e2a2f1e49",
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : "Deliveries/Deliverybc3a4c00f03e4500abb3c3efc7fc4897/Stage7a601a70935049aa9cf0fe441a400a54/Transitione6d5f26e84c3497baf997191037082b6/Condition927ca100b2df4c01bec5391bd8a53afb",
        "type" : "delivery.TimeCondition",
        "satisfied" : false,
        "startDateOffset" : 24
      } ]
    } ]
  } ],
  "automated" : true
}

Delete a transition

To delete an existing transition in a delivery pattern, send this request:

HTTP Request
DELETE /api/v1/delivery-patterns/Deliveries/Delivery312837a89c9242ef9712d6fd622e5dfc/Stage18fca50beab9463cb7fc20ac6cd1d7a6/Transition781ae6b0b5f94151a14c5630b72da1a1
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery312837a89c9242ef9712d6fd622e5dfc/Stage18fca50beab9463cb7fc20ac6cd1d7a6/Transition781ae6b0b5f94151a14c5630b72da1a1' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery312837a89c9242ef9712d6fd622e5dfc/Stage18fca50beab9463cb7fc20ac6cd1d7a6/Transition781ae6b0b5f94151a14c5630b72da1a1'

Using the following path parameters:

Table 134. /api/v1/delivery-patterns/{transitionId}
Parameter Description

transitionId

The full id of the transition

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

Create a tracked item

To create a tracked item in a delivery pattern, send this request:

HTTP Request
POST /api/v1/delivery-patterns/Deliveries/Delivery3594deb24f7242f1a16f085b0b34ea39/tracked-items

{
  "id" : "892062399",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery3594deb24f7242f1a16f085b0b34ea39/tracked-items' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "892062399",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}'
HTTPie
$ echo '{
  "id" : "892062399",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery3594deb24f7242f1a16f085b0b34ea39/tracked-items' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 135. /api/v1/delivery-patterns/{patternId}/tracked-items
Parameter Description

patternId

The id of the pattern

The response contains the created item:

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

{
  "id" : "Deliveries/Delivery3594deb24f7242f1a16f085b0b34ea39/TrackedItem58a41e6d2691446bafad8626a38dd950",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:35.237+02:00",
  "modifiedDate" : "2022-07-14T17:05:35.237+02:00"
}

Get tracked items

To get a list of tracked items in a delivery pattern, send this request:

HTTP Request
GET /api/v1/delivery-patterns/Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/tracked-items
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/tracked-items' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/tracked-items' \
    'Accept:application/json'

Using the following path parameters:

Table 136. /api/v1/delivery-patterns/{patternId}/tracked-items
Parameter Description

patternId

The id of the pattern

The response contains the list of tracked items:

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

[ {
  "id" : "Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/TrackedItem0e91fa25a619415bb4bedc5cf4209404",
  "type" : "delivery.TrackedItem",
  "title" : "Test item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:47.625+02:00",
  "modifiedDate" : "2022-07-14T17:05:47.625+02:00"
}, {
  "id" : "Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/TrackedItem0a42810a3fec41569ddb48711752665f",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 1",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:47.756+02:00",
  "modifiedDate" : "2022-07-14T17:05:47.756+02:00"
}, {
  "id" : "Deliveries/Delivery9c7e2951843b43e5b35de9fc61b29e0a/TrackedItemb624f715136049bf946cec56fa5c5b97",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 2",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:47.819+02:00",
  "modifiedDate" : "2022-07-14T17:05:47.819+02:00"
} ]

Update a tracked item

To update an existing tracked item in a delivery pattern, send this request:

HTTP Request
PUT /api/v1/delivery-patterns/Deliveries/Deliverye7e10bcd94ff4e2db17ac72c0b6e5933/TrackedItemadf90e9ee81c4a2facf1618ba46afb43

{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:49.819+02:00",
  "modifiedDate" : "2022-07-14T17:05:49.819+02:00"
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverye7e10bcd94ff4e2db17ac72c0b6e5933/TrackedItemadf90e9ee81c4a2facf1618ba46afb43' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:49.819+02:00",
  "modifiedDate" : "2022-07-14T17:05:49.819+02:00"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:49.819+02:00",
  "modifiedDate" : "2022-07-14T17:05:49.819+02:00"
}' | http PUT 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverye7e10bcd94ff4e2db17ac72c0b6e5933/TrackedItemadf90e9ee81c4a2facf1618ba46afb43' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 137. /api/v1/delivery-patterns/{itemId}
Parameter Description

itemId

The full id of the tracked item

The response contains the updated tracked item:

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

{
  "id" : "Deliveries/Deliverye7e10bcd94ff4e2db17ac72c0b6e5933/TrackedItemadf90e9ee81c4a2facf1618ba46afb43",
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:49.819+02:00",
  "modifiedDate" : "2022-07-14T17:05:49.918+02:00"
}

Delete a tracked item

To delete an existing tracked item in a delivery pattern, send this request:

HTTP Request
DELETE /api/v1/delivery-patterns/Deliveries/Delivery066234ea833e45d599abce4c4673ecf3/TrackedItemd5b405e3ccd3461e8e95effd181a9ba3
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery066234ea833e45d599abce4c4673ecf3/TrackedItemd5b405e3ccd3461e8e95effd181a9ba3' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery066234ea833e45d599abce4c4673ecf3/TrackedItemd5b405e3ccd3461e8e95effd181a9ba3' \
    'Accept:application/json'

Using the following path parameters:

Table 138. /api/v1/delivery-patterns/{itemId}
Parameter Description

itemId

The full id of the tracked item

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

Deliveries

Find a delivery by ID

To find a delivery by its ID, send this request:

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

Using the following path parameters:

Table 139. /api/v1/deliveries/{deliveryId}
Parameter Description

deliveryId

The id of the delivery

The response contains the found delivery:

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

{
  "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:05:58.154+02:00",
  "endDate" : "2022-07-16T11:05:58.154+02:00",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Delivery086069676676483d8e24733be6da3ce8",
  "stages" : [ {
    "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec3c0b032498e478cbb53ab41263a838d",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec3c0b032498e478cbb53ab41263a838d/StageTrackedItem1708bb361314404eb4fdb113571cabf9",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/TrackedItem298c5483eacd4aae93d05b6aac088bea",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec3c0b032498e478cbb53ab41263a838d/Transitiondcfe7262e26e4a4cb035e04903cbe4ae",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec3c0b032498e478cbb53ab41263a838d",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec09a74f40a3043c993c2a2528bd0c3d7",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec09a74f40a3043c993c2a2528bd0c3d7/Transition0f8c37c540da4dbcb96c5dd8c40ff10e",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stagec09a74f40a3043c993c2a2528bd0c3d7",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stage9e36979dbf0742288a1ac38773333156",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stage9e36979dbf0742288a1ac38773333156/Transition75137d8852ec44eb8ae55bb5678ae472",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stage9e36979dbf0742288a1ac38773333156",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/Stage86fcdddd714c4965bf06146e03e94425",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery702dc74e2ace4810884c6ebf093ab430/TrackedItem298c5483eacd4aae93d05b6aac088bea",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:05:58.154+02:00",
    "modifiedDate" : "2022-07-14T17:05:58.154+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : true,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Update a delivery

To update an existing delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery99deae7bb949406abb8007f9284a8c68

{
  "id" : null,
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:16.858+02:00",
  "endDate" : "2022-07-15T05:06:16.858+02:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery99deae7bb949406abb8007f9284a8c68' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:16.858+02:00",
  "endDate" : "2022-07-15T05:06:16.858+02:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:16.858+02:00",
  "endDate" : "2022-07-15T05:06:16.858+02:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}' | http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery99deae7bb949406abb8007f9284a8c68' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 140. /api/v1/deliveries/{deliveryId}
Parameter Description

deliveryId

The id of the delivery

The response contains the updated delivery:

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

{
  "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68",
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:16.858+02:00",
  "endDate" : "2022-07-15T05:06:16.858+02:00",
  "plannedDuration" : 12,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Deliveryaf83c9d8e74f4e5387618f55bce48f24",
  "stages" : [ {
    "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage17956611cdfc4d86811c776535f22f79",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage17956611cdfc4d86811c776535f22f79/StageTrackedItemc2bb80a958ce4e739d85c7b91c6be2d1",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/TrackedItemd2a54368c9f54fdd84e1e6dfe79d3675",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage17956611cdfc4d86811c776535f22f79/Transitiond3ede7fc5c2f4aa6a2131e04789db233",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage17956611cdfc4d86811c776535f22f79",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage78ae0082b31841aaa574b9f4f00c738b",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage78ae0082b31841aaa574b9f4f00c738b/Transitionbcce2863730a41cda328ae388549ac1c",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage78ae0082b31841aaa574b9f4f00c738b",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage6ff2fd3891bb4d00b54e6384c21b50ef",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage6ff2fd3891bb4d00b54e6384c21b50ef/Transition59a00c54c0534eafaf8c1f7ea040b7db",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stage6ff2fd3891bb4d00b54e6384c21b50ef",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/Stagefd5c2054a5e6474aa34cc59d68fe00d2",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery99deae7bb949406abb8007f9284a8c68/TrackedItemd2a54368c9f54fdd84e1e6dfe79d3675",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:06:16.850+02:00",
    "modifiedDate" : "2022-07-14T17:06:16.850+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false,
  "$metadata" : {
    "details" : {
      "pattern" : "Test pattern",
      "folder" : "Folder 7",
      "hasPatternViewAccess" : true,
      "hasFolderViewAccess" : true
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "release#edit_security", "group#view", "release#lock_task", "delivery_pattern#view", "template#create_release_other_folder", "group#edit", "template#lock_task", "folder#generate_configuration", "release#task_transition", "delivery_pattern#edit", "trigger#view_trigger", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_versions", "trigger#edit_trigger", "folder#apply_changes", "release#view", "folder#edit_notifications", "delivery#view", "release#edit_blackout", "release#edit_failure_handler", "template#edit_precondition", "folder#edit", "release#abort", "template#edit_failure_handler", "folder#edit_variables", "folder#edit_configuration", "release#advance_task_transition", "folder#edit_versions", "release#restart_phase", "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#edit_task_attachments", "release#reassign_task", "delivery#edit", "template#edit_security", "template#create_release", "release#edit_task_description", "delivery#edit_tracked_item", "release#start", "template#view", "template#edit_triggers", "dashboard#edit", "folder#edit_security" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
}

Delete a delivery

To delete an existing delivery, send this request:

HTTP Request
DELETE /api/v1/deliveries/Deliveries/Deliverybcaa0f3081204030b7786d1192f885b4
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybcaa0f3081204030b7786d1192f885b4' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybcaa0f3081204030b7786d1192f885b4'

Using the following path parameters:

Table 141. /api/v1/deliveries/{deliveryId}
Parameter Description

deliveryId

The id of the delivery

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

Search deliveries

To search deliveries, send this request:

HTTP Request
POST /api/v1/deliveries/search?page=0&resultsPerPage=100&orderBy=CREATED_DATE

{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "",
  "statuses" : [ "IN_PROGRESS", "COMPLETED" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/search?page=0&resultsPerPage=100&orderBy=CREATED_DATE' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "",
  "statuses" : [ "IN_PROGRESS", "COMPLETED" ]
}'
HTTPie
$ echo '{
  "title" : "Test",
  "strictTitleMatch" : false,
  "trackedItemTitle" : "",
  "strictTrackedItemTitleMatch" : false,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "",
  "statuses" : [ "IN_PROGRESS", "COMPLETED" ]
}' | http POST 'http://localhost:5516/api/v1/deliveries/search?page=0&resultsPerPage=100&orderBy=CREATED_DATE' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Path Type Description

title

String

Case-insensitive matches the part of the delivery title

strictTitleMatch

Boolean

Set to true to exact match the delivery title (case-insensitive)

folderId

String

ID of the folder containing the deliveries

originPatternId

String

ID of the delivery pattern the deliveries were created from

statuses

Array

Delivery statuses to filter by

The response contains a list of the found deliveries:

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

[ {
  "id" : "Deliveries/Delivery77959a2838044a7dab64c83d70bef9ce",
  "type" : "delivery.Delivery",
  "title" : "Test delivery 2",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:01.400+02:00",
  "endDate" : "2022-07-19T17:06:01.400+02:00",
  "plannedDuration" : 120,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery77959a2838044a7dab64c83d70bef9ce/Stage22c70781b3bf453a8454c7f5f3a66c44",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery77959a2838044a7dab64c83d70bef9ce/Stageadf837843a774bb6bceede5daa68d495",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery77959a2838044a7dab64c83d70bef9ce/Staged777a6b66dc448ee92edcd47509ae627",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery77959a2838044a7dab64c83d70bef9ce/Stage71517ee9f935487ca066732a19d75301",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}, {
  "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2022-07-14T17:06:01.392+02:00",
  "endDate" : "2022-07-16T11:06:01.392+02:00",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Delivery433d465d43be4117a3da080fb580f868",
  "stages" : [ {
    "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage405598b2be824f78bb42626c463a0c16",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage405598b2be824f78bb42626c463a0c16/StageTrackedItemaabc5bbeac9340e0993240d4a02e33a4",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/TrackedItemffa16e6674644ee9929a894c2102b28f",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage405598b2be824f78bb42626c463a0c16/Transition832764083e7f49899d227f7647c8405b",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage405598b2be824f78bb42626c463a0c16",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Staged12a5ce807d14dae9cd99fecb9994ecf",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Staged12a5ce807d14dae9cd99fecb9994ecf/Transitiona7a18d5885de471d86cfac087091812b",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Staged12a5ce807d14dae9cd99fecb9994ecf",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage983699ce5cc9409395d2f72ebb78468b",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage983699ce5cc9409395d2f72ebb78468b/Transition528eac0ddfc947f18a91f92c6f44c95a",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage983699ce5cc9409395d2f72ebb78468b",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/Stage5a466f6a0b9b4b4793b88cba244cd673",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliveryac4136cb93ec4d8787e93a8521b0d45d/TrackedItemffa16e6674644ee9929a894c2102b28f",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2022-07-14T17:06:01.391+02:00",
    "modifiedDate" : "2022-07-14T17:06:01.391+02:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false
} ]

Get releases associated with a delivery

To get all releases associated with a delivery, send this request:

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

Using the following path parameters:

Table 142. /api/v1/deliveries/{deliveryId}/releases
Parameter Description

deliveryId

The id of the delivery

The response contains a list of associated releases info:

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

[ {
  "id" : "Releasef84348cedff44059a20a383324561452",
  "title" : "Release 1",
  "status" : "in_progress",
  "startDate" : null,
  "endDate" : null,
  "archived" : false
}, {
  "id" : "Release261aa38eed514fc0bcbf1e2a9b8ca496",
  "title" : "Release 2",
  "status" : "in_progress",
  "startDate" : null,
  "endDate" : null,
  "archived" : false
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

ID of the release

[].title

String

Title of the release

[].status

String

Status of the release

[].startDate

Number

Start date of the release

[].endDate

Number

End date of the release

[].archived

Boolean

Is release archived

Create a tracked item

To create a tracked item in a delivery, send this request:

HTTP Request
POST /api/v1/deliveries/Deliveries/Deliveryc9c3723cf679467c9acf12f2bb66093d/tracked-items

{
  "id" : "1239261726",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc9c3723cf679467c9acf12f2bb66093d/tracked-items' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "1239261726",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}'
HTTPie
$ echo '{
  "id" : "1239261726",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false
}' | http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc9c3723cf679467c9acf12f2bb66093d/tracked-items' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 143. /api/v1/deliveries/{deliveryId}/tracked-items
Parameter Description

deliveryId

The id of the delivery

The response contains the created item:

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

{
  "id" : "Deliveries/Deliveryc9c3723cf679467c9acf12f2bb66093d/TrackedItem3c0e5a2287104941bd07213b9dde045b",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:05:57.015+02:00",
  "modifiedDate" : "2022-07-14T17:05:57.015+02:00"
}

Get tracked items

To get a list of tracked items in a delivery, send this request:

HTTP Request
GET /api/v1/deliveries/Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/tracked-items
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/tracked-items' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/tracked-items' \
    'Accept:application/json'

Using the following path parameters:

Table 144. /api/v1/deliveries/{deliveryId}/tracked-items
Parameter Description

deliveryId

The id of the delivery

The response contains the list of tracked items:

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

[ {
  "id" : "Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/TrackedItem2df7fa841ff74f8eaf0c38101d92178a",
  "type" : "delivery.TrackedItem",
  "title" : "Test item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:10.925+02:00",
  "modifiedDate" : "2022-07-14T17:06:10.925+02:00"
}, {
  "id" : "Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/TrackedItemb52dae3b5ec84608b2e33475fba65f1f",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 1",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:10.981+02:00",
  "modifiedDate" : "2022-07-14T17:06:10.981+02:00"
}, {
  "id" : "Deliveries/Delivery241cf10ea46f45f18a344452fe1c4422/TrackedItembee8555401774f9da91c71f93050647b",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 2",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:11.193+02:00",
  "modifiedDate" : "2022-07-14T17:06:11.193+02:00"
} ]

Update a tracked item

To update an existing tracked item in a delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery13e454999d654588b840c714ff99b676/TrackedItemb51b372653b748a6a0685d004733d984

{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:12.105+02:00",
  "modifiedDate" : "2022-07-14T17:06:12.105+02:00"
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery13e454999d654588b840c714ff99b676/TrackedItemb51b372653b748a6a0685d004733d984' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:12.105+02:00",
  "modifiedDate" : "2022-07-14T17:06:12.105+02:00"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:12.105+02:00",
  "modifiedDate" : "2022-07-14T17:06:12.105+02:00"
}' | http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery13e454999d654588b840c714ff99b676/TrackedItemb51b372653b748a6a0685d004733d984' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 145. /api/v1/deliveries/{itemId}
Parameter Description

itemId

The full id of the tracked item

The response contains the updated tracked item:

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

{
  "id" : "Deliveries/Delivery13e454999d654588b840c714ff99b676/TrackedItemb51b372653b748a6a0685d004733d984",
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2022-07-14T17:06:12.105+02:00",
  "modifiedDate" : "2022-07-14T17:06:12.362+02:00"
}

Delete a tracked item

To delete an existing tracked item in a delivery, send this request:

HTTP Request
DELETE /api/v1/deliveries/Deliveries/Deliveryc9ee2a53d0e14d92a4515a9d185dcdbc/TrackedItem8db7886b26c04c46b426677dadc8e1e1
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc9ee2a53d0e14d92a4515a9d185dcdbc/TrackedItem8db7886b26c04c46b426677dadc8e1e1' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc9ee2a53d0e14d92a4515a9d185dcdbc/TrackedItem8db7886b26c04c46b426677dadc8e1e1' \
    'Accept:application/json'

Using the following path parameters:

Table 146. /api/v1/deliveries/{itemId}
Parameter Description

itemId

The full id of the tracked item

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

Descope a tracked item

To descope a tracked item in a delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery6ef260f9933142408f530ed31b0aa131/TrackedItem11e0d597b2a24a74abfdf2dd9703e964/descope
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery6ef260f9933142408f530ed31b0aa131/TrackedItem11e0d597b2a24a74abfdf2dd9703e964/descope' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery6ef260f9933142408f530ed31b0aa131/TrackedItem11e0d597b2a24a74abfdf2dd9703e964/descope' \
    'Accept:application/json'

Using the following path parameters:

Table 147. /api/v1/deliveries/{itemId}/descope
Parameter Description

itemId

The full id of the tracked item

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

Rescope a tracked item

To rescope a tracked item in a delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery2511e87fa20144acb7760b319391d4ef/TrackedItem46f1a6dda3f14c83871c63c3db0b34c4/rescope
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery2511e87fa20144acb7760b319391d4ef/TrackedItem46f1a6dda3f14c83871c63c3db0b34c4/rescope' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery2511e87fa20144acb7760b319391d4ef/TrackedItem46f1a6dda3f14c83871c63c3db0b34c4/rescope' \
    'Accept:application/json'

Using the following path parameters:

Table 148. /api/v1/deliveries/{itemId}/rescope
Parameter Description

itemId

The full id of the tracked item

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

Complete a tracked item

To complete a tracked item in a stage in a delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/Stageaa2713262db24a228a2675e931c041dc/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/TrackedItem03c3eb21ed604633a370d58820c1ea12/complete
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/Stageaa2713262db24a228a2675e931c041dc/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/TrackedItem03c3eb21ed604633a370d58820c1ea12/complete' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/Stageaa2713262db24a228a2675e931c041dc/Deliveries/Delivery95f500c68b3147d7af4e43b419c96cb0/TrackedItem03c3eb21ed604633a370d58820c1ea12/complete' \
    'Accept:application/json'

Using the following path parameters:

Table 149. /api/v1/deliveries/{stageId}/{itemId}/complete
Parameter Description

stageId

The full id of the stage

itemId

The id of the tracked item

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

Skip a tracked item

To skip a tracked item in a stage in a delivery, send this request:

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/Stage2eb5c38e5ce94f5fa00e5c1eb17d91c9/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/TrackedItem7cb0a9303e9a44c6b2198df8eb4681e2/skip
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/Stage2eb5c38e5ce94f5fa00e5c1eb17d91c9/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/TrackedItem7cb0a9303e9a44c6b2198df8eb4681e2/skip' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/Stage2eb5c38e5ce94f5fa00e5c1eb17d91c9/Deliveries/Delivery3b345e62daad4e7592917f30a6ee8ad9/TrackedItem7cb0a9303e9a44c6b2198df8eb4681e2/skip' \
    'Accept:application/json'

Using the following path parameters:

Table 150. /api/v1/deliveries/{stageId}/{itemId}/skip
Parameter Description

stageId

The full id of the stage

itemId

The id of the tracked item

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

Complete a stage

To complete a stage in a delivery, send this request:

HTTP Request
POST /api/v1/deliveries/Deliveries/Delivery4cb3a2112acc4e4783b08f9c618671b5/Stage9b2c8f2c8c7a420fbca48cd4a9a5e2af/complete
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery4cb3a2112acc4e4783b08f9c618671b5/Stage9b2c8f2c8c7a420fbca48cd4a9a5e2af/complete' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery4cb3a2112acc4e4783b08f9c618671b5/Stage9b2c8f2c8c7a420fbca48cd4a9a5e2af/complete' \
    'Accept:application/json'

Using the following path parameters:

Table 151. /api/v1/deliveries/{stageId}/complete
Parameter Description

stageId

The full id of the stage

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

Reopen a stage

To reopen a stage in a delivery, send this request:

HTTP Request
POST /api/v1/deliveries/Deliveries/Delivery224be68ad2064c7fa8db2cea96a1e7a1/Stageeedb3f9ad94340e7ad305ad8443bf2d9/reopen
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery224be68ad2064c7fa8db2cea96a1e7a1/Stageeedb3f9ad94340e7ad305ad8443bf2d9/reopen' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery224be68ad2064c7fa8db2cea96a1e7a1/Stageeedb3f9ad94340e7ad305ad8443bf2d9/reopen' \
    'Accept:application/json'

Using the following path parameters:

Table 152. /api/v1/deliveries/{stageId}/reopen
Parameter Description

stageId

The full id of the stage

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

Complete a transition

To complete a transition in a delivery, send this request:

HTTP Request
POST /api/v1/deliveries/Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/Stagec22f8d2b1e14472ba689cd367b07ce60/Transition15735de9b2224c47884971492d3d8495/complete

{
  "transitionItems" : [ "Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/TrackedItem8df8d2efa91c4547a1f59622faa5b061" ],
  "closeStages" : true
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/Stagec22f8d2b1e14472ba689cd367b07ce60/Transition15735de9b2224c47884971492d3d8495/complete' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "transitionItems" : [ "Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/TrackedItem8df8d2efa91c4547a1f59622faa5b061" ],
  "closeStages" : true
}'
HTTPie
$ echo '{
  "transitionItems" : [ "Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/TrackedItem8df8d2efa91c4547a1f59622faa5b061" ],
  "closeStages" : true
}' | http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery669f4f0b16c64d338817f022cba5ca39/Stagec22f8d2b1e14472ba689cd367b07ce60/Transition15735de9b2224c47884971492d3d8495/complete' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 153. /api/v1/deliveries/{transitionId}/complete
Parameter Description

transitionId

The full id of the transition

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

Activity Logs

Release Activity Logs

To get activity logs for release or template, send this request:

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

Using the following path parameters:

Table 154. /api/v1/activities/{releaseId}
Parameter Description

releaseId

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

The response contains a list of the activity log entries:

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

[ {
  "id" : "64",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "TASK_STARTED",
  "message" : "Started Task 'Configure users'",
  "eventTime" : "2022-07-14T17:04:40.034+02:00",
  "targetType" : "xlrelease.Task",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726"
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

This field contains ID of activity log.

[].type

String

This field represents type of 'xlrelease.ActivityLogEntry'.

[].username

String

The username. Blank if event is generated by SYSTEM.

[].activityType

String

The type of activity.

[].message

String

Environment description

[].eventTime

String

The time of activity.

[].targetType

String

This field represents type of target.

[].targetId

String

This field contains ID of target.

Delivery Activity Logs

To get activity logs for delivery or pattern, send this request:

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

Using the following path parameters:

Table 155. /api/v1/activities/{deliveryId}
Parameter Description

deliveryId

Full identifier of the delivery; for example, Deliveries/Delivery1

The response contains a list of the activity log entries:

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

[ {
  "id" : "83",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "DELIVERY_CREATED",
  "message" : "Created delivery 'Delivery1'",
  "eventTime" : "2022-07-14T17:04:45.249+02:00",
  "targetType" : "delivery.Delivery",
  "targetId" : "Deliveries/Delivery734bbb4f3c854a049516df1ae7983abd"
} ]

Trigger Activity Logs

To get activity logs for trigger, send this request:

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

Using the following path parameters:

Table 156. /api/v1/activities/{triggerId}
Parameter Description

triggerId

Full identifier of the trigger; for example, Applications/Trigger1

The response contains a list of the activity log entries:

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

[ {
  "id" : "77",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "TRIGGER_ADDED",
  "message" : "Added release trigger 'Simple Trigger'",
  "eventTime" : "2022-07-14T17:04:42.788+02:00",
  "targetType" : "unit.SimpleTriggerTest",
  "targetId" : "Applications/Triggera141c0a6e641454084ae761194ab6c3f"
} ]

Report

Release Report

To download a release report, send this request:

HTTP Request
GET /api/v1/reports/download/xlrelease.ReleaseAuditExcelReport/Applications/Release162151faba694d03aa3065665cf26f21
Curl
$ curl 'http://localhost:5516/api/v1/reports/download/xlrelease.ReleaseAuditExcelReport/Applications/Release162151faba694d03aa3065665cf26f21' -i -X GET \
    -H 'Accept: application/octet-stream'
HTTPie
$ http GET 'http://localhost:5516/api/v1/reports/download/xlrelease.ReleaseAuditExcelReport/Applications/Release162151faba694d03aa3065665cf26f21' \
    'Accept:application/octet-stream'

Using the following parameter:

Table 157. /api/v1/reports/download/{reportType}/{releaseId}
Parameter Description

reportType

Synthetic type of the release report; for example, xlrelease.ReleaseAuditExcelReport

releaseId

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

You will receive the release report file in the response.

Task Reporting Records

Type of records

Table 158. Task Reporting Records
Record Digital.ai Release type

Build

udm.BuildRecord

Code Compliance

udm.CodeComplianceRecord

Deployment

udm.DeploymentRecord

ITSM

udm.ItsmRecord

Plan

udm.PlanRecord
Fields in udm.BuildRecord
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 'udm.BuildRecord'.

[].targetId

String

The ID of the CI that the facet is applied to.

[].variableMapping

Object

Variable Mapping

[].serverUrl

String

Server base URL used to fetch data.

[].serverUser

String

Username used to authenticate to the server when fetching data.

[].creationDate

String

Timestamp of when this record was created.

[].project

String

The project name.

[].build

String

The ID of the build.

[].outcome

String

Result of the build.

[].startDate

String

Start date of the build.

[].endDate

String

End date of the build.

[].duration

String

Duration of the build.

[].build_url

String

Link to the job build.
Fields in udm.CodeComplianceRecord
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 'udm.CodeComplianceRecord'.

[].targetId

String

The ID of the CI that the facet is applied to.

[].variableMapping

Object

Variable Mapping

[].serverUrl

String

Server base URL used to fetch data.

[].serverUser

String

Username used to authenticate to the server when fetching data.

[].creationDate

String

Timestamp of when this record was created.

[].project

String

The project name.

[].project_url

String

URL for the project.

[].analysisDate

String

Date of the analysis.

[].outcome

String

Result of the analysis.

[].complianceData

String

The compliance data.
Fields in udm.DeploymentRecord
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 'udm.DeploymentRecord'.

[].targetId

String

The ID of the CI that the facet is applied to.

[].variableMapping

Object

Variable Mapping

[].serverUrl

String

Server base URL used to fetch data.

[].serverUser

String

Username used to authenticate to the server when fetching data.

[].creationDate

String

Timestamp of when this record was created.

[].deploymentTask

String

The deployment.

[].deploymentTask_url

String

The URL of the deployment.

[].applicationName

String

The name of the application whose version is being deployed.

[].version

String

The version of the application.

[].environmentName

String

The name of the environment where this task deploys to.

[].status

String

The status of the deployment.
Fields in udm.ItsmRecord
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 'udm.ItsmRecord'.

[].targetId

String

The ID of the CI that the facet is applied to.

[].variableMapping

Object

Variable Mapping

[].serverUrl

String

Server base URL used to fetch data.

[].serverUser

String

Username used to authenticate to the server when fetching data.

[].creationDate

String

Timestamp of when this record was created.

[].record

String

Unique identifier in ITSM.

[].record_url

String

Link to the record in ITSM.

[].title

String

Title of the record in ITSM.

[].status

String

Status of the record.

[].priority

String

Priority of the record.

[].createdBy

String

Record created by.
Fields in udm.PlanRecord
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 'udm.PlanRecord'.

[].targetId

String

The ID of the CI that the facet is applied to.

[].variableMapping

Object

Variable Mapping

[].serverUrl

String

Server base URL used to fetch data.

[].serverUser

String

Username used to authenticate to the server when fetching data.

[].creationDate

String

Timestamp of when this record was created.

[].ticket

String

Ticket ID.

[].title

String

Issue title.

[].ticketType

String

Ticket type.

[].status

String

Status of the ticket.

[].updatedDate

String

Date and time of last update.

[].updatedBy

String

Person who performed the last update.

[].ticket_url

String

Link to the ticket.

List all records

Get all records for a release

To get task reporting records for a release, send this request:

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

Using the following path parameters:

Table 159. /api/v1/reports/records/{releaseId}
Parameter Description

releaseId

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

The response contains a list of the task reporting records:

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

[ {
  "id" : "Facet9be056b4338a44d68cd11b501d1e929e",
  "type" : "udm.PlanRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task169e52908657406c9b5ae07a496c697c",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2022-07-14T17:06:40.789+02:00",
  "ticket" : "REL-6437",
  "title" : "Some issue",
  "ticketType" : "BUG",
  "status" : "Paused",
  "updatedDate" : "2022-07-14T17:06:40.706+02:00",
  "updatedBy" : "admin",
  "ticket_url" : "http://example.com/browse/REL-6437"
}, {
  "id" : "Facetfb12e50b8d2d4be397fbb1b72d76b67d",
  "type" : "udm.DeploymentRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task31a0974f90b8450c98dbeef993f53667",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2022-07-14T17:06:40.757+02:00",
  "deploymentTask" : "PR-1234",
  "deploymentTask_url" : "http://example.com",
  "applicationName" : "XL-Jetpack",
  "version" : "1.0",
  "environmentName" : "34521",
  "status" : "IN_PROGRESS"
}, {
  "id" : "Facet57b82acd70b8491c986009eaf5cdecad",
  "type" : "udm.ItsmRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Taskcecbc48333e04276b212a4091adf3928",
  "variableMapping" : { },
  "serverUrl" : "example.com",
  "serverUser" : "nobody",
  "creationDate" : "2022-07-14T17:06:40.773+02:00",
  "record" : "CN-123",
  "record_url" : "https://example.com/changes/CN-123",
  "title" : "Move definition of ITSM Facet from synthetic.xml to proper Java class with getters and setters",
  "status" : "In progress",
  "priority" : "Major",
  "createdBy" : "Toadsworth"
}, {
  "id" : "Facet104795e66a194d6da367bff5b84f2fad",
  "type" : "udm.BuildRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2022-07-14T17:06:40.724+02:00",
  "project" : "XL-RELEASE",
  "build" : "PR-1234",
  "outcome" : "SUCCESS",
  "startDate" : "2022-07-14T17:06:40.706+02:00",
  "endDate" : "2022-07-14T17:06:40.706+02:00",
  "duration" : "34521",
  "build_url" : "http://example.com"
}, {
  "id" : "Facet12eac5e5ded642439ebc04d93c69ce6d",
  "type" : "udm.CodeComplianceRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task5be4358d7e7a4282b79e6cf474375978",
  "variableMapping" : { },
  "serverUrl" : "https://example.com",
  "serverUser" : "nobody",
  "creationDate" : "2022-07-14T17:06:40.740+02:00",
  "project" : "Project",
  "project_url" : "https://example.com/project1",
  "analysisDate" : "2022-07-14T17:06:40.706+02:00",
  "outcome" : "Success",
  "complianceData" : "report"
} ]
Get all records for a task

To get task reporting records for a task, send this request:

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

Using the following path parameters:

Table 160. /api/v1/reports/records/{taskId}
Parameter Description

taskId

Full identifier of the task; for example, Applications/Folder1/Release1/Phase1/Task1

The response contains a list of the task reporting records.

Search records

To search task reporting records, send this request:

HTTP Request
POST /api/v1/reports/records/search

{
  "parentId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task31a0974f90b8450c98dbeef993f53667",
  "types" : [ ]
}
Curl
$ curl 'http://localhost:5516/api/v1/reports/records/search' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "parentId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task31a0974f90b8450c98dbeef993f53667",
  "types" : [ ]
}'
HTTPie
$ echo '{
  "parentId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task31a0974f90b8450c98dbeef993f53667",
  "types" : [ ]
}' | http POST 'http://localhost:5516/api/v1/reports/records/search' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Path Type Description

parentId

String

Full identifier of the release; for example, Applications/Folder1/Release1 (Optional if targetId specified)

targetId

String

Full identifier of the task; for example, Applications/Folder1/Release1/Phase1/Task1 (Optional if parentId specified)

types

Array

The (Optional) Task reporting record types; for example, 'udm.DeploymentRecord'

The response contains a list of the task reporting records for matching search criteria.

Plugin Manager

API for managing plugins in Digital.ai Release. User must have ADMIN permission level in order to interact with the plugin manager API.

With the API you can list installed plugins and install or upgrade integration plugins from the official Digital.ai plugin repository or custom built plugins from a local file.

This API is shared with Digital.ai Deploy.

List

Lists the plugins that are currently active in the system.

HTTP Request
GET /plugin-manager/list
Curl
$ curl 'http://localhost:5516/plugin-manager/list' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/plugin-manager/list'

A response :

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

[ {
  "hasLogo" : true,
  "metadata" : {
    "author" : "Digital.ai",
    "categories" : [ "Repository Management" ],
    "description" : "Test plugin description.",
    "features" : [ "f1", "f2" ],
    "links" : [ {
      "name" : "Website",
      "url" : "https://www.example.com/"
    }, {
      "name" : "Documentation",
      "url" : "https://docs.xebialabs.com/release/how-to/nexus-trigger.html"
    } ],
    "maturity" : "Mature",
    "name" : "Test plugin",
    "requirements" : {
      "product" : "XL Release",
      "versions" : [ "== 22.2.2" ]
    },
    "screenshots" : [ {
      "name" : "Set up a Nexus server",
      "url" : "https://docs.xebialabs.com/release/images/nexus-configuration-details.png"
    } ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins"
  },
  "status" : "READY_FOR_INSTALL",
  "versions" : [ {
    "repository" : "xlr-official",
    "version" : "10.1.0"
  } ]
} ]
Path Type Description

[].hasLogo

Boolean

Whether if plugin has logo

[].status

String

Status of plugin in system. Possible values: AVAILABLE, READY_FOR_INSTALL, INSTALLED

[].metadata.author

String

Author of the plugin

[].metadata.categories

Array

Category of the plugin

[].metadata.description

String

Plugin description

[].metadata.features

Array

List of plugin features

[].metadata.maturity

String

Plugin maturity. Possible values: Incubating, Mature, Deprecated

[].metadata.name

String

Official plugin name

[].metadata.screenshots

Array

Screenshots of the plugin

[].metadata.supportedBy

String

Plugin created and supported by

[].metadata.links[].name

String

Plugin can have usage or help (or any other kind) links associated to them. This field contains the link name

[].metadata.links[].url

String

Link URL

[].metadata.screenshots[].name

String

Plugin can have screenshots associated to them. This field contains the screenshots name

[].metadata.screenshots[].url

String

Screenshot URL

[].metadata.requirements.product

String

Digital.Ai product to which the plugin belongs

[].metadata.requirements.versions

Array

Digital.Ai product version which is required for plugin

[].plugin.artifactId

String

The name of artifact on the Nexus repository

[].plugin.groupId

String

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__)

[].versions[].repository

String

Plugin repository identifier

[].versions[].version

String

Plugin version

List repositories

Lists all Nexus repositories that are configured in the system. A repository contains the plugin artifacts that can be installed by the Plugin Manager. To interact with a repository, use the response field config.repository-id as the repository identifier in subsequent requests.

The default repository id is xlr-official

HTTP Request
GET /plugin-manager/repositories
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/plugin-manager/repositories'

A response:

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

[ {
  "config" : {
    "nexus-group-id" : "com.xebialabs.xlrelease.plugins",
    "nexus-metadata-artifact" : {
      "artifact-id" : "xlr-plugins-metadata",
      "group-id" : "com.xebialabs.xlrelease.plugins.metadata"
    },
    "nexus-packaging-type" : "jar",
    "repository-id" : "official-plugins",
    "repository-type" : "nexus-by-group-id",
    "server" : {
      "server-type" : "nexus",
      "url" : "http://localhost:35241/nexus"
    }
  },
  "lastUpdated" : 1657811050451,
  "repositoryId" : "xlr-official",
  "repositoryType" : "nexus"
} ]
Path Type Description

[].lastUpdated

Number

Timestamp of the latest download of this repository metadata

[].repositoryId

String

Repository identifier

[].repositoryType

String

Type of repository used by the plugin manager. Possible values: 'nexus', 'unknown'

[].config.nexus-group-id

String

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__)

[].config.nexus-packaging-type

String

XLR can only use repositories that have 'jar' packaging, so this will always have 'jar' value

[].config.repository-id

String

Repository identifier

[].config.repository-type

String

XLR only supports fetching repository metadata from Nexus by providing groupId and artifactId, so this field will always have 'nexus-by-group-id' value

[].config.nexus-metadata-artifact.artifact-id

String

The name of artifact on the Nexus repository

[].config.nexus-metadata-artifact.group-id

String

Group id of the metadata file

[].config.server.server-type

String

Type of repository server

[].config.server.url

String

Url of repository server

List plugins from repository

Lists all available plugins for the provided repositoryId. The result contains the metadata and installation status per plugin.

Digital.ai Release caches the metadata from the repository. To refresh the list of plugins and their metadata, call (POST /plugin-manager/repositories/{repository-id}/update).

HTTP Request
GET /plugin-manager/repositories/xlr-official/list
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories/xlr-official/list' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/plugin-manager/repositories/xlr-official/list'
Table 161. /plugin-manager/repositories/{repositoryId}/list
Parameter Description

repositoryId

The Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be __local__); for example, xlr-official

A response:

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

[ {
  "hasLogo" : true,
  "metadata" : {
    "author" : "Digital.ai",
    "categories" : [ "Repository Management" ],
    "description" : "Test plugin description.",
    "features" : [ "f1", "f2" ],
    "links" : [ {
      "name" : "Website",
      "url" : "https://www.example.com/"
    }, {
      "name" : "Documentation",
      "url" : "https://docs.xebialabs.com/release/how-to/nexus-trigger.html"
    } ],
    "maturity" : "Mature",
    "name" : "Test plugin",
    "requirements" : {
      "product" : "XL Release",
      "versions" : [ "== 22.2.2" ]
    },
    "screenshots" : [ {
      "name" : "Set up a Nexus server",
      "url" : "https://docs.xebialabs.com/release/images/nexus-configuration-details.png"
    } ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins"
  },
  "versions" : [ {
    "repository" : "xlr-official",
    "version" : "10.1.0"
  } ]
}, {
  "hasLogo" : false,
  "metadata" : {
    "author" : "Digital.ai",
    "categories" : [ "Provisioning", "Config Management" ],
    "description" : "Description.",
    "features" : [ ],
    "links" : [ {
      "name" : "Documentation",
      "url" : "https://docs.xebialabs.com/xl-release/how-to/using-the-remote-completion-plugin.html"
    } ],
    "maturity" : "Mature",
    "name" : "another test plugin",
    "requirements" : {
      "product" : "XL Release",
      "versions" : [ "== 22.2.2" ]
    },
    "screenshots" : [ ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "another-test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins"
  },
  "versions" : [ {
    "repository" : "xlr-official",
    "version" : "10.1.0"
  } ]
} ]
Path Type Description

[].hasLogo

Boolean

Whether if plugin has logo

[].metadata.author

String

Author of the plugin

[].metadata.categories

Array

Category of the plugin

[].metadata.description

String

Plugin description

[].metadata.features

Array

List of plugin features

[].metadata.maturity

String

Plugin maturity. Possible values: Incubating, Mature, Deprecated

[].metadata.name

String

Official plugin name

[].metadata.screenshots

Array

Screenshots of the plugin

[].metadata.supportedBy

String

Plugin created and supported by

[].metadata.links[].name

String

Plugin can have usage or help (or any other kind) links associated to them. This field contains the link name

[].metadata.links[].url

String

Link URL

[].metadata.screenshots[].name

String

Plugin can have screenshots associated to them. This field contains the screenshots name

[].metadata.screenshots[].url

String

Screenshot URL

[].metadata.requirements.product

String

Digital.Ai product to which the plugin belongs

[].metadata.requirements.versions

Array

Digital.Ai product version which is required for plugin

[].plugin.artifactId

String

The name of artifact on the Nexus repository

[].plugin.groupId

String

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__)

[].versions[].repository

String

Plugin repository identifier

[].versions[].version

String

Plugin version

Install from repository

Downloads a plugin from a repository and installs it into Digital.ai Release.

The plugin will be first in READY_FOR_INSTALL status, and a system restart is needed for the installation to be completed. While the plugin is in READY_FOR_INSTALL it can still be deleted. Once the plugin is active, deletion is not permitted.

HTTP Request
POST /plugin-manager/repositories/xlr-official/install/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories/xlr-official/install/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0' -i -X POST \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1'
HTTPie
$ http POST 'http://localhost:5516/plugin-manager/repositories/xlr-official/install/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'

A response:

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

{
  "message" : "Installation of another-test-plugin succeeded"
}
Path Type Description

message

String

Human readable description of what happened

Update from repository

The endpoint can be used to update the plugin with a newer version. All that’s needed is to pass the repositoryId, groupId and artifactId. The version that the plugin will be updated to is the one that the product supports. This version can not be altered via API.

HTTP Request
POST /plugin-manager/repositories/xlr-official/update/com.xebialabs.xlrelease.plugins/another-test-plugin
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories/xlr-official/update/com.xebialabs.xlrelease.plugins/another-test-plugin' -i -X POST \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1'
HTTPie
$ http POST 'http://localhost:5516/plugin-manager/repositories/xlr-official/update/com.xebialabs.xlrelease.plugins/another-test-plugin' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'

A response:

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

{
  "message" : "Installed plugin already at highest version. Update will not be performed."
}
Path Type Description

message

String

Human readable description of what happened

Install local plugin

Installs a plugin by uploading the plugin binary.

The plugin will be first in READY_FOR_INSTALL status, and a system restart is needed for the installation to be completed. While the plugin is in READY_FOR_INSTALL it can still be deleted. Once the plugin is active, deletion is not permitted.

This endpoint can’t be used for updating the plugin, please use update endpoint for that.

Parameter Description

pluginId

Plugin filename; for example, xlr-git-plugin-9.2.0.jar
HTTP Request
POST /plugin-manager/install?pluginId=test-plugin-name.jar

--boundary
 Content-Disposition: form-data; name="file"; filename="test-plugin-name.jar"
Content-Type: multipart/form-data

bytes
--boundary--
Curl
$ curl 'http://localhost:5516/plugin-manager/install?pluginId=test-plugin-name.jar' -i -X POST \
    -H 'Content-Type: multipart/form-data; boundary=boundary' \
    -H 'Accept: application/json' \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1' \
    -d '--boundary
 Content-Disposition: form-data; name="file"; filename="test-plugin-name.jar"
Content-Type: multipart/form-data

bytes
--boundary--'
HTTPie
$ echo '--boundary
 Content-Disposition: form-data; name="file"; filename="test-plugin-name.jar"
Content-Type: multipart/form-data

bytes
--boundary--' | http POST 'http://localhost:5516/plugin-manager/install?pluginId=test-plugin-name.jar' \
    'Content-Type:multipart/form-data; boundary=boundary' \
    'Accept:application/json' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'

A response:

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

{
  "message" : "Installation of test-plugin-name succeeded"
}
Path Type Description

message

String

Human readable description of what happened

Update local plugin

The plugin can be updated by uploading a new file. There are no restrictions with regard to versions. This means this endpoint can be used for plugin upgrades and downgrades.

Parameter Description

existingPluginName

Plugin name, e.g. xlr-git-plugin

newPluginId

Plugin filename, e.g. xlr-git-plugin-9.2.0.jar
HTTP Request
POST /plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar

--boundary
 Content-Disposition: form-data; name="file"; filename="another-test-plugin.jar"
Content-Type: multipart/form-data

bytes
--boundary--
Curl
$ curl 'http://localhost:5516/plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar' -i -X POST \
    -H 'Content-Type: multipart/form-data; boundary=boundary' \
    -H 'Accept: application/json' \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1' \
    -d '--boundary
 Content-Disposition: form-data; name="file"; filename="another-test-plugin.jar"
Content-Type: multipart/form-data

bytes
--boundary--'
HTTPie
$ echo '--boundary
 Content-Disposition: form-data; name="file"; filename="another-test-plugin.jar"
Content-Type: multipart/form-data

bytes
--boundary--' | http POST 'http://localhost:5516/plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar' \
    'Content-Type:multipart/form-data; boundary=boundary' \
    'Accept:application/json' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'

A response:

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

{
  "message" : "Update of plugin another-test-plugin succeeded"
}
Path Type Description

message

String

Human readable description of what happened

Uninstall

Cancels pending installation of a plugin. Plugin installation requires a restart of the system to be completed. The uninstall API call can be made on plugins in the READY_FOR_INSTALL status (which is the state of plugin after the install API call but before system restart).

Note: once a plugin is in INSTALLED state it can not be deleted anymore.

HTTP Request
DELETE /plugin-manager/delete/xlr-official/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0
Curl
$ curl 'http://localhost:5516/plugin-manager/delete/xlr-official/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0' -i -X DELETE \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1'
HTTPie
$ http DELETE 'http://localhost:5516/plugin-manager/delete/xlr-official/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'
Table 162. /plugin-manager/delete/{repositoryId}/{groupId}/{artifactId}/{version}
Parameter Description

repositoryId

The Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be __local__); for example, xlr-official

groupId

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__); for example, com.xebialabs.xlrelease.plugins

artifactId

The name of artifact on the Nexus repository; for example, xlr-plugin

version

The version of the artifact for which installation will be cancelled; for example, 10.1.0

A response:

HTTP/1.1 200 OK
Content-Language: en

Update repository:

Updates cached list of available official plugins in the system for a given repository by downloading the metadata from the Nexus repository.

Sometimes plugins are updated and released to Nexus so it is good to periodically do this API call in order to update the cached list of plugins in the system.

HTTP Request
POST /plugin-manager/repositories/xlr-official/update
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories/xlr-official/update' -i -X POST \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1'
HTTPie
$ http POST 'http://localhost:5516/plugin-manager/repositories/xlr-official/update' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'

A response:

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

{
  "lastDownloaded" : "07-14-2022 05:04:11 CEST"
}
Path Type Description

lastDownloaded

String

Timestamp of the last metadata download from Nexus. Not to be confused with the timestamp the metadata was last updated on Nexus.

Gets the plugin logo.

HTTP Request
GET /plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin
Curl
$ curl 'http://localhost:5516/plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin'
Table 163. /plugin-manager/repositories/{repositoryId}/logo/{groupId}/{artifactId}
Parameter Description

repositoryId

The Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be __local__); for example, xlr-official

groupId

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__); for example, com.xebialabs.xlrelease.plugins

artifactId

The name of artifact on the Nexus repository; for example, xlr-plugin

A response is the plugin logo.

The search is performed amongst all available plugins regardless of their installation status. It’s performed against the plugin id, which is a string in the following format:

repository-id:groupId:artifactId-version.extension

For example, suppose the following plugins are in Digital.ai Release:

  1. xlr-official:com.xebialabs.xlrelease.plugins:xlr-ansible-plugin-10.3.0.jar

  2. xlr-official:com.xebialabs.xlrelease.plugins:xlr-blackduck-plugin-10.3.0.jar

  3. local:local:my-local-plugin.jar

Search criteria Results

xlr-official

1, 2

ansible

1

xlr

1, 2

.jar

1, 2, 3

plugins:xlr

1, 2
HTTP Request
GET /plugin-manager/search/test
Curl
$ curl 'http://localhost:5516/plugin-manager/search/test' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/plugin-manager/search/test'
Table 164. /plugin-manager/search/{query}
Parameter Description

query

Query string
Path Type Description

[].hasLogo

Boolean

Whether if plugin has logo

[].metadata.author

String

Author of the plugin

[].metadata.categories

Array

Category of the plugin

[].metadata.description

String

Plugin description

[].metadata.features

Array

List of plugin features

[].metadata.maturity

String

Plugin maturity. Possible values: Incubating, Mature, Deprecated

[].metadata.name

String

Official plugin name

[].metadata.screenshots

Array

Screenshots of the plugin

[].metadata.supportedBy

String

Plugin created and supported by

[].metadata.links[].name

String

Plugin can have usage or help (or any other kind) links associated to them. This field contains the link name

[].metadata.links[].url

String

Link URL

[].metadata.screenshots[].name

String

Plugin can have screenshots associated to them. This field contains the screenshots name

[].metadata.screenshots[].url

String

Screenshot URL

[].metadata.requirements.product

String

Digital.Ai product to which the plugin belongs

[].metadata.requirements.versions

Array

Digital.Ai product version which is required for plugin

[].plugin.artifactId

String

The name of artifact on the Nexus repository

[].plugin.groupId

String

The coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be __local__)

[].versions[].repository

String

Plugin repository identifier

[].versions[].version

String

Plugin version