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

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

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:38:56.219+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:38:56.219+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:02.988+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:02.988+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Find me",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
} ]

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,
  "templateId" : null,
  "orderDirection" : "ASC",
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderDirection" : "ASC",
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderDirection" : "ASC",
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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

kind

String

Matches the releases with the WORKFLOW or RELEASE kind; default value is RELEASE

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:11.338+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:11.338+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Find me",
  "scheduledStartDate" : "2024-11-18T07:39:11.324+01:00",
  "dueDate" : "2024-11-18T07:39:11.324+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:39:11.324+01:00",
  "queryableEndDate" : "2024-11-18T07:39:11.324+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ "foo", "bar" ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
} ]

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,
  "templateId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderBy" : "end_date",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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

kind

String

Matches the releases with the WORKFLOW or RELEASE kind; default value is RELEASE

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

{
  "live" : {
    "page" : 0,
    "size" : 3,
    "releases" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
      "type" : "xlrelease.Release",
      "$createdBy" : "admin",
      "$createdAt" : "2024-11-18T06:39:11.688+0000",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2024-11-18T06:39:11.688+0000",
      "$scmTraceabilityDataId" : "0",
      "title" : "Planned Release",
      "scheduledStartDate" : "2024-11-18T07:39:11.677+01:00",
      "dueDate" : "2024-11-18T15:39:11.677+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2024-11-18T07:39:11.677+01:00",
      "queryableEndDate" : "2024-11-18T15:39:11.677+01:00",
      "realFlagStatus" : "OK",
      "status" : "PLANNED",
      "kind" : "RELEASE",
      "tags" : [ "foo", "bar" ],
      "categories" : [ ],
      "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",
      "allowTargetFolderOverride" : true,
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
      "type" : "xlrelease.Release",
      "$createdBy" : "admin",
      "$createdAt" : "2024-11-18T06:39:11.847+0000",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2024-11-18T06:39:11.847+0000",
      "$scmTraceabilityDataId" : "0",
      "title" : "Running Release",
      "dueDate" : "2024-11-18T15:34:11.678+01:00",
      "startDate" : "2024-11-18T07:34:11.678+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2024-11-18T07:34:11.678+01:00",
      "queryableEndDate" : "2024-11-18T15:34:11.678+01:00",
      "realFlagStatus" : "OK",
      "status" : "IN_PROGRESS",
      "kind" : "RELEASE",
      "tags" : [ "bar" ],
      "categories" : [ ],
      "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",
      "allowTargetFolderOverride" : true,
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Release9303b354aba041eea4e2486ed81f80c2",
      "type" : "xlrelease.Release",
      "$createdBy" : "admin",
      "$createdAt" : "2024-11-18T06:39:11.970+0000",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2024-11-18T06:39:11.970+0000",
      "$scmTraceabilityDataId" : "0",
      "title" : "Failed Release",
      "dueDate" : "2024-11-18T15:29:11.678+01:00",
      "startDate" : "2024-11-18T07:29:11.678+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2024-11-18T07:29:11.678+01:00",
      "queryableEndDate" : "2024-11-18T15:29:11.678+01:00",
      "realFlagStatus" : "OK",
      "status" : "FAILED",
      "kind" : "RELEASE",
      "tags" : [ "foo" ],
      "categories" : [ ],
      "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",
      "allowTargetFolderOverride" : true,
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    } ]
  },
  "archived" : {
    "page" : 0,
    "size" : 2,
    "releases" : [ {
      "id" : "Applications/Release4c0a37c875694c97b30fa971fc1ee03c",
      "type" : "xlrelease.Release",
      "$createdBy" : "admin",
      "$createdAt" : "2024-11-18T06:39:12.092+0000",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2024-11-18T06:39:12.092+0000",
      "$scmTraceabilityDataId" : "0",
      "title" : "Completed Release",
      "startDate" : "2024-11-17T23:39:11.678+01:00",
      "endDate" : "2024-11-18T07:39:11.678+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2024-11-17T23:39:11.678+01:00",
      "queryableEndDate" : "2024-11-18T07:39:11.678+01:00",
      "realFlagStatus" : "OK",
      "status" : "COMPLETED",
      "kind" : "RELEASE",
      "tags" : [ "bar" ],
      "categories" : [ ],
      "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",
      "allowTargetFolderOverride" : true,
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    }, {
      "id" : "Applications/Release18a1237a6df6409b941ab62a245141cc",
      "type" : "xlrelease.Release",
      "$createdBy" : "admin",
      "$createdAt" : "2024-11-18T06:39:12.283+0000",
      "$lastModifiedBy" : "admin",
      "$lastModifiedAt" : "2024-11-18T06:39:12.283+0000",
      "$scmTraceabilityDataId" : "0",
      "title" : "Aborted Release",
      "startDate" : "2024-11-17T22:39:11.678+01:00",
      "endDate" : "2024-11-18T06:39:11.678+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "maxConcurrentReleases" : 100,
      "releaseTriggers" : [ ],
      "teams" : [ ],
      "memberViewers" : [ ],
      "roleViewers" : [ ],
      "attachments" : [ ],
      "phases" : [ ],
      "queryableStartDate" : "2024-11-17T22:39:11.678+01:00",
      "queryableEndDate" : "2024-11-18T06:39:11.678+01:00",
      "realFlagStatus" : "OK",
      "status" : "ABORTED",
      "kind" : "RELEASE",
      "tags" : [ "foo" ],
      "categories" : [ ],
      "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",
      "allowTargetFolderOverride" : true,
      "riskScore" : "000",
      "totalRiskScore" : "0000"
    } ]
  }
}

Search releases overview by criteria

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

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

{
  "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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/search/overview?page=0&resultsPerPage=100' -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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : null
}' | http POST 'http://localhost:5516/api/v1/releases/search/overview?page=0&resultsPerPage=100' \
    '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

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

kind

String

Matches the releases with the WORKFLOW or RELEASE kind; default value is RELEASE

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 results matching the criteria:

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Find me",
  "startDate" : 1731911940368,
  "endDate" : 1731911940368,
  "archived" : false,
  "status" : "PLANNED",
  "kind" : "RELEASE"
} ]

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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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

kind

String

Matches the releases with the WORKFLOW or RELEASE kind; default value is RELEASE

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,
      "FAILED" : 1,
      "ABORTED" : 1,
      "IN_PROGRESS" : 1,
      "PLANNED" : 1
    }
  }
}

Find phase by ID

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

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

Using the following parameters:

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

phaseId

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

The response contains the phase as JSON:

HTTP/1.1 200 OK
Content-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: 1121

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:20.684+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "lastStatusChangeBy" : "admin",
  "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: 1005

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "find me",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:14.423+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "lastStatusChangeBy" : "admin",
  "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
Curl
$ curl 'http://localhost:5516/api/v1/releases?page=0&resultsPerPage=2' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases?page=0&resultsPerPage=2' \
    '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

The response contains a page of planned or active releases sorted in ascending order by start date and title:

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:10.798+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:10.798+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
}, {
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:10.952+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:10.952+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
} ]

Listing templates

To list a page of release templates send this request:

HTTP Request
GET /api/v1/templates?title=Test%20template&tag=tag1&kind=RELEASE&page=0&resultsPerPage=2
Curl
$ curl 'http://localhost:5516/api/v1/templates?title=Test%20template&tag=tag1&kind=RELEASE&page=0&resultsPerPage=2' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates?title=Test%20template&tag=tag1&kind=RELEASE&page=0&resultsPerPage=2' \
    '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

title

Title of the release

tag

Tag of the release

kind

The (optional) kind of the template; for example, WORKFLOW or RELEASE; default value is RELEASE

The response contains a page of release templates sorted in ascending order by title:

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:00.934+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:00.934+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Test template 1",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ "tag1", "tag2", "tag3" ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
}, {
  "id" : "Applications/Releasecaa6882c22ff46b89abf7140359df88a",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:01.120+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:01.120+0000",
  "$scmTraceabilityDataId" : "0",
  "title" : "Test template 2",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ "tag1", "tag2" ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { }
  }
} ]

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

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Release630982075c744002a45618a0f9e0eb20",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T07:38:54.149+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:54.149+0100",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2024-11-18T07:38:54.094+01:00",
  "dueDate" : "2024-11-18T15:38:54.094+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "rootReleaseId" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:54.094+01:00",
  "queryableEndDate" : "2024-11-18T15:38:54.094+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarLinkToken" : "-3724749205719465833",
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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" : { }
  }
}

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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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

{
  "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releasef6dedfdbe04d43db87554c78a4af20a0",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T07:38:59.867+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:59.867+0100",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2024-11-18T07:38:59.843+01:00",
  "dueDate" : "2024-11-18T15:38:59.843+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:59.843+01:00",
  "queryableEndDate" : "2024-11-18T15:38:59.843+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releasef6dedfdbe04d43db87554c78a4af20a0/Variableb0acb38e43b2450fb2ae7e6ba1a4b966",
    "type" : "xlrelease.StringVariable",
    "key" : "stringVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "providedValue",
    "multiline" : false,
    "preventInterpolation" : false
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releasef6dedfdbe04d43db87554c78a4af20a0/Variable825dbf6c73ae4fe4a56d9dfb3d524e77",
    "type" : "xlrelease.PasswordStringVariable",
    "key" : "passwordVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : "********",
    "multiline" : false
  }, {
    "id" : "Applications/Folder16471301a63401435604e56d1303c451/Releasef6dedfdbe04d43db87554c78a4af20a0/Variable45729e32f7704affb2f2df3b5bc275d2",
    "type" : "xlrelease.ListStringVariable",
    "key" : "listVar",
    "requiresValue" : true,
    "showOnReleaseStart" : true,
    "inherited" : false,
    "value" : [ "a", "b" ]
  } ],
  "calendarLinkToken" : "212148294624953094",
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder16471301a63401435604e56d1303c451/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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" : { }
  }
}

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "startDate" : "2024-11-18T07:39:10.033+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "lastStatusChangeBy" : "admin",
  "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: 1068

{
  "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",
  "lastStatusChangeBy" : "admin",
  "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: 1439

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment41f70d1347bc4aa59faa8eaecb4aa982",
    "type" : "xlrelease.Comment",
    "text" : "Important step in our pipeline",
    "author" : "admin",
    "date" : "2024-11-18T07:39:24.968+01:00",
    "creationDate" : "2024-11-18T07:39:24.968+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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: 1565

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:18.019+01:00",
  "endDate" : "2024-11-18T07:39:18.217+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment802dbd0afead452c9a92744773806f1b",
    "type" : "xlrelease.Comment",
    "text" : "Task completed!",
    "author" : "admin",
    "date" : "2024-11-18T07:39:18.225+01:00",
    "creationDate" : "2024-11-18T07:39:18.225+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "COMPLETED",
  "lastStatusChangeBy" : "admin",
  "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: 1479

{
  "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/Comment9b11818981fc41548f589ce9f428d66a",
    "type" : "xlrelease.Comment",
    "text" : "Reopen a task that has been completed in advance.",
    "author" : "admin",
    "date" : "2024-11-18T07:39:22.223+01:00",
    "creationDate" : "2024-11-18T07:39:22.223+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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: 1493

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:21.620+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment97df1c96a0734fa6a084e24e892c79cd",
    "type" : "xlrelease.Comment",
    "text" : "Task failed :-(",
    "author" : "admin",
    "date" : "2024-11-18T07:39:21.811+01:00",
    "creationDate" : "2024-11-18T07:39:21.811+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "FAILED",
  "lastStatusChangeBy" : "admin",
  "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: 1501

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:16.340+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment11c6feda055a426991e81e4559760621",
    "type" : "xlrelease.Comment",
    "text" : "Retry failed task.",
    "author" : "admin",
    "date" : "2024-11-18T07:39:16.346+01:00",
    "creationDate" : "2024-11-18T07:39:16.346+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "lastStatusChangeBy" : "admin",
  "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: 1560

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:25.146+01:00",
  "endDate" : "2024-11-18T07:39:25.355+01:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Comment2f72f5f450fb490abe64140f297103bb",
    "type" : "xlrelease.Comment",
    "text" : "Task skipped",
    "author" : "admin",
    "date" : "2024-11-18T07:39:25.361+01:00",
    "creationDate" : "2024-11-18T07:39:25.361+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "SKIPPED",
  "lastStatusChangeBy" : "admin",
  "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

Abort a task

To abort a task, send this request:

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

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

Using the following parameters:

Table 17. /api/v1/tasks/{taskId}/abort
Parameter Description

taskId

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

comment

String

The comment to associate with abort

The response contains the aborted task and the added comment:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.ScriptTask",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "owner" : "admin",
  "startDate" : "2024-11-18T07:39:15.240+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/Commenta442dc0d37e24261ac80a249308c4acf",
    "type" : "xlrelease.Comment",
    "text" : "Script aborted by user. Reason: 'Please abort this task'",
    "author" : "admin",
    "date" : "2024-11-18T07:39:15.462+01:00",
    "creationDate" : "2024-11-18T07:39:15.462+01:00"
  } ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "FAILED",
  "lastStatusChangeBy" : "admin",
  "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,
  "ignoreScriptVariableInterpolation" : false,
  "script" : "print(\"${foo}\")"
}

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 18. /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: 1074

{
  "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",
  "lastStatusChangeBy" : "admin",
  "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 19. /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: 1563

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:00.924+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:39:01.166+0100",
  "$scmTraceabilityDataId" : "0",
  "title" : "Running release, don't abort me",
  "endDate" : "2024-11-18T07:39:01.149+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableEndDate" : "2024-11-18T07:39:01.149+01:00",
  "realFlagStatus" : "OK",
  "status" : "ABORTED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "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 20. /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: 4878

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:38:59.240+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:59.816+0100",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2024-11-18T07:38:59.675+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "endDate" : "2024-11-18T07:38:59.222+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "lastStatusChangeBy" : "admin",
      "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" : "2024-11-18T07:38:59.678+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2024-11-18T07:38:59.715+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase53228aef3564406aa3933efb0f6dfe26",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "lastStatusChangeBy" : "admin",
      "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" : "2024-11-18T07:38:59.675+01:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "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' \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form 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 21. /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: 5569

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:04.201+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:39:04.639+0100",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "startDate" : "2024-11-18T07:39:04.620+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
    "startDate" : "2024-11-18T07:39:04.508+01:00",
    "endDate" : "2024-11-18T07:39:04.508+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2024-11-18T07:39:04.184+01:00",
      "endDate" : "2024-11-18T07:39:04.509+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "SKIPPED",
      "lastStatusChangeBy" : "admin",
      "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/Phase0d9bc65be1b14e3881b2cc8deb60b361",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (1)",
    "startDate" : "2024-11-18T07:39:04.620+01:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase0d9bc65be1b14e3881b2cc8deb60b361/Task97c27091a9b342599e1b631dc6d44726",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
      "startDate" : "2024-11-18T07:39:04.622+01:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase0d9bc65be1b14e3881b2cc8deb60b361",
      "facets" : [ ],
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "lastStatusChangeBy" : "admin",
      "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" : "2024-11-18T07:39:04.620+01:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/progress",
    "type" : "xlrelease.ReleaseProgress",
    "totalTasks" : 2,
    "totalRemainingTasks" : 1,
    "phasesProgress" : {
      "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e" : "1;1",
      "Applications/Release162151faba694d03aa3065665cf26f21/Phase0d9bc65be1b14e3881b2cc8deb60b361" : "1;0"
    }
  } ],
  "autoStart" : false,
  "automatedResumeCount" : 1,
  "variableMapping" : { },
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "serverUrl" : { },
    "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" : "2024-11-18T07:38:55.448+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.448+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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" : "2024-11-18T07:38:55.448+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.448+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2024-11-18T07:38:55.448+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.448+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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

{
  "id" : "Applications/Folder01345a690c16b345168751d62934e912/Releasec45117edf75d44758fd082b4e5f40e46",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T07:38:55.609+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:55.609+0100",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2024-11-18T07:38:55.448+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teamd0ae8c6b85014e4b9cfb3b057eb7cadb",
    "type" : "xlrelease.Team",
    "teamName" : "Release Admin",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "release#edit_precondition", "release#edit", "workflow#view_execution", "release#advance_task_transition", "workflow#abort_execution", "release#edit_security", "release#restart_phase", "release#lock_task", "folder#view", "release#edit_task_script", "release#edit_task_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "workflow#start_execution", "release#edit_task", "release#edit_task_attachments", "release#task_transition", "trigger#view_trigger", "release#reassign_task", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "release#edit_task_description", "trigger#edit_trigger", "release#view", "release#edit_blackout", "release#start", "release#edit_failure_handler", "release#abort" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Teamaf0a6985b422439a8e63600f69f07e1a",
    "type" : "xlrelease.Team",
    "teamName" : "Folder Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "folder#edit_variables", "delivery_pattern#edit", "folder#edit_configuration", "app_pipelines#view", "delivery#edit", "folder#view_security", "folder#view_versions", "folder#apply_changes", "group#view", "folder#edit_versions", "folder#edit_notifications", "app_pipelines#edit", "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" ]
  }, {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Team54a05bd637ba441097586ca4ab5dbfe3",
    "type" : "xlrelease.Team",
    "teamName" : "Template Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "template#edit", "trigger#view_trigger", "app_pipelines#view", "template#edit_security", "template#create_release", "template#create_release_other_folder", "template#lock_task", "template#view", "folder#view", "template#edit_triggers", "template#edit_precondition", "template#edit_failure_handler" ]
  } ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Folder01345a690c16b345168751d62934e912/Releasec45117edf75d44758fd082b4e5f40e46/Phase34258c44fa9e4e1e9dfcaae9afd1bfbc",
    "type" : "xlrelease.Phase",
    "title" : "New Phase",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ ],
    "release" : "Applications/Folder01345a690c16b345168751d62934e912/Releasec45117edf75d44758fd082b4e5f40e46",
    "status" : "PLANNED"
  } ],
  "queryableStartDate" : "2024-11-18T07:38:55.448+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "folderVariables" : {
      "id" : "Applications/Folder01345a690c16b345168751d62934e912/variables",
      "type" : "xlrelease.FolderVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ "release#edit_precondition", "release#edit", "template#edit", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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" : { }
  }
}

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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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 22. /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: 1505

{
  "id" : "Applications/Releasee41555e9e6c0442fadf0293cd04bb514",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T07:38:57.071+0100",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:57.071+0100",
  "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",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "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 23. /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/Phase35043bbae3d3450aaec58079b6678cd5",
  "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' \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/phases/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/copy?targetPosition=1' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase076f3e30031b41d8bf2d322ce546a1a3",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ {
    "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase076f3e30031b41d8bf2d322ce546a1a3/Task97c27091a9b342599e1b631dc6d44726",
    "type" : "xlrelease.GateTask",
    "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "comments" : [ ],
    "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase076f3e30031b41d8bf2d322ce546a1a3",
    "facets" : [ ],
    "attachments" : [ ],
    "status" : "PLANNED",
    "lastStatusChangeBy" : "admin",
    "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 25. /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 26. /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: 960

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task68eb818bbc9348dc81f904132264dd02",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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",
  "lastStatusChangeBy" : "admin",
  "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",
  "lastStatusChangeBy" : "admin",
  "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",
  "lastStatusChangeBy" : "admin",
  "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 27. /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: 960

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task8af5552dda3a4a8b89a98b60577aad84",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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 container

You can copy a task to a specific position in a container. The destination can be in the same container as the origin task or in a different container.

Permissions Required

Users must have adequate permissions to copy tasks in both the source and destination locations if the destination is different from the source.

Copying Limitations

Certain restrictions apply when copying tasks:

  • Locked Tasks: Locked tasks cannot be copied. To proceed, unlock the task in the source location.

  • Task Status: Tasks with the following final statuses cannot be copied—completed, skipped, or aborted. However, failed tasks can be copied, and their status is set to Planned in the destination.

  • Excluded Information: The following details are not copied, and no comments are added to the copied task:

    • User, system, and log messages.

    • Attachments - when a task is copied between releases.

  • A task cannot be copied to a position before an active or done task in a container. Additionally, tasks cannot be copied into an in-progress parallel group.

  • A comment is added to the copied task if additional attention is required for the copied task.

Information Not Copied with Comments Added

When copying tasks between releases, the following task information—if found in a task—is not copied, but relevant details are included in the task comment at the destination:

  • Connections: If connection references in the source task are unavailable in the destination, they are cleared. A task comment indicates this change.

  • Variables:

    • Folder variables are only copied if the destination folder contains variables that match in title and type.

    • If a variable in the source task has the same name but a different type in the destination, it will not be copied. A comment indicates this.

    • Value provider variables must be configured in the destination. A message to configure the value provider is included in the task comment.

  • Teams: If a team from the source task does not exist in the destination, it will not be copied, and a comment is added to the task.

Note: No comments are added if you copy a task to within the same release.

Information Created in the Destination

In some cases, new information will be created in the destination, and a comment is added to the task.

If a task uses release variables, such as those for User input or Create release tasks, these variables are created in the destination if they do not already exist. Details are added to the task comment accordingly.

Usage example:

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 \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/copy/?targetContainerId=Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e&targetPosition=1'

Using the following path parameters:

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Taskbbe4154bc4e94f53b6ee7e0f5df66da6",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726 (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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 29. /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: 1014

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "type" : "xlrelease.Task",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T06:39:18.642+0000",
  "title" : "new title",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e",
  "facets" : [ ],
  "attachments" : [ ],
  "status" : "PLANNED",
  "lastStatusChangeBy" : "admin",
  "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 30. /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: 1097

{
  "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",
  "lastStatusChangeBy" : "admin",
  "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 31. /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/GateCondition37b22ededb5b478cad3499f5c5dd05ae",
  "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 32. /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 33. /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 34. /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/Dependency74289e6ea9fc4ff9867f3df1fa90be80",
  "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 35. /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 36. /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

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=fileOne; filename=testFile2.xml
Content-Type: application/xml

<test><content>test content</content></test>
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=fileOne; filename=testFile2.xml
Content-Type: application/xml

<test><content>test content</content></test>
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'fileOne=@testFile2.xml;type=application/xml' \
    -F 'fileOne=@testFile2.xml;type=application/xml'
HTTPie
$ http --multipart POST 'http://localhost:5516/api/v1/tasks/Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726/attachments' \
    'fileOne'@'testFile2.xml' \
    'fileOne'@'testFile2.xml'

Using the following parameter:

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Attachment397f843e29be4774995434985d03c7dd",
  "type" : "xlrelease.Attachment",
  "contentType" : "application/xml",
  "exportFilename" : "attachments/Attachment397f843e29be4774995434985d03c7dd-testFile2.xml",
  "portableFilename" : "attachments/testFile2.xml",
  "fileUri" : "sql:Applications%2FRelease162151faba694d03aa3065665cf26f21%2FAttachment397f843e29be4774995434985d03c7dd"
} ]

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

Using the following parameters:

Table 38. /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" : "2024-11-18T07:38:55.021+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.021+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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" : "2024-11-18T07:38:55.021+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.021+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2024-11-18T07:38:55.021+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.021+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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 39. /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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:38:54.813+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:38:55.093+0100",
  "$scmTraceabilityDataId" : "0",
  "title" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "scheduledStartDate" : "2024-11-18T07:38:55.021+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:38:55.021+01:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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" : "2024-11-18T07:39:06.081+01:00",
  "dueDate" : "2024-11-18T07:39:06.081+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:39:06.081+01:00",
  "queryableEndDate" : "2024-11-18T07:39:06.081+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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" : "2024-11-18T07:39:06.081+01:00",
  "dueDate" : "2024-11-18T07:39:06.081+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:39:06.081+01:00",
  "queryableEndDate" : "2024-11-18T07:39:06.081+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null,
    "folderVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2024-11-18T07:39:06.081+01:00",
  "dueDate" : "2024-11-18T07:39:06.081+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:39:06.081+01:00",
  "queryableEndDate" : "2024-11-18T07:39:06.081+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "archiveRelease" : true,
  "allowPasswordsInAllFields" : false,
  "disableNotifications" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "variableMapping" : { },
  "allowTargetFolderOverride" : true,
  "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 40. /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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21",
  "type" : "xlrelease.Release",
  "$createdBy" : "admin",
  "$createdAt" : "2024-11-18T06:39:05.920+0000",
  "$lastModifiedBy" : "admin",
  "$lastModifiedAt" : "2024-11-18T07:39:06.130+0100",
  "$scmTraceabilityDataId" : "0",
  "title" : "new title",
  "scheduledStartDate" : "2024-11-18T07:39:06.081+01:00",
  "dueDate" : "2024-11-18T07:39:06.081+01:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2024-11-18T07:39:06.081+01:00",
  "queryableEndDate" : "2024-11-18T07:39:06.081+01:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "kind" : "RELEASE",
  "tags" : [ ],
  "categories" : [ ],
  "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",
  "allowTargetFolderOverride" : true,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "serverUrl" : { },
    "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.

kind

String

The kind of a template.

tags

Array

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

categories

Array

The categories for the release.

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

parentReleaseId

String

ID of the Release 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

author

String

The author of the template

logo

Varies

The logo of the template

defaultTargetFolderId

String

Default folder where release should be created. Can be overridden if 'allowTargetFolderOverride' flag is true.

allowTargetFolderOverride

Boolean

Flag that controls if default target folder can be overridden.

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 41. /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 42. /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 43. /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 44. /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/Release5b84e1a6b3924630a5e9d19a95a4b675
Curl
$ curl 'http://localhost:5516/api/v1/templates/zip/Applications/Release5b84e1a6b3924630a5e9d19a95a4b675' -i -X GET \
    -H 'Accept: */*'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/zip/Applications/Release5b84e1a6b3924630a5e9d19a95a4b675' \
    '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=1
Curl
$ curl 'http://localhost:5516/api/v1/folders/list?depth=1' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/list?depth=1' \
    '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

You receive a response containing a list of folders:

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

[ {
  "id" : "Applications/Folderd9f80cf61e8543809d467a6eda150ed0",
  "type" : "xlrelease.Folder",
  "$token" : "ff47e7d0-d2aa-43bc-bc37-46b2c48a7273",
  "title" : "Microservices",
  "children" : [ ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "folder#view", "folder#edit" ],
      "teams" : [ ]
    }
  }
} ]

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

Using the following parameters:

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

Using the following parameters:

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

folderId

The id of the folder
Parameter Description

kind

The (optional) kind of the template; for example, WORKFLOW or RELEASE; default value is RELEASE

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/Folder28cd98450be04eb4afc606262b205510/Folder144d54726e624f9e833ff08cf8f58053/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,
  "templateId" : null,
  "orderBy" : "risk",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder28cd98450be04eb4afc606262b205510/Folder144d54726e624f9e833ff08cf8f58053/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,
  "templateId" : null,
  "orderBy" : "risk",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : 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,
  "templateId" : null,
  "orderBy" : "risk",
  "orderDirection" : null,
  "riskStatusWithThresholds" : null,
  "kind" : "RELEASE",
  "categories" : null
}' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder28cd98450be04eb4afc606262b205510/Folder144d54726e624f9e833ff08cf8f58053/releases' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

kind

String

Matches the releases with the WORKFLOW or RELEASE kind; default value is RELEASE

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

Using the following parameters:

Table 49. /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/Folderbd5b676a86d04f398f6b582129a7b9e2

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

Using the following parameters:

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

Using the following parameters:

Table 51. /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/Folder7e222264f40243829c293aabe5b7122c/move?newParentId=Applications/Folder8d788c147fc84546b0d547543502293a
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder7e222264f40243829c293aabe5b7122c/move?newParentId=Applications/Folder8d788c147fc84546b0d547543502293a' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/folders/Applications/Folder7e222264f40243829c293aabe5b7122c/move?newParentId=Applications/Folder8d788c147fc84546b0d547543502293a' \
    'Accept:application/json'

Using the following parameters:

Table 52. /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 any running or scheduled releases

  • the folder or any of its children contain any triggers

  • it contains any releases that reference connections not available under new parent folder

Rename folders

To rename a folder, send this request:

HTTP Request
POST /api/v1/folders/Applications/Folderdf5b91ed345244109fcb9832a5fef822/rename?newName=Microservices%20II
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderdf5b91ed345244109fcb9832a5fef822/rename?newName=Microservices%20II' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/folders/Applications/Folderdf5b91ed345244109fcb9832a5fef822/rename?newName=Microservices%20II' \
    'Accept:application/json'

Using the following parameters:

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

folderId

The id of the folder to move
Parameter Description

newName

The new name of the folder

Teams

Get a team by ID

To get the principals, roles and permissions for a team using the team ID, send this request:

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

Using the following parameters:

Table 54. /api/v1/folders/{folderId}/{teamId}
Parameter Description

folderId

The parent folder to retrieve from

teamId

The team to retrieve

Search for a team by name

To get the principals, roles and permissions for a team using the team name, send this request:

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

Using the following parameters:

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

folderId

The parent folder to retrieve from

teamName

The team name to search for

Create a team

To create a team in a folder, send this request:

HTTP Request
POST /api/v1/folders/Applications/Folderb7cb9b85b4b349b0af412afb99509b04/create-team

{
  "name" : "QA",
  "principals" : [ "QaUser" ],
  "roles" : [ "QaRole" ],
  "permissions" : [ "template#view" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderb7cb9b85b4b349b0af412afb99509b04/create-team' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "QA",
  "principals" : [ "QaUser" ],
  "roles" : [ "QaRole" ],
  "permissions" : [ "template#view" ]
}'
HTTPie
$ echo '{
  "name" : "QA",
  "principals" : [ "QaUser" ],
  "roles" : [ "QaRole" ],
  "permissions" : [ "template#view" ]
}' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folderb7cb9b85b4b349b0af412afb99509b04/create-team' \
    'Content-Type:application/json'

Using the following parameters:

Table 56. /api/v1/folders/{folderId}/create-team
Parameter Description

folderId

The id of the folder
Path Type Description

name

String

Name of the team

principals

Array

Names of users that are members of the team.

roles

Array

Names of roles that are members of the team team.

permissions

Array

Names of the team permissions.

Note that the create team API will create a new team or add the specified principals, roles or permissions to an existing team with the same name in the folder.

Update a team by name

Add principals to the team

To add principals to a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder7ad3e2838f22496e82b844f8f62851a1/teams/QA/add-principals

[ "QaUser 1", "QaUser 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder7ad3e2838f22496e82b844f8f62851a1/teams/QA/add-principals' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaUser 1", "QaUser 2" ]'
HTTPie
$ echo '[ "QaUser 1", "QaUser 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder7ad3e2838f22496e82b844f8f62851a1/teams/QA/add-principals' \
    'Content-Type:application/json'

Using the following parameters:

Table 57. /api/v1/folders/{folderId}/teams/{teamName}/add-principals
Parameter Description

folderId

The id of the folder

teamName

The name of the team to modify
Add roles to the team

To add roles to a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder71dc6001a0f54379b3ca566db3b5b3e6/teams/QA/add-roles

[ "QaRole 1", "QaRole 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder71dc6001a0f54379b3ca566db3b5b3e6/teams/QA/add-roles' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaRole 1", "QaRole 2" ]'
HTTPie
$ echo '[ "QaRole 1", "QaRole 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder71dc6001a0f54379b3ca566db3b5b3e6/teams/QA/add-roles' \
    'Content-Type:application/json'

Using the following parameters:

Table 58. /api/v1/folders/{folderId}/teams/{teamName}/add-roles
Parameter Description

folderId

The id of the folder

teamName

The name of the team to modify
Add permissions to the team

To add permissions to a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folderb18f166285fb45e2bbae0a2b3671e726/teams/QA/add-permissions

[ "template#view", "release#view" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderb18f166285fb45e2bbae0a2b3671e726/teams/QA/add-permissions' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "template#view", "release#view" ]'
HTTPie
$ echo '[ "template#view", "release#view" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folderb18f166285fb45e2bbae0a2b3671e726/teams/QA/add-permissions' \
    'Content-Type:application/json'

Using the following parameters:

Table 59. /api/v1/folders/{folderId}/teams/{teamName}/add-permissions
Parameter Description

folderId

The id of the folder

teamName

The name of the team to modify
Remove principals from the team

To remove principals from a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Foldera10c7944d40148e0b35d550393db42c5/teams/QA/remove-principals

[ "QaUser 1", "QaUser 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Foldera10c7944d40148e0b35d550393db42c5/teams/QA/remove-principals' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaUser 1", "QaUser 2" ]'
HTTPie
$ echo '[ "QaUser 1", "QaUser 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Foldera10c7944d40148e0b35d550393db42c5/teams/QA/remove-principals' \
    'Content-Type:application/json'

Using the following parameters:

Table 60. /api/v1/folders/{folderId}/teams/{teamName}/remove-principals
Parameter Description

folderId

The id of the folder

teamName

The name of the team modify
Remove roles from the team

To remove roles from a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder34fe0fd034ae4b23ac230ec6d8392f04/teams/QA/remove-roles

[ "QaRole 1", "QaRole 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder34fe0fd034ae4b23ac230ec6d8392f04/teams/QA/remove-roles' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaRole 1", "QaRole 2" ]'
HTTPie
$ echo '[ "QaRole 1", "QaRole 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder34fe0fd034ae4b23ac230ec6d8392f04/teams/QA/remove-roles' \
    'Content-Type:application/json'

Using the following parameters:

Table 61. /api/v1/folders/{folderId}/teams/{teamName}/remove-roles
Parameter Description

folderId

The id of the folder

teamName

The name of the team to modify
Remove permissions from the team

To remove permissions from a team using the team name, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder1f6cddbb6fd7460b8e1b5e553fc4fe26/teams/QA/remove-permissions

[ "template#view", "release#view" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder1f6cddbb6fd7460b8e1b5e553fc4fe26/teams/QA/remove-permissions' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "template#view", "release#view" ]'
HTTPie
$ echo '[ "template#view", "release#view" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder1f6cddbb6fd7460b8e1b5e553fc4fe26/teams/QA/remove-permissions' \
    'Content-Type:application/json'

Using the following parameters:

Table 62. /api/v1/folders/{folderId}/teams/{teamName}/remove-permissions
Parameter Description

folderId

The id of the folder

teamName

The name of the team to modify

Update a team by ID

Add principals to the team

To add principals to a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder945bd2e00b704e348aaea2bd4a37aa60/Team1ee7b68483e141748ddf63cae5f56ad1/add-principals

[ "QaUser 1", "QaUser 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder945bd2e00b704e348aaea2bd4a37aa60/Team1ee7b68483e141748ddf63cae5f56ad1/add-principals' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaUser 1", "QaUser 2" ]'
HTTPie
$ echo '[ "QaUser 1", "QaUser 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder945bd2e00b704e348aaea2bd4a37aa60/Team1ee7b68483e141748ddf63cae5f56ad1/add-principals' \
    'Content-Type:application/json'

Using the following parameters:

Table 63. /api/v1/folders/{folderId}/{teamId}/add-principals
Parameter Description

folderId

The id of the folder

teamId

The id of the team modify
Add roles to the team

To add roles to a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folderfeb494f65739486bb0d16044d1a06e8e/Team95d35e2778f14140ab91aea432ab9243/add-roles

[ "QaRole 1", "QaRole 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderfeb494f65739486bb0d16044d1a06e8e/Team95d35e2778f14140ab91aea432ab9243/add-roles' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaRole 1", "QaRole 2" ]'
HTTPie
$ echo '[ "QaRole 1", "QaRole 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folderfeb494f65739486bb0d16044d1a06e8e/Team95d35e2778f14140ab91aea432ab9243/add-roles' \
    'Content-Type:application/json'

Using the following parameters:

Table 64. /api/v1/folders/{folderId}/{teamId}/add-roles
Parameter Description

folderId

The id of the folder

teamId

The id of the team to modify
Add permissions to the team

To add permissions to a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder34a5e6d220664d53bc0ec9c49c4ca04b/Team166c5a16c27444beb7538947fba4400d/add-permissions

[ "template#view", "release#view" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder34a5e6d220664d53bc0ec9c49c4ca04b/Team166c5a16c27444beb7538947fba4400d/add-permissions' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "template#view", "release#view" ]'
HTTPie
$ echo '[ "template#view", "release#view" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder34a5e6d220664d53bc0ec9c49c4ca04b/Team166c5a16c27444beb7538947fba4400d/add-permissions' \
    'Content-Type:application/json'

Using the following parameters:

Table 65. /api/v1/folders/{folderId}/{teamId}/add-permissions
Parameter Description

folderId

The id of the folder

teamId

The id of the team to modify
Remove principals from the team

To remove principals from a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder25066519f7244ab1a0a25a1a24d88e18/Team1b423da2a8154f10b79fa93a94253c25/remove-principals

[ "QaUser 1", "QaUser 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder25066519f7244ab1a0a25a1a24d88e18/Team1b423da2a8154f10b79fa93a94253c25/remove-principals' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaUser 1", "QaUser 2" ]'
HTTPie
$ echo '[ "QaUser 1", "QaUser 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder25066519f7244ab1a0a25a1a24d88e18/Team1b423da2a8154f10b79fa93a94253c25/remove-principals' \
    'Content-Type:application/json'

Using the following parameters:

Table 66. /api/v1/folders/{folderId}/{teamId}/remove-principals
Parameter Description

folderId

The id of the folder

teamId

The id of the team modify
Remove roles from the team

To remove roles from a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder318f6bc9b83b46c187d868c7d8f6d2dd/Teamb7ad9d51d9a34317aac7cd69bbca4406/remove-roles

[ "QaRole 1", "QaRole 2" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder318f6bc9b83b46c187d868c7d8f6d2dd/Teamb7ad9d51d9a34317aac7cd69bbca4406/remove-roles' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "QaRole 1", "QaRole 2" ]'
HTTPie
$ echo '[ "QaRole 1", "QaRole 2" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folder318f6bc9b83b46c187d868c7d8f6d2dd/Teamb7ad9d51d9a34317aac7cd69bbca4406/remove-roles' \
    'Content-Type:application/json'

Using the following parameters:

Table 67. /api/v1/folders/{folderId}/{teamId}/remove-roles
Parameter Description

folderId

The id of the folder

teamId

The id of the team to modify
Remove permissions from the team

To remove permissions from a team using the team ID, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folderaccfd5955bd04ccb874e25d2798a1c9a/Teame0af6927ab364fe8a59fa635b58e6d44/remove-permissions

[ "template#view", "release#view" ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderaccfd5955bd04ccb874e25d2798a1c9a/Teame0af6927ab364fe8a59fa635b58e6d44/remove-permissions' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[ "template#view", "release#view" ]'
HTTPie
$ echo '[ "template#view", "release#view" ]' | http PUT 'http://localhost:5516/api/v1/folders/Applications/Folderaccfd5955bd04ccb874e25d2798a1c9a/Teame0af6927ab364fe8a59fa635b58e6d44/remove-permissions' \
    'Content-Type:application/json'

Using the following parameters:

Table 68. /api/v1/folders/{folderId}/{teamId}/remove-permissions
Parameter Description

folderId

The id of the folder

teamId

The id of the team to modify

Delete a team by ID

Delete a team using the team ID, send this request:

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

Using the following parameters:

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

folderId

The id of the folder

teamId

The id of the team to delete

Delete a team by name

Delete a team using the team name, send this request:

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

Using the following parameters:

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

folderId

The id of the folder

teamName

The name of the team to delete

Working with variables

For a detailed description about variables, refer to Variables in Digital.ai Release

Types of variables

Table 71. 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 72. /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: 328

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

[].preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

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 73. /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 74. /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

preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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 75. /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 76. /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,
  "preventInterpolation" : 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,
  "preventInterpolation" : false
}'
HTTPie
$ echo '{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false,
  "preventInterpolation" : false
}' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b' \
    'Content-Type:application/json'

Using the following path parameters:

Table 77. /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,
  "preventInterpolation" : 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,
  "preventInterpolation" : false
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false,
  "preventInterpolation" : false
} ]' | http PUT 'http://localhost:5516/api/v1/releases/Applications/Release162151faba694d03aa3065665cf26f21/variables' \
    'Content-Type:application/json'

Using the following path parameters:

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

[ {
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Variable4d6814d312344aa68a36974e714bac0b",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false,
  "preventInterpolation" : 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 79. /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 80. /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 81. /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 82. /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: 329

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

[].preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

Updating the variables of a UserInput task

You can update the variables values from a UserInput task using the following request:

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

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

In order to call this API you will need release edit permission or having the task assigned to the same user doing the request. You can’t update variables that don’t belong to this task. You can’t add nor remove variables with this api.

The response will contain all the variables that the task has:

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

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

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

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

[].preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

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 83. /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: 279

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false,
  "preventInterpolation" : 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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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,
  "referencedType" : null,
  "inherited" : false,
  "preventInterpolation" : 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: 316

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

Using the following path parameters:

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

preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

The response contains the updated global variable:

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

{
  "id" : "Configuration/variables/global/Variable1",
  "type" : "xlrelease.StringVariable",
  "key" : "global.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "updated value",
  "multiline" : false,
  "preventInterpolation" : 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 85. /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/Folder731f3c8d60454c6f9b66f7991e81dcde/Folderd9e6419f84494245a5cd68040dcc85c9/variables?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder731f3c8d60454c6f9b66f7991e81dcde/Folderd9e6419f84494245a5cd68040dcc85c9/variables?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder731f3c8d60454c6f9b66f7991e81dcde/Folderd9e6419f84494245a5cd68040dcc85c9/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: 752

[ {
  "id" : "Variabledbe0d18936ee4e56804314584b1effbb",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder731f3c8d60454c6f9b66f7991e81dcde",
  "key" : "folder.var1",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "value",
  "multiline" : false,
  "preventInterpolation" : false
}, {
  "id" : "Variablebad520905250468c969c72e59110976a",
  "type" : "xlrelease.StringVariable",
  "folderId" : "Applications/Folder731f3c8d60454c6f9b66f7991e81dcde/Folderd9e6419f84494245a5cd68040dcc85c9",
  "key" : "folder.var2",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "inherited" : false,
  "value" : "${folder.var1}",
  "multiline" : false,
  "preventInterpolation" : 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

[].preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

List folder variable values

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

HTTP Request
GET /api/v1/folders/Applications/Foldera9b070aeef5a4d14bf6f88e529a7c579/Folder612828c958454d3ea4b4c9fab4f070e2/variableValues?folderOnly=false
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Foldera9b070aeef5a4d14bf6f88e529a7c579/Folder612828c958454d3ea4b4c9fab4f070e2/variableValues?folderOnly=false' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Foldera9b070aeef5a4d14bf6f88e529a7c579/Folder612828c958454d3ea4b4c9fab4f070e2/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/Folder7470492c4ec34dc1b5c2fbca79457d11/Variable1292a7aea18d4587bdd99cec34ce56cd
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder7470492c4ec34dc1b5c2fbca79457d11/Variable1292a7aea18d4587bdd99cec34ce56cd' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder7470492c4ec34dc1b5c2fbca79457d11/Variable1292a7aea18d4587bdd99cec34ce56cd' \
    'Accept:application/json'

Using the following path parameters:

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

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

Create folder variable

To add new folder variable, send this request:

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

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

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

Update folder variable

To update a folder variable, send this request:

HTTP Request
PUT /api/v1/folders/Applications/Folder3630adca1288431a9c9df06f6d050949/Variable246aa83a48114d208607c39c434ae4f3

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

Using the following path parameters:

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

preventInterpolation

Boolean

Set this to true if you don’t want the contents of this variable scanned for other variables and updated after the variables are resolved.

The response contains the updated folder variable:

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

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

Delete folder variable

To delete a folder variable, send this request

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

Using the following path parameters:

Table 88. /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/Folder7466a738a095432c8f793b17807c20cf&folderOnly=true
Curl
$ curl 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server&folderId=Applications/Folder7466a738a095432c8f793b17807c20cf&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/Folder7466a738a095432c8f793b17807c20cf&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/Configuration3dc6da0e035a441f84891a422a99bc2a",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder7466a738a095432c8f793b17807c20cf",
  "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/Configuration61ca35cb8b08474eb00c0774a075a8a0
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration61ca35cb8b08474eb00c0774a075a8a0' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/Configuration/Custom/Configuration61ca35cb8b08474eb00c0774a075a8a0' \
    'Accept:application/json'

Using the following parameters:

Table 89. /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/Configuration61ca35cb8b08474eb00c0774a075a8a0",
  "type" : "jira.Server",
  "folderId" : "Applications/Folder8fe843e5a6a14e459c088f1bbdd73f83",
  "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/Folderfcca8d92b88942b896541c88bb907114",
  "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/Folderfcca8d92b88942b896541c88bb907114",
  "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/Folderfcca8d92b88942b896541c88bb907114",
  "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/Configuration92451fda83144069a69a98e8682a5caa",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderfcca8d92b88942b896541c88bb907114",
  "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/Configurationdb2bd21e1fb149be9df0cc830efcce39

{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb342ef9481d24cd2b8c8fd073834988a",
  "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/Configurationdb2bd21e1fb149be9df0cc830efcce39' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Configuration1",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb342ef9481d24cd2b8c8fd073834988a",
  "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/Folderb342ef9481d24cd2b8c8fd073834988a",
  "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/Configurationdb2bd21e1fb149be9df0cc830efcce39' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

Table 90. /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/Configurationdb2bd21e1fb149be9df0cc830efcce39",
  "type" : "jira.Server",
  "folderId" : "Applications/Folderb342ef9481d24cd2b8c8fd073834988a",
  "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/Configurationd6681773c4004e19bf16355e8cec72fc
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationd6681773c4004e19bf16355e8cec72fc' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/config/Configuration/Custom/Configurationd6681773c4004e19bf16355e8cec72fc' \
    'Accept:application/json'

Using the following parameters:

Table 91. /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 92. /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 93. /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: 1125

// Exported from:        http://172.18.45.151:0/#/templates/Release162151faba694d03aa3065665cf26f21/code
// Release version:      24.4.0-SNAPSHOT
// Date created:         Mon Nov 18 07:38:28 CET 2024

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

[ {
  "username" : "admin",
  "external" : false,
  "profileId" : "admin",
  "email" : "",
  "fullName" : "Release Administrator",
  "externalId" : null,
  "loginAllowed" : true,
  "dateFormat" : null,
  "timeFormat" : null,
  "firstDayOfWeek" : 0,
  "lastActive" : null,
  "analyticsEnabled" : true,
  "taskDrawerEnabled" : true,
  "personalAccessTokenEnabled" : false
}, {
  "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,
  "taskDrawerEnabled" : true,
  "personalAccessTokenEnabled" : false
} ]

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.

external

should filter only external users.

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

[].taskDrawerEnabled

Boolean

The profile settings for opt-out from new task drawer details

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 94. /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 95. /api/v1/users/{username}
Parameter Description

username

The username from the user to be created.

User preferences

Table 96. 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 97. /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: 358

{
  "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,
  "taskDrawerEnabled" : true,
  "personalAccessTokenEnabled" : false
}
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 98. /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 99. /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: 384

[ "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", "runner#registration" ]

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

[ {
  "name" : "Developers",
  "id" : "148a66a2-37da-4e0f-9ede-dcb840e09a20",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}, {
  "name" : "Operations",
  "id" : "cb9e4b11-2058-4adf-8da7-9b5845ee9b54",
  "permissions" : [ "release#create" ],
  "principals" : [ {
    "username" : "mdavis",
    "fullname" : null
  } ]
} ]

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 100. /api/v1/roles/{roleName}
Parameter Description

roleName

Name of the role

which returns:

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

{
  "name" : "Developers",
  "id" : "c69ec0e9-58e3-4be9-ac10-31fd14c70d41",
  "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 101. /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

This API does not support partial updates. You must include all the existing and new principals in the principals[] array to update them together. If you just add the new principals then the existing ones will get deleted. 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 102. /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

This API does not support partial updates. You must include all the existing and new principals in the principals[] array to update them together. If you just add the new principals then the existing ones will get deleted. 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 \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/roles/Developers/rename?newName=New%20Developers'

with the following path parameters:

Table 103. /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 104. /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: 1117

[ "folder#view", "folder#edit", "folder#view_security", "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/Folder2f689f969ee74567af074d88c694070e/teams
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder2f689f969ee74567af074d88c694070e/teams' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder2f689f969ee74567af074d88c694070e/teams' \
    'Accept:application/json'
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json
Content-Length: 2498

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

See the following table for applicable path parameters:

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

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

See the following table for applicable path parameters:

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

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

See the following table for applicable path parameters:

Table 107. /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/Foldera90c3ed7608043658d9ec9297bb865e0/teams

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

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

See the following table for applicable path parameters:

Table 108. /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/Release44713a207a1d4402a4b009b7244d15e4/teams

[ {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Team9f33b1d8578d448ebd199d1f8bd0d900",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team8d0863f356de4375aae442ae5e31a7e0",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team56c2de886a17494c9ab360552451e9cf",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Teamd03f29d7a8d345928f348a53796c9ee0",
  "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/Release44713a207a1d4402a4b009b7244d15e4/teams' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '[ {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Team9f33b1d8578d448ebd199d1f8bd0d900",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team8d0863f356de4375aae442ae5e31a7e0",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team56c2de886a17494c9ab360552451e9cf",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Teamd03f29d7a8d345928f348a53796c9ee0",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Team9f33b1d8578d448ebd199d1f8bd0d900",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team8d0863f356de4375aae442ae5e31a7e0",
  "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/Release44713a207a1d4402a4b009b7244d15e4/Team56c2de886a17494c9ab360552451e9cf",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Teamd03f29d7a8d345928f348a53796c9ee0",
  "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/Release44713a207a1d4402a4b009b7244d15e4/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/Release44713a207a1d4402a4b009b7244d15e4/Team8d0863f356de4375aae442ae5e31a7e0",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "trigger#view_trigger", "trigger#edit_trigger", "template#view", "release#view", "release#task_transition", "release#start", "release#restart_phase", "release#reassign_task", "release#lock_task", "release#edit_task_tags", "release#edit_task_script", "release#edit_task_input_output_properties", "release#edit_task_flag", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_configuration_facet", "release#edit_task_attachments", "release#edit_task", "release#edit_security", "release#edit_precondition", "release#edit_failure_handler", "release#edit_blackout", "release#edit", "release#advance_task_transition", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Teamd03f29d7a8d345928f348a53796c9ee0",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Team56c2de886a17494c9ab360552451e9cf",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release44713a207a1d4402a4b009b7244d15e4/Team9f33b1d8578d448ebd199d1f8bd0d900",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#view", "template#lock_task", "template#edit_triggers", "template#edit_security", "template#edit_precondition", "template#edit_failure_handler", "template#edit", "template#create_release_other_folder", "template#create_release" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

Table 109. /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/Release30103a52577846c68f730b552d0a0156/teams

[ {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team7aa1629e49af49d6b60d28b1b8a3bf4e",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team3a7e9e08699d47fca6b7f9761930328c",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Teame1b1733ba6ae40a6912578add0a87f39",
  "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/Release30103a52577846c68f730b552d0a0156/Team0f84f48d039443789baef89e735d8662",
  "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
} ]
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release30103a52577846c68f730b552d0a0156/teams' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '[ {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team7aa1629e49af49d6b60d28b1b8a3bf4e",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team3a7e9e08699d47fca6b7f9761930328c",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Teame1b1733ba6ae40a6912578add0a87f39",
  "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/Release30103a52577846c68f730b552d0a0156/Team0f84f48d039443789baef89e735d8662",
  "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
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team7aa1629e49af49d6b60d28b1b8a3bf4e",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team3a7e9e08699d47fca6b7f9761930328c",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Teame1b1733ba6ae40a6912578add0a87f39",
  "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/Release30103a52577846c68f730b552d0a0156/Team0f84f48d039443789baef89e735d8662",
  "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
} ]' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release30103a52577846c68f730b552d0a0156/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/Release30103a52577846c68f730b552d0a0156/Teame1b1733ba6ae40a6912578add0a87f39",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "Release Administrator",
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "template#view", "template#lock_task", "template#edit_triggers", "template#edit_security", "template#edit_precondition", "template#edit_failure_handler", "template#edit", "template#create_release_other_folder", "template#create_release" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team3a7e9e08699d47fca6b7f9761930328c",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team0f84f48d039443789baef89e735d8662",
  "teamName" : "Release Admin",
  "members" : [ ],
  "permissions" : [ "trigger#view_trigger", "trigger#edit_trigger", "template#view", "release#view", "release#task_transition", "release#start", "release#restart_phase", "release#reassign_task", "release#lock_task", "release#edit_task_tags", "release#edit_task_script", "release#edit_task_input_output_properties", "release#edit_task_flag", "release#edit_task_description", "release#edit_task_dates", "release#edit_task_configuration_facet", "release#edit_task_attachments", "release#edit_task", "release#edit_security", "release#edit_precondition", "release#edit_failure_handler", "release#edit_blackout", "release#edit", "release#advance_task_transition", "release#abort" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Release30103a52577846c68f730b552d0a0156/Team7aa1629e49af49d6b60d28b1b8a3bf4e",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  }, {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL",
    "roleId" : null
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

Table 110. /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 111. /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: 6797

{
  "id" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
  "type" : "xlrelease.Risk",
  "score" : 90,
  "totalScore" : 170,
  "riskAssessments" : [ {
    "id" : "600936163",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailedRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 90,
    "headline" : "Release has failed",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21 has failed" ]
  }, {
    "id" : "1057222808",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/MoreThanOneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1912867188",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor5Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "15996395",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessorMoreThan5Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "458667516",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAttentionNeededRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "729894819",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2040310798",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1499968923",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailingRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2008023582",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAtRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1450030876",
    "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" : "1242402051",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseDueDateRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 30,
    "headline" : "Release is overdue",
    "messages" : [ "Applications/Release162151faba694d03aa3065665cf26f21 is overdue since 2024-11-18T07:38:54.651" ]
  }, {
    "id" : "773989044",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor3Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1509254556",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1654389993",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/OneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1155006508",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor4Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "2068888961",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "167509746",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "876226448",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor2Retries",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "812095579",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "1319470947",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagAtRiskRiskAssessor",
    "risk" : "Applications/Release162151faba694d03aa3065665cf26f21/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "419429419",
    "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/RiskProfilefc4b842f5a9244cb9fdbd17df2393fc8",
  "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 112. 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/RiskProfile08db46fb586f4cc483dbb0792e94d09c",
  "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/RiskProfileef151947b1ed416eaaa17c29958fb84c",
  "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/RiskProfile8079f652a0e144b8b40f271a1322d084
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile8079f652a0e144b8b40f271a1322d084' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile8079f652a0e144b8b40f271a1322d084' \
    'Accept:application/json'

Using the following path parameters:

Table 113. /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/RiskProfile8079f652a0e144b8b40f271a1322d084",
  "type" : "xlrelease.RiskProfile",
  "title" : "Risk Profile 1",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20"
  }
}

Update risk profile

To update a risk profile, send this request:

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

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

Using the following path parameters:

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

Using the following path parameters:

Table 115. /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 116. /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/RiskProfile9608b97425394844bf03f49df107293c",
  "type" : "xlrelease.RiskProfile",
  "title" : "Default risk profile (1)",
  "defaultProfile" : false,
  "riskProfileAssessors" : {
    "xlrelease.TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor" : "75",
    "xlrelease.MoreThanOneTaskOverDueRiskAssessor" : "35",
    "xlrelease.TaskWithOneFlagNeedsAttentionRiskAssessor" : "10",
    "xlrelease.TaskRetriesRiskAssessor2Retries" : "60",
    "xlrelease.TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor" : "40",
    "xlrelease.ReleaseFlaggedAtRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailingRiskAssessor" : "70",
    "xlrelease.OneTaskOverDueRiskAssessor" : "25",
    "xlrelease.TaskWithTwoOrThreeFlagsAtRiskRiskAssessor" : "70",
    "xlrelease.TaskWithOneFlagAtRiskRiskAssessor" : "65",
    "xlrelease.TaskRetriesRiskAssessor5Retries" : "90",
    "xlrelease.TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor" : "30",
    "xlrelease.TaskWithMoreThanSixFlagsAtRiskRiskAssessor" : "80",
    "xlrelease.ReleaseStatusFailedRiskAssessor" : "90",
    "xlrelease.ReleaseFlaggedAttentionNeededRiskAssessor" : "30",
    "xlrelease.TaskRetriesRiskAssessor" : "50",
    "xlrelease.TaskRetriesRiskAssessor4Retries" : "80",
    "xlrelease.TaskRetriesRiskAssessorMoreThan5Retries" : "100",
    "xlrelease.ReleaseDueDateRiskAssessor" : "30",
    "xlrelease.TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor" : "20",
    "xlrelease.TaskRetriesRiskAssessor3Retries" : "70"
  }
}

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

{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage4a6edbdb3be14a82b6f4e0d98eee1b2d",
  "labelIds" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/environments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage4a6edbdb3be14a82b6f4e0d98eee1b2d",
  "labelIds" : null
}'
HTTPie
$ echo '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New environment",
  "description" : "Environment description",
  "stageId" : "Configuration/environmentManagement/EnvironmentStage4a6edbdb3be14a82b6f4e0d98eee1b2d",
  "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: 383

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

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/Environment7bc4a82ea55e41a8acdb378dda1e897c",
  "title" : "Environment1",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStagedf665efea79d483c9391819175f9b1c6",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel1e10cf6cde9c4879bd6b90eec08f3865",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Update an environment

To update an existing environment, send this request:

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

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

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/Environment724346ea232841d2bdc8c634959f4b0e",
  "title" : "New environment title",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "description" : "New description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage40e43e0fd92546c3aecb0ae6d411c82d",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabelb434bcd835984c76a2d27e1eb80414e4",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ]
}

Delete an environment

To delete an existing environment, send this request:

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

Using the following path parameters:

Table 119. /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",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stage" : "DEV",
  "labels" : [ "AWS" ],
  "scope" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/search' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Env",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stage" : "DEV",
  "labels" : [ "AWS" ],
  "scope" : null
}'
HTTPie
$ echo '{
  "title" : "Env",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stage" : "DEV",
  "labels" : [ "AWS" ],
  "scope" : null
}' | 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: 535

[ {
  "id" : "Configuration/environmentManagement/Environment1359f6bd13e543eb9cd4aa1c5b2a6857",
  "title" : "Environment1",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage63110f95c20046aba15b8185d76808bb",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabelba37c39564a243d59d0d5884da128fd1",
    "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/Environment8b008d46fd174640934c52a409b59f15/reservations
Curl
$ curl 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environment8b008d46fd174640934c52a409b59f15/reservations' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/Configuration/environmentManagement/Environment8b008d46fd174640934c52a409b59f15/reservations' \
    'Accept:application/json'

Using the following path parameters:

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

[ {
  "id" : "Configuration/environmentManagement/EnvironmentReservationefbe42c466344c5e8b695f6802071aec",
  "startDate" : 1731911912647,
  "endDate" : 1731919112672,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/Environment8b008d46fd174640934c52a409b59f15",
    "title" : "Environment3",
    "folderId" : null,
    "description" : null,
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage5215b26a8f144959a61073451dec255c",
      "title" : "DEV"
    },
    "labels" : [ ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application9a8a809d1e0f4b948502169df4415284",
    "title" : "APP1",
    "folderId" : null
  } ]
} ]

Get deployable applications for environment

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

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

Using the following path parameters:

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

[ {
  "id" : "Configuration/environmentManagement/Applicationa62806642fb24321974e8916a233bdde",
  "title" : "APP2",
  "folderId" : "Folder01345a690c16b345168751d62934e912"
}, {
  "id" : "Configuration/environmentManagement/Applicationaa1afd0965704e2a94144425df7e926b",
  "title" : "APP1",
  "folderId" : "Folder01345a690c16b345168751d62934e912"
} ]

Environment reservations

Create a new environment reservation

To create a new environment reservation, send this request:

HTTP Request
POST /api/v1/environments/reservations

{
  "startDate" : 1731911926004,
  "endDate" : 1731919126004,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/605969530",
  "applicationIds" : [ "Configuration/environmentManagement/Application8a4d3890280644ce802ef1bfe772db20" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "startDate" : 1731911926004,
  "endDate" : 1731919126004,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/605969530",
  "applicationIds" : [ "Configuration/environmentManagement/Application8a4d3890280644ce802ef1bfe772db20" ]
}'
HTTPie
$ echo '{
  "startDate" : 1731911926004,
  "endDate" : 1731919126004,
  "note" : "Note",
  "environmentId" : "Configuration/environmentManagement/605969530",
  "applicationIds" : [ "Configuration/environmentManagement/Application8a4d3890280644ce802ef1bfe772db20" ]
}' | 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: 861

{
  "id" : "Configuration/environmentManagement/EnvironmentReservationf879d05f17df4e95b6a08e545b28f257",
  "startDate" : 1731911926004,
  "endDate" : 1731919126004,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/605969530",
    "title" : "Environment1",
    "folderId" : null,
    "description" : "Environment1 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage7145a1dca649486aae139856ccb03982",
      "title" : "DEV"
    },
    "labels" : [ {
      "id" : "Configuration/environmentManagement/EnvironmentLabel7364b555139b4034ab880b01250c7f95",
      "title" : "AWS",
      "color" : "#ff00ff"
    } ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application8a4d3890280644ce802ef1bfe772db20",
    "title" : "APP1",
    "folderId" : null
  } ]
}

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/EnvironmentReservationd93b8ad41f694222a02f74a6aff388f6
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationd93b8ad41f694222a02f74a6aff388f6' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservationd93b8ad41f694222a02f74a6aff388f6' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentReservationd93b8ad41f694222a02f74a6aff388f6",
  "startDate" : 1731911927997,
  "endDate" : 1731915527997,
  "note" : "Note",
  "environment" : {
    "id" : "Configuration/environmentManagement/429860169",
    "title" : "Environment1",
    "folderId" : null,
    "description" : "Environment1 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage8b17610784bc4b71b5476c029b56c45d",
      "title" : "DEV"
    },
    "labels" : [ {
      "id" : "Configuration/environmentManagement/EnvironmentLabel227641af99c04d6bbab0e390946b793d",
      "title" : "AWS",
      "color" : "#ff00ff"
    } ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application8c4836aaf424451d8afb577b17734f5a",
    "title" : "APP1",
    "folderId" : null
  } ]
}

Update an environment reservation

To update an existing enviornment reservation, send this request:

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

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

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/EnvironmentReservation5effeab1805e4ed6bd9a12c273467d92",
  "startDate" : 1731911926740,
  "endDate" : 1731915526740,
  "note" : "New note",
  "environment" : {
    "id" : "Configuration/environmentManagement/1346261309",
    "title" : "Environment2",
    "folderId" : null,
    "description" : "Environment2 description",
    "stage" : {
      "id" : "Configuration/environmentManagement/EnvironmentStage6d033440239743d08a5e95f96703f71c",
      "title" : "DEV"
    },
    "labels" : [ ]
  },
  "applications" : [ {
    "id" : "Configuration/environmentManagement/Application45ac0f92ffe642d3a73a3c2386064819",
    "title" : "APP1",
    "folderId" : null
  } ]
}

Delete an environment reservation

To delete an existing environment reservation, send this request:

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

Using the following path parameters:

Table 124. /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" : 1731911923869,
  "to" : 1731937123869
}
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" : 1731911923869,
  "to" : 1731937123869
}'
HTTPie
$ echo '{
  "environmentTitle" : "Env",
  "stages" : [ "DEV" ],
  "labels" : [ "AWS" ],
  "applications" : [ "APP1" ],
  "from" : 1731911923869,
  "to" : 1731937123869
}' | 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: 1235

[ {
  "id" : "Configuration/environmentManagement/1001926232",
  "title" : "Environment1",
  "folderId" : null,
  "description" : "Environment1 description",
  "stage" : {
    "id" : "Configuration/environmentManagement/EnvironmentStage130cfe8281a541e9aba5ea1d5b4dc8c2",
    "title" : "DEV"
  },
  "labels" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentLabel894f8404eadb43ecbc763867f9f7ab92",
    "title" : "AWS",
    "color" : "#ff00ff"
  } ],
  "reservations" : [ {
    "id" : "Configuration/environmentManagement/EnvironmentReservationca7dc4a349d247049874e3aaf350b205",
    "startDate" : 1731911923869,
    "endDate" : 1731937123869,
    "note" : null,
    "applications" : [ {
      "id" : "Configuration/environmentManagement/Applicationeaa07b43066f4ed79b47d09a292da1c1",
      "title" : "APP1",
      "folderId" : null
    } ]
  }, {
    "id" : "Configuration/environmentManagement/EnvironmentReservation2cbdd6fc2fcc4e2c9d68d4b5961707cd",
    "startDate" : 1731911923869,
    "endDate" : 1731915523869,
    "note" : "Note",
    "applications" : [ {
      "id" : "Configuration/environmentManagement/Applicationeaa07b43066f4ed79b47d09a292da1c1",
      "title" : "APP1",
      "folderId" : null
    } ]
  } ]
} ]

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/EnvironmentReservation30f453dae35e4633874c418890f879df?applicationId=Configuration/environmentManagement/Applicationf421f8cb9bc84d17897cb36bf9d8d4d7
Curl
$ curl 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservation30f453dae35e4633874c418890f879df?applicationId=Configuration/environmentManagement/Applicationf421f8cb9bc84d17897cb36bf9d8d4d7' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded'
HTTPie
$ http --form POST 'http://localhost:5516/api/v1/environments/reservations/Configuration/environmentManagement/EnvironmentReservation30f453dae35e4633874c418890f879df?applicationId=Configuration/environmentManagement/Applicationf421f8cb9bc84d17897cb36bf9d8d4d7' \
    'Accept:application/json'

Using the following path parameters:

Table 125. /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/EnvironmentStage6362ed32b2b74f839bf33ac3cd447f80",
  "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/EnvironmentStage3c202966ff9440f087e1f395b2ac9d33
Curl
$ curl 'http://localhost:5516/api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStage3c202966ff9440f087e1f395b2ac9d33' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStage3c202966ff9440f087e1f395b2ac9d33' \
    'Accept:application/json'

Using the following path parameters:

Table 126. /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/EnvironmentStage3c202966ff9440f087e1f395b2ac9d33",
  "title" : "DEV1"
}

Update an environment stage

To update an existing environment stage, send this request:

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

{
  "title" : "TEST1"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/stages/Configuration/environmentManagement/EnvironmentStageb9ef06092fa34a77a1961a698b63eec5' -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/EnvironmentStageb9ef06092fa34a77a1961a698b63eec5' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 127. /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/EnvironmentStageb9ef06092fa34a77a1961a698b63eec5",
  "title" : "TEST1"
}

Delete an environment stage

To delete an existing environment stage, send this request:

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

Using the following path parameters:

Table 128. /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/EnvironmentStagecd9b915ee08241d7b45da965480884e5",
  "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/EnvironmentLabel28af008aac8847ec8d1495781390cf9b",
  "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/EnvironmentLabel91790dc3dedb4cc8960e13fcebe3988f
Curl
$ curl 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabel91790dc3dedb4cc8960e13fcebe3988f' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabel91790dc3dedb4cc8960e13fcebe3988f' \
    'Accept:application/json'

Using the following path parameters:

Table 129. /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/EnvironmentLabel91790dc3dedb4cc8960e13fcebe3988f",
  "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/EnvironmentLabel68246d33050f4cd8a4dc72817e533f72

{
  "title" : "RDS",
  "color" : "#ff00ff"
}
Curl
$ curl 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabel68246d33050f4cd8a4dc72817e533f72' -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/EnvironmentLabel68246d33050f4cd8a4dc72817e533f72' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 130. /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/EnvironmentLabel68246d33050f4cd8a4dc72817e533f72",
  "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/EnvironmentLabele5871902ef6a4ab6b04a1be383fa2aa1
Curl
$ curl 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabele5871902ef6a4ab6b04a1be383fa2aa1' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/environments/labels/Configuration/environmentManagement/EnvironmentLabele5871902ef6a4ab6b04a1be383fa2aa1' \
    'Accept:application/json'

Using the following path parameters:

Table 131. /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/EnvironmentLabel91d71007e83b4d71bfeb678919dfc5c4",
  "title" : "Openshift",
  "color" : "#aaaaaa"
} ]

Applications

Create a new application

To create a new application, send this request:

HTTP Request
POST /api/v1/applications

{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment75454af294a84e6e8d0ea0a2251320a1" ]
}
Curl
$ curl 'http://localhost:5516/api/v1/applications' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment75454af294a84e6e8d0ea0a2251320a1" ]
}'
HTTPie
$ echo '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "New application",
  "environmentIds" : [ "Configuration/environmentManagement/Environment75454af294a84e6e8d0ea0a2251320a1" ]
}' | 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: 376

{
  "id" : "Configuration/environmentManagement/Applicationc5a3b4965814483a961d290981384b6e",
  "title" : "New application",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment75454af294a84e6e8d0ea0a2251320a1",
    "title" : "ENV1",
    "folderId" : null,
    "description" : null
  } ]
}

Find an application by ID

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

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

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/Applicationb743597188c14264bc2d99fac9933589",
  "title" : "Application1",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environmenta1b9cb6110ef404f9372dda1d1cb711c",
    "title" : "ENV1",
    "folderId" : null,
    "description" : null
  } ]
}

Update an application

To update an existing application, send this request:

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

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

Using the following path parameters:

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

{
  "id" : "Configuration/environmentManagement/Applicationa5fe3e8c1a0646ff8b38325bb942fd72",
  "title" : "New application title",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environmentd574ce71e1f445d48aa9b553e9107b31",
    "title" : "ENV1",
    "folderId" : null,
    "description" : null
  } ]
}

Delete an application

To delete an existing application, send this request:

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

Using the following path parameters:

Table 134. /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",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "environments" : [ "ENV1" ],
  "scope" : null
}
Curl
$ curl 'http://localhost:5516/api/v1/applications/search' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "App",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "environments" : [ "ENV1" ],
  "scope" : null
}'
HTTPie
$ echo '{
  "title" : "App",
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "environments" : [ "ENV1" ],
  "scope" : null
}' | 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: 377

[ {
  "id" : "Configuration/environmentManagement/Applicationaa4f6f5bd3c84ce882d0bc195a9908e9",
  "title" : "Application1",
  "folderId" : "Folder01345a690c16b345168751d62934e912",
  "environments" : [ {
    "id" : "Configuration/environmentManagement/Environment1617a9d8e3f74a92a3faa21f30dc50e5",
    "title" : "ENV1",
    "folderId" : null,
    "description" : null
  } ]
} ]

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" : "60",
  "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" : "60",
  "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" : "60",
  "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" : "60",
  "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" : "60",
  "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" : "60",
  "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 135. /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 136. /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 137. /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 138. /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 139. /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 140. /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/Deliveryb6af4886d33d4074b824ad124525565a",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage62ef8731479e4dcf80f6b382605dc4c9",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage907b61830e3a4d3cbfdf7d368512d4cd",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage5295be17976544c5aa09415d84704bbb",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage04ba535149684a1886868478ed7b01a5",
    "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/Deliveryb6af4886d33d4074b824ad124525565a",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage62ef8731479e4dcf80f6b382605dc4c9",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage907b61830e3a4d3cbfdf7d368512d4cd",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage5295be17976544c5aa09415d84704bbb",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage04ba535149684a1886868478ed7b01a5",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage62ef8731479e4dcf80f6b382605dc4c9",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage907b61830e3a4d3cbfdf7d368512d4cd",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage5295be17976544c5aa09415d84704bbb",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryb6af4886d33d4074b824ad124525565a/Stage04ba535149684a1886868478ed7b01a5",
    "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/Delivery8ef1397541b74733b7c9bcf837bf0ded",
  "type" : "delivery.Delivery",
  "title" : "New pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery8ef1397541b74733b7c9bcf837bf0ded/Stage62ef8731479e4dcf80f6b382605dc4c9",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery8ef1397541b74733b7c9bcf837bf0ded/Stage907b61830e3a4d3cbfdf7d368512d4cd",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery8ef1397541b74733b7c9bcf837bf0ded/Stage5295be17976544c5aa09415d84704bbb",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery8ef1397541b74733b7c9bcf837bf0ded/Stage04ba535149684a1886868478ed7b01a5",
    "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/Deliverya3fbb802761048fa84404f612657c404
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverya3fbb802761048fa84404f612657c404' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverya3fbb802761048fa84404f612657c404' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404/Stage7c1f865a32314258aa44e913a2400c32",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404/Stagee86a02b182454fb6be0cf6cb6fab9f37",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404/Stageeb2ec95b22d04cb48d6f7719ddfd461d",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404/Staged3d2c0597f4e43f59a574288e53d1fb0",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliverya3fbb802761048fa84404f612657c404/TrackedItem6f4c8a25a5814e55bbe079cba70a55bb",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:37.466+01:00",
    "modifiedDate" : "2024-11-18T07:38:37.466+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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 142. /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: 3524

{
  "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257/Stage7344d4ecb6cd49de9981f9d3ca9754b6",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257/Stage4b3cd769c85c437fb92893aef9e56154",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257/Stageea8f47a4122a4ab990f67af72733c82e",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257/Stageed22432f4b7644a0889c6af9d41b59b3",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliveryb9326629f2aa432fb0d7cc9cc7cc2257/TrackedItem6bce872fb92147dfb4dbcb681ae43002",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:34.208+01:00",
    "modifiedDate" : "2024-11-18T07:38:34.208+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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/Deliveryc26a23ca41ce48f1ac449512629664a3

{
  "id" : "Deliveries/Delivery988d058bea33451e8355bf08e2adf4b9",
  "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/Deliveryc26a23ca41ce48f1ac449512629664a3' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "Deliveries/Delivery988d058bea33451e8355bf08e2adf4b9",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 72,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : "Deliveries/Delivery988d058bea33451e8355bf08e2adf4b9",
  "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/Deliveryc26a23ca41ce48f1ac449512629664a3' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3",
  "type" : "delivery.Delivery",
  "title" : "Updated pattern",
  "status" : "TEMPLATE",
  "startDate" : "2024-11-18T07:38:43.337+01:00",
  "endDate" : "2024-11-21T07:38:43.337+01:00",
  "plannedDuration" : 72,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3/Stage8ff08b861cda481dbed61e5a540ee92b",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3/Stagef0be05669e5048699205d2611334df45",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3/Stage81ae9938ccc04568b14f7c45b864376c",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3/Stage31b077e1c8a64b048e44c0633b4b7778",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliveryc26a23ca41ce48f1ac449512629664a3/TrackedItem8d996e0bb3e74c7abd62eeeff98af238",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:43.201+01:00",
    "modifiedDate" : "2024-11-18T07:38:43.201+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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/Deliverya647cfbed501442bbfa0761f788ead12
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverya647cfbed501442bbfa0761f788ead12' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverya647cfbed501442bbfa0761f788ead12'

Using the following path parameters:

Table 144. /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/Deliveryb5f038a2287349f5bbb0d8878b8c8941/create

{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "duration" : 0,
  "startDate" : 1731911914994,
  "endDate" : 1731940714994,
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryb5f038a2287349f5bbb0d8878b8c8941/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" : 1731911914994,
  "endDate" : 1731940714994,
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "duration" : 0,
  "startDate" : 1731911914994,
  "endDate" : 1731940714994,
  "autoComplete" : false
}' | http POST 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryb5f038a2287349f5bbb0d8878b8c8941/create' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following parameters:

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

{
  "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "description" : "Test delivery description",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:34.994+01:00",
  "endDate" : "2024-11-18T15:38:34.994+01:00",
  "plannedDuration" : 8,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Deliveryb5f038a2287349f5bbb0d8878b8c8941",
  "stages" : [ {
    "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stagef28b94fc62af4e55a6bb23f7ee28d28f",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stagef28b94fc62af4e55a6bb23f7ee28d28f/StageTrackedItem64fa3581da3949c5912d837eb1e2a3bb",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/TrackedItem1f86635399954de29fd62b6781bac110",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stagee88827e6778f42388ad516e3ca0cbc01",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stagee88827e6778f42388ad516e3ca0cbc01/StageTrackedItembe278396a38142789ca1da2a4f830380",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/TrackedItem1f86635399954de29fd62b6781bac110",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stage6efca58b043b467dac6c77856db4b448",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stage6efca58b043b467dac6c77856db4b448/StageTrackedItemcb7497ebcc1340d59a67e4d4349d8371",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/TrackedItem1f86635399954de29fd62b6781bac110",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stage3f2dd843e5b74a35a000eeb3f0f3a59b",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/Stage3f2dd843e5b74a35a000eeb3f0f3a59b/StageTrackedItem9eb25f96312c48949024ab1f0d96b095",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/TrackedItem1f86635399954de29fd62b6781bac110",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery82e731b0342f4ac4bdc9fdb1bd3b0db7/TrackedItem1f86635399954de29fd62b6781bac110",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:35.028+01:00",
    "modifiedDate" : "2024-11-18T07:38:35.028+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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/Delivery255f54b567184f09b61f318c409c35dc",
  "type" : "delivery.Delivery",
  "title" : "Test pattern",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery255f54b567184f09b61f318c409c35dc/Stage2be147067b3242ca955eba9131666fcc",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery255f54b567184f09b61f318c409c35dc/Stagefd6afe83033e46ad949c44a108c4c2e7",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery255f54b567184f09b61f318c409c35dc/Stagee02cc06a2754413cad112feccd3b97b1",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery255f54b567184f09b61f318c409c35dc/Stage19a80d2f74074ba9adc8480a6d75536d",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery255f54b567184f09b61f318c409c35dc/TrackedItem003a734da1374e2fb9d053423f2b0942",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:31.527+01:00",
    "modifiedDate" : "2024-11-18T07:38:31.527+01:00"
  } ],
  "subscribers" : [ ],
  "autoComplete" : false
}, {
  "id" : "Deliveries/Delivery8bea063b46f9462b935c0666e5d7ce11",
  "type" : "delivery.Delivery",
  "title" : "Test pattern 2",
  "status" : "TEMPLATE",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery8bea063b46f9462b935c0666e5d7ce11/Stage33870117bded423098a9b1cfdb866cc1",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery8bea063b46f9462b935c0666e5d7ce11/Stagedf072800335442e79323585f21dd8e11",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery8bea063b46f9462b935c0666e5d7ce11/Stage7f2fb8520e8b490e87b647993aee7531",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery8bea063b46f9462b935c0666e5d7ce11/Stageab70527d359146febc10808c1c43204d",
    "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/Delivery59018fb8a4a14a28b67120d3dd130eb9/stages/4

{
  "id" : "1652793860",
  "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/Delivery59018fb8a4a14a28b67120d3dd130eb9/stages/4' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "1652793860",
  "type" : "delivery.Stage",
  "title" : "New stage",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "Owner user",
  "team" : "Owner team"
}'
HTTPie
$ echo '{
  "id" : "1652793860",
  "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/Delivery59018fb8a4a14a28b67120d3dd130eb9/stages/4' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 146. /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/Delivery59018fb8a4a14a28b67120d3dd130eb9/Stage84cb00fb94c844bcbd2a580b1950e16e",
  "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/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/stages
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/stages' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/stages' \
    'Accept:application/json'

Using the following path parameters:

Table 147. /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/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/Stage405c181b401e42119a424d1ad61fd8ae",
  "type" : "delivery.Stage",
  "title" : "Feature in Dev",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User Dev",
  "team" : "Team Dev"
}, {
  "id" : "Deliveries/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/Stagec5024b60baf942ff92a515f6f3b352e9",
  "type" : "delivery.Stage",
  "title" : "Feature in QA",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User QA",
  "team" : "Team QA"
}, {
  "id" : "Deliveries/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/Stagea6020288f0854df1a2498b0f88283efe",
  "type" : "delivery.Stage",
  "title" : "Feature in Pre-Prod",
  "status" : "OPEN",
  "items" : [ ],
  "owner" : "User Pre-Prod",
  "team" : "Team Pre-Prod"
}, {
  "id" : "Deliveries/Deliveryf8b8ca105bba4cf1acd15e0e88ec6adc/Stageb5a5c9ed418c462b8cfc488c1cc512bd",
  "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/Deliveryb6143336132449cc8e00acd003902add/Stage9e37992cdc1a440b9a320f57bfc4e84e

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

Using the following path parameters:

Table 148. /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/Deliveryb6143336132449cc8e00acd003902add/Stage9e37992cdc1a440b9a320f57bfc4e84e",
  "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/Delivery4b7729e354614430b9f7b567bb6a9f5d/Stage0caa97e2f2724a9697a7b4bdf59cb56d
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery4b7729e354614430b9f7b567bb6a9f5d/Stage0caa97e2f2724a9697a7b4bdf59cb56d' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery4b7729e354614430b9f7b567bb6a9f5d/Stage0caa97e2f2724a9697a7b4bdf59cb56d'

Using the following path parameters:

Table 149. /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/Delivery99f86c81219f4e3f8d0bb52d4fc6f8f0/Stage5ba1865424e44a51afd43466cd954a3a/transitions

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

Using the following path parameters:

Table 150. /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/Delivery99f86c81219f4e3f8d0bb52d4fc6f8f0/Stage5ba1865424e44a51afd43466cd954a3a/Transitione0d1daec6a6844fb89f65b4275dbcdf8",
  "type" : "delivery.Transition",
  "title" : "New transition",
  "stage" : "Deliveries/Delivery99f86c81219f4e3f8d0bb52d4fc6f8f0/Stage5ba1865424e44a51afd43466cd954a3a",
  "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/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff

{
  "id" : null,
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d",
  "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/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : null,
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d",
  "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/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d",
  "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/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 151. /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/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff",
  "type" : "delivery.Transition",
  "title" : "New transition title",
  "stage" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d",
  "conditions" : [ {
    "id" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff/Conditiond5a4b1f93d964d59b247a0125662f027",
    "type" : "delivery.ConditionGroup",
    "satisfied" : false,
    "operator" : "AND",
    "conditions" : [ {
      "id" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff/Conditione89874821265468f835d331db4c0ce9f",
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff/Condition2ba7a9ab37d14c5eb219572c0bcf49b9",
        "type" : "delivery.ItemsCompletionCondition",
        "satisfied" : false
      } ]
    }, {
      "id" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff/Condition9962b01874984d729a9eb23ec6928378",
      "type" : "delivery.ConditionGroup",
      "satisfied" : false,
      "operator" : "OR",
      "conditions" : [ {
        "id" : "Deliveries/Delivery209c5d4253f34600a573904aca95ae11/Stage6ffb919b9c1348cbb00e10d10eb84c9d/Transition5d1b0ded32534c218234f62467cc4cff/Conditioncfc36b2878684b079fd46398fbbdebc1",
        "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/Deliveryb876e3b850104f04b1a4f0dbbb4b8900/Stage4dcf3f36c16c4e1ab74fdbb353b5bbc8/Transition97ac5d50661a4bcea069db62867e88b6
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryb876e3b850104f04b1a4f0dbbb4b8900/Stage4dcf3f36c16c4e1ab74fdbb353b5bbc8/Transition97ac5d50661a4bcea069db62867e88b6' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliveryb876e3b850104f04b1a4f0dbbb4b8900/Stage4dcf3f36c16c4e1ab74fdbb353b5bbc8/Transition97ac5d50661a4bcea069db62867e88b6'

Using the following path parameters:

Table 152. /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/Delivery630b879a28154820991ee0434a1a34e5/tracked-items

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

Using the following path parameters:

Table 153. /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/Delivery630b879a28154820991ee0434a1a34e5/TrackedItem5f7c94b6de6d4808b01a8580efa0e331",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:28.154+01:00",
  "modifiedDate" : "2024-11-18T07:38:28.154+01: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/Delivery0908e473a6fa42baaa3eb540e0386a9c/tracked-items
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery0908e473a6fa42baaa3eb540e0386a9c/tracked-items' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Delivery0908e473a6fa42baaa3eb540e0386a9c/tracked-items' \
    'Accept:application/json'

Using the following path parameters:

Table 154. /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/Delivery0908e473a6fa42baaa3eb540e0386a9c/TrackedItem76bc6263fbc34e4a9fe34edf024eb9d4",
  "type" : "delivery.TrackedItem",
  "title" : "Test item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.705+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.705+01:00"
}, {
  "id" : "Deliveries/Delivery0908e473a6fa42baaa3eb540e0386a9c/TrackedItem1d46e152fbaa496aa38d49966b95f6a3",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 1",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.815+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.815+01:00"
}, {
  "id" : "Deliveries/Delivery0908e473a6fa42baaa3eb540e0386a9c/TrackedIteme3b80d505f3646a490943a3eb4134707",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 2",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.837+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.837+01: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/Deliverydf4dd39ba52b4e3992bfe040b0b418ba/TrackedItem6a7399f3fc204548be49bea210a3fee0

{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:38.474+01:00",
  "modifiedDate" : "2024-11-18T07:38:38.474+01:00"
}
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverydf4dd39ba52b4e3992bfe040b0b418ba/TrackedItem6a7399f3fc204548be49bea210a3fee0' -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" : "2024-11-18T07:38:38.474+01:00",
  "modifiedDate" : "2024-11-18T07:38:38.474+01:00"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:38.474+01:00",
  "modifiedDate" : "2024-11-18T07:38:38.474+01:00"
}' | http PUT 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverydf4dd39ba52b4e3992bfe040b0b418ba/TrackedItem6a7399f3fc204548be49bea210a3fee0' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 155. /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/Deliverydf4dd39ba52b4e3992bfe040b0b418ba/TrackedItem6a7399f3fc204548be49bea210a3fee0",
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:38.474+01:00",
  "modifiedDate" : "2024-11-18T07:38:38.511+01: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/Deliverye272513727134394bf34de785110869a/TrackedItem2cfc87fb19844b92be2521243c448cc3
Curl
$ curl 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverye272513727134394bf34de785110869a/TrackedItem2cfc87fb19844b92be2521243c448cc3' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/delivery-patterns/Deliveries/Deliverye272513727134394bf34de785110869a/TrackedItem2cfc87fb19844b92be2521243c448cc3' \
    'Accept:application/json'

Using the following path parameters:

Table 156. /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/Delivery13f8a75155454152bbb3ad0bc00ea032
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:23.587+01:00",
  "endDate" : "2024-11-20T01:38:23.587+01:00",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Delivery5408b0f1bcd34050a40f6d1446c8be00",
  "stages" : [ {
    "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stageaa0b92490eca4826895e891f32c9e4dc",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stageaa0b92490eca4826895e891f32c9e4dc/StageTrackedItem4044162fbef744288d68ba9d550e5c69",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/TrackedItemd6c196ea887d4d24868aae56f88300a3",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stageaa0b92490eca4826895e891f32c9e4dc/Transitionb443b33850f242318a33cf426472c367",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stageaa0b92490eca4826895e891f32c9e4dc",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stage1315e2b100ec486aa1aaafe6fd120464",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stage1315e2b100ec486aa1aaafe6fd120464/Transition696da561c8f6418f951d29597b3a5f06",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stage1315e2b100ec486aa1aaafe6fd120464",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stagee3936a1fc2654014ac6e12f97f4a257c",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stagee3936a1fc2654014ac6e12f97f4a257c/Transition61d88171bbe8439eb834ece2f73ad4bb",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stagee3936a1fc2654014ac6e12f97f4a257c",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/Stage851189a17139449bb86452b6b0f2c84a",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery13f8a75155454152bbb3ad0bc00ea032/TrackedItemd6c196ea887d4d24868aae56f88300a3",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:23.586+01:00",
    "modifiedDate" : "2024-11-18T07:38:23.586+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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/Deliverybe1f85ab330e40638243256ca7a730f0

{
  "id" : null,
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:40.807+01:00",
  "endDate" : "2024-11-18T19:38:40.807+01:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0' -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" : "2024-11-18T07:38:40.807+01:00",
  "endDate" : "2024-11-18T19:38:40.807+01:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:40.807+01:00",
  "endDate" : "2024-11-18T19:38:40.807+01:00",
  "plannedDuration" : 30,
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "autoComplete" : false
}' | http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0",
  "type" : "delivery.Delivery",
  "title" : "Updated delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:40.807+01:00",
  "endDate" : "2024-11-18T19:38:40.807+01:00",
  "plannedDuration" : 12,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Delivery12cdd6c0697d4ac0a3f8417910349139",
  "stages" : [ {
    "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagefe265bbf0b9a4e9a88064405669981fd",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagefe265bbf0b9a4e9a88064405669981fd/StageTrackedItema31daf3055a3498f96db9ddf9575d802",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/TrackedItem7819126e290d4532ad0294fa93a375dd",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagefe265bbf0b9a4e9a88064405669981fd/Transitionbf01360735f248189648202e63a841bb",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagefe265bbf0b9a4e9a88064405669981fd",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagef3c70f8838f840ceb8ce3ab138afee89",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagef3c70f8838f840ceb8ce3ab138afee89/Transition5329a455f64b498d8cc806680e6da208",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stagef3c70f8838f840ceb8ce3ab138afee89",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stage13f05961c1114892acfc7d984311099f",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stage13f05961c1114892acfc7d984311099f/Transition5d3a4a91edc54ff69a6bf5dd504f59d1",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stage13f05961c1114892acfc7d984311099f",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/Stageae678960c5994a248c92ee6fc71e5d45",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Deliverybe1f85ab330e40638243256ca7a730f0/TrackedItem7819126e290d4532ad0294fa93a375dd",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:40.791+01:00",
    "modifiedDate" : "2024-11-18T07:38:40.791+01: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", "workflow#view_execution", "workflow#abort_execution", "release#edit_security", "group#view", "release#lock_task", "app_pipelines#edit", "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", "app_pipelines#view", "release#edit_task_input_output_properties", "release#edit_task_tags", "folder#view_security", "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_flag", "release#edit_task_configuration_facet", "release#edit_task_dates", "dashboard#view", "workflow#start_execution", "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/Deliveryc43b8e2d0faf4c66a0d1caeed21d5011
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc43b8e2d0faf4c66a0d1caeed21d5011' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryc43b8e2d0faf4c66a0d1caeed21d5011'

Using the following path parameters:

Table 159. /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/Delivery4ec9ffe1772a41848f0aac79706022cc",
  "type" : "delivery.Delivery",
  "title" : "Test delivery 2",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:28.288+01:00",
  "endDate" : "2024-11-23T07:38:28.288+01:00",
  "plannedDuration" : 120,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "stages" : [ {
    "id" : "Deliveries/Delivery4ec9ffe1772a41848f0aac79706022cc/Stage29e8b34b5981409ba88f41510927c997",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery4ec9ffe1772a41848f0aac79706022cc/Stagefb627668d8a44ba3b0886c0681f6874e",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery4ec9ffe1772a41848f0aac79706022cc/Staged1a7333a8fa0462ba65f628b20e6467c",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery4ec9ffe1772a41848f0aac79706022cc/Stage354d0beeba2640c5865ca2f07f6fff25",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ ],
  "subscribers" : [ ],
  "autoComplete" : false
}, {
  "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df",
  "type" : "delivery.Delivery",
  "title" : "Test delivery",
  "status" : "IN_PROGRESS",
  "startDate" : "2024-11-18T07:38:28.269+01:00",
  "endDate" : "2024-11-20T01:38:28.269+01:00",
  "plannedDuration" : 42,
  "releaseIds" : [ ],
  "folderId" : "Applications/Folder01345a690c16b345168751d62934e912",
  "originPatternId" : "Deliveries/Deliveryb670b0e45d1043abb15e322420075232",
  "stages" : [ {
    "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage93b4fcb8c68e48f6a2e133404d503013",
    "type" : "delivery.Stage",
    "title" : "Feature in Dev",
    "status" : "OPEN",
    "items" : [ {
      "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage93b4fcb8c68e48f6a2e133404d503013/StageTrackedItem699b2f20e3594fcfbd83b736cf22db22",
      "type" : "delivery.StageTrackedItem",
      "trackedItemId" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/TrackedItem803c8be6d3144206b162d9861c8dde9a",
      "status" : "NOT_READY",
      "releaseIds" : [ ]
    } ],
    "transition" : {
      "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage93b4fcb8c68e48f6a2e133404d503013/Transition2de9a889fce24332bd2b6db5bec35f6e",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Dev",
      "stage" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage93b4fcb8c68e48f6a2e133404d503013",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Dev",
    "team" : "Team Dev"
  }, {
    "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage20aa9a57f2c546a5883406ae2f216f5e",
    "type" : "delivery.Stage",
    "title" : "Feature in QA",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage20aa9a57f2c546a5883406ae2f216f5e/Transition3a72290d67ef4715a8dc526323233ecf",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in QA",
      "stage" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage20aa9a57f2c546a5883406ae2f216f5e",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User QA",
    "team" : "Team QA"
  }, {
    "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage2acfed061f044d14afa2197626105cd3",
    "type" : "delivery.Stage",
    "title" : "Feature in Pre-Prod",
    "status" : "OPEN",
    "items" : [ ],
    "transition" : {
      "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage2acfed061f044d14afa2197626105cd3/Transition828ecd0c7447481783e88445c6b2280e",
      "type" : "delivery.Transition",
      "title" : "Wait for Feature in Pre-Prod",
      "stage" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage2acfed061f044d14afa2197626105cd3",
      "conditions" : [ ],
      "automated" : true
    },
    "owner" : "User Pre-Prod",
    "team" : "Team Pre-Prod"
  }, {
    "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/Stage08338ebf686547fbba3a8c611c002c44",
    "type" : "delivery.Stage",
    "title" : "Feature in Prod",
    "status" : "OPEN",
    "items" : [ ],
    "owner" : "User Prod",
    "team" : "Team Prod"
  } ],
  "trackedItems" : [ {
    "id" : "Deliveries/Delivery12afc84df64e4de6be567358c46b44df/TrackedItem803c8be6d3144206b162d9861c8dde9a",
    "type" : "delivery.TrackedItem",
    "title" : "Test item",
    "releaseIds" : [ ],
    "descoped" : false,
    "createdDate" : "2024-11-18T07:38:28.269+01:00",
    "modifiedDate" : "2024-11-18T07:38:28.269+01: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/Deliveryafccc2de7a9f475d98f60600ed0f1a38/releases
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryafccc2de7a9f475d98f60600ed0f1a38/releases' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryafccc2de7a9f475d98f60600ed0f1a38/releases' \
    'Accept:application/json'

Using the following path parameters:

Table 160. /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" : "Release1d1b527bc2b546c5850a085b44ecc948",
  "title" : "Release 1",
  "status" : "in_progress",
  "startDate" : null,
  "endDate" : null,
  "archived" : false
}, {
  "id" : "Release665eec048faa4c9baeb4b6cc44bf6602",
  "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/Deliveryf3fbbdbd86614d79b07cd2d2b33beb7a/tracked-items

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

Using the following path parameters:

Table 161. /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/Deliveryf3fbbdbd86614d79b07cd2d2b33beb7a/TrackedItemdc14a0a909054a0d8e2d09a9361726a9",
  "type" : "delivery.TrackedItem",
  "title" : "Item A",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:20.493+01:00",
  "modifiedDate" : "2024-11-18T07:38:20.493+01:00"
}

Get tracked items

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

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

Using the following path parameters:

Table 162. /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/Delivery5b6edeec9b124a0b8d613d954371d5ba/TrackedItem84506f8b67df4445856fcd452e7c444f",
  "type" : "delivery.TrackedItem",
  "title" : "Test item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:35.745+01:00",
  "modifiedDate" : "2024-11-18T07:38:35.745+01:00"
}, {
  "id" : "Deliveries/Delivery5b6edeec9b124a0b8d613d954371d5ba/TrackedItem137f8e02c9754ec0ba4f290e37874a2e",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 1",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:35.769+01:00",
  "modifiedDate" : "2024-11-18T07:38:35.769+01:00"
}, {
  "id" : "Deliveries/Delivery5b6edeec9b124a0b8d613d954371d5ba/TrackedItemc79ff30aba404feabe8fa5e76c3f39bf",
  "type" : "delivery.TrackedItem",
  "title" : "Item A 2",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:35.873+01:00",
  "modifiedDate" : "2024-11-18T07:38:35.873+01:00"
} ]

Update a tracked item

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

HTTP Request
PUT /api/v1/deliveries/Deliveries/Delivery929a463abb414a918fd98723fa0dd71d/TrackedItemf2284b2c3c2543f9abcaa8dbe05bb416

{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.743+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.743+01:00"
}
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery929a463abb414a918fd98723fa0dd71d/TrackedItemf2284b2c3c2543f9abcaa8dbe05bb416' -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" : "2024-11-18T07:38:36.743+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.743+01:00"
}'
HTTPie
$ echo '{
  "id" : null,
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.743+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.743+01:00"
}' | http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery929a463abb414a918fd98723fa0dd71d/TrackedItemf2284b2c3c2543f9abcaa8dbe05bb416' \
    'Content-Type:application/json' \
    'Accept:application/json'

Using the following path parameters:

Table 163. /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/Delivery929a463abb414a918fd98723fa0dd71d/TrackedItemf2284b2c3c2543f9abcaa8dbe05bb416",
  "type" : "delivery.TrackedItem",
  "title" : "Updated item",
  "releaseIds" : [ ],
  "descoped" : false,
  "createdDate" : "2024-11-18T07:38:36.743+01:00",
  "modifiedDate" : "2024-11-18T07:38:36.811+01:00"
}

Delete a tracked item

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

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

Using the following path parameters:

Table 164. /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/Deliverybe00704656354133b5b0844716b505b9/TrackedItemf6a1ded2f9b34e719c7e62a0b8a58eb8/descope
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybe00704656354133b5b0844716b505b9/TrackedItemf6a1ded2f9b34e719c7e62a0b8a58eb8/descope' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverybe00704656354133b5b0844716b505b9/TrackedItemf6a1ded2f9b34e719c7e62a0b8a58eb8/descope' \
    'Accept:application/json'

Using the following path parameters:

Table 165. /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/Delivery7fce46196ebd4978bc4165922d10c582/TrackedItemae5e5801e59542b6b699f65c6ff472b6/rescope
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery7fce46196ebd4978bc4165922d10c582/TrackedItemae5e5801e59542b6b699f65c6ff472b6/rescope' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery7fce46196ebd4978bc4165922d10c582/TrackedItemae5e5801e59542b6b699f65c6ff472b6/rescope' \
    'Accept:application/json'

Using the following path parameters:

Table 166. /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/Delivery179eee46b0d14741892ffb2f0a303b6c/Stagece81af5cb9a7454c94358d2a3ca3bd38/Deliveries/Delivery179eee46b0d14741892ffb2f0a303b6c/TrackedItem9cb1ab7818dd4e3f9eb95b7ffa0c859c/complete
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery179eee46b0d14741892ffb2f0a303b6c/Stagece81af5cb9a7454c94358d2a3ca3bd38/Deliveries/Delivery179eee46b0d14741892ffb2f0a303b6c/TrackedItem9cb1ab7818dd4e3f9eb95b7ffa0c859c/complete' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Delivery179eee46b0d14741892ffb2f0a303b6c/Stagece81af5cb9a7454c94358d2a3ca3bd38/Deliveries/Delivery179eee46b0d14741892ffb2f0a303b6c/TrackedItem9cb1ab7818dd4e3f9eb95b7ffa0c859c/complete' \
    'Accept:application/json'

Using the following path parameters:

Table 167. /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/Deliverydd73971e6c664b1d87ac8c311cb1df0c/Stage89139552840041b388aaf5bc86059a42/Deliveries/Deliverydd73971e6c664b1d87ac8c311cb1df0c/TrackedItemc7932c524b39405d98347f25df0ee2a1/skip
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverydd73971e6c664b1d87ac8c311cb1df0c/Stage89139552840041b388aaf5bc86059a42/Deliveries/Deliverydd73971e6c664b1d87ac8c311cb1df0c/TrackedItemc7932c524b39405d98347f25df0ee2a1/skip' -i -X PUT \
    -H 'Accept: application/json'
HTTPie
$ http PUT 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverydd73971e6c664b1d87ac8c311cb1df0c/Stage89139552840041b388aaf5bc86059a42/Deliveries/Deliverydd73971e6c664b1d87ac8c311cb1df0c/TrackedItemc7932c524b39405d98347f25df0ee2a1/skip' \
    'Accept:application/json'

Using the following path parameters:

Table 168. /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/Deliverye000da514849416585cfd23083301e2c/Stageca87146de98a4d26a6935c4e490db119/complete
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverye000da514849416585cfd23083301e2c/Stageca87146de98a4d26a6935c4e490db119/complete' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliverye000da514849416585cfd23083301e2c/Stageca87146de98a4d26a6935c4e490db119/complete' \
    'Accept:application/json'

Using the following path parameters:

Table 169. /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/Deliveryfee3311d839c4d1ea9e14995c057212a/Stagec405da853f5449c5be87e741a0190ded/reopen
Curl
$ curl 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryfee3311d839c4d1ea9e14995c057212a/Stagec405da853f5449c5be87e741a0190ded/reopen' -i -X POST \
    -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/deliveries/Deliveries/Deliveryfee3311d839c4d1ea9e14995c057212a/Stagec405da853f5449c5be87e741a0190ded/reopen' \
    'Accept:application/json'

Using the following path parameters:

Table 170. /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/Deliveryf7d2c7cedc894090bf0b17dd97db3a69/Stagea45fd981a9194f5482db795690c41938/Transitionf95b1762e4fd485297bef467e9caa021/complete

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

Using the following path parameters:

Table 171. /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 172. /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: 398

[ {
  "id" : "9",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "TASK_STARTED",
  "message" : "Started Task 'Configure users'",
  "eventTime" : "2024-11-18T07:38:17.825+01: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/Deliveryef7b695e85414e4bb3c7ddd805176c1e
Curl
$ curl 'http://localhost:5516/api/v1/activities/Deliveries/Deliveryef7b695e85414e4bb3c7ddd805176c1e' -i -X GET \
    -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/activities/Deliveries/Deliveryef7b695e85414e4bb3c7ddd805176c1e' \
    'Accept:application/json'

Using the following path parameters:

Table 173. /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" : "28",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "DELIVERY_CREATED",
  "message" : "Created delivery 'Delivery1'",
  "eventTime" : "2024-11-18T07:38:26.286+01:00",
  "targetType" : "delivery.Delivery",
  "targetId" : "Deliveries/Deliveryef7b695e85414e4bb3c7ddd805176c1e"
} ]

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 174. /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" : "22",
  "type" : "xlrelease.ActivityLogEntry",
  "username" : "admin",
  "activityType" : "TRIGGER_ADDED",
  "message" : "Added release trigger 'Simple Trigger'",
  "eventTime" : "2024-11-18T07:38:22.681+01: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 175. /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 176. 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 177. /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" : "Facetd16143c75bd74be3b658a5b232750208",
  "type" : "udm.PlanRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task169e52908657406c9b5ae07a496c697c",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2024-11-18T07:38:47.053+01:00",
  "ticket" : "REL-6437",
  "title" : "Some issue",
  "ticketType" : "BUG",
  "status" : "Paused",
  "updatedDate" : "2024-11-18T07:38:46.951+01:00",
  "updatedBy" : "admin",
  "ticket_url" : "http://example.com/browse/REL-6437"
}, {
  "id" : "Faceta852c6b33f66438fa26b28ef919911cb",
  "type" : "udm.DeploymentRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task31a0974f90b8450c98dbeef993f53667",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2024-11-18T07:38:47.009+01:00",
  "deploymentTask" : "PR-1234",
  "deploymentTask_url" : "http://example.com",
  "applicationName" : "XL-Jetpack",
  "version" : "1.0",
  "environmentName" : "34521",
  "status" : "IN_PROGRESS"
}, {
  "id" : "Facetb53af6efb1bf459385179cef8cf8f3df",
  "type" : "udm.ItsmRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Taskcecbc48333e04276b212a4091adf3928",
  "variableMapping" : { },
  "serverUrl" : "example.com",
  "serverUser" : "nobody",
  "creationDate" : "2024-11-18T07:38:47.032+01: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" : "Faceta3cf21a0a0b64f37839dae773ff1c1d5",
  "type" : "udm.BuildRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task97c27091a9b342599e1b631dc6d44726",
  "variableMapping" : { },
  "serverUrl" : "http://example.com",
  "serverUser" : "admin",
  "creationDate" : "2024-11-18T07:38:46.973+01:00",
  "project" : "XL-RELEASE",
  "build" : "PR-1234",
  "outcome" : "SUCCESS",
  "startDate" : "2024-11-18T07:38:46.951+01:00",
  "endDate" : "2024-11-18T07:38:46.951+01:00",
  "duration" : "34521",
  "build_url" : "http://example.com"
}, {
  "id" : "Facet3b0716d12f954dc4b89ef3f4d4ffd627",
  "type" : "udm.CodeComplianceRecord",
  "targetId" : "Applications/Release162151faba694d03aa3065665cf26f21/Phase520d9bb734c8490cad6818f736da7a5e/Task5be4358d7e7a4282b79e6cf474375978",
  "variableMapping" : { },
  "serverUrl" : "https://example.com",
  "serverUser" : "nobody",
  "creationDate" : "2024-11-18T07:38:46.990+01:00",
  "project" : "Project",
  "project_url" : "https://example.com/project1",
  "analysisDate" : "2024-11-18T07:38:46.951+01: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 178. /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 /api/v1/plugin-manager/list
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/list' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/plugin-manager/list'

A response :

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

[ {
  "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" : "zip test plugin",
    "requirements" : {
      "product" : "XL Release",
      "versions" : [ "== 24.4.0" ]
    },
    "screenshots" : [ ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "zip-test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins",
    "packaging" : "jar"
  },
  "status" : "READY_FOR_INSTALL",
  "versions" : [ {
    "repository" : "xlr-official",
    "version" : "23.3.0"
  } ]
}, {
  "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" : [ "== 24.4.0" ]
    },
    "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",
    "packaging" : "jar"
  },
  "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__)

[].plugin.packaging

String

The packaging of plugin on the Nexus repository

[].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 /api/v1/plugin-manager/repositories
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/repositories' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/plugin-manager/repositories'

A response:

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

[ {
  "config" : {
    "nexus-group-id" : "com.xebialabs.xlrelease.plugins",
    "nexus-metadata-artifact" : {
      "artifact-id" : "xlr-plugins-metadata",
      "group-id" : "com.xebialabs.xlrelease.plugins.metadata"
    },
    "repository-id" : "official-plugins",
    "repository-type" : "nexus-by-group-id",
    "server" : {
      "server-type" : "nexus",
      "url" : "http://localhost:35241/nexus"
    }
  },
  "lastUpdated" : 1731911920831,
  "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.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 /api/v1/plugin-manager/repositories/xlr-official/list
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/repositories/xlr-official/list' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/plugin-manager/repositories/xlr-official/list'
Table 179. /api/v1/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: 2563

[ {
  "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" : "zip test plugin",
    "requirements" : {
      "product" : "XL Release",
      "versions" : [ "== 24.4.0" ]
    },
    "screenshots" : [ ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "zip-test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins",
    "packaging" : "jar"
  },
  "versions" : [ {
    "repository" : "xlr-official",
    "version" : "23.3.0"
  } ]
}, {
  "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" : [ "== 24.4.0" ]
    },
    "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",
    "packaging" : "jar"
  },
  "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" : [ "== 24.4.0" ]
    },
    "screenshots" : [ ],
    "supportedBy" : "Digital.ai"
  },
  "plugin" : {
    "artifactId" : "another-test-plugin",
    "groupId" : "com.xebialabs.xlrelease.plugins",
    "packaging" : "jar"
  },
  "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__)

[].plugin.packaging

String

The packaging of plugin on the Nexus repository

[].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 /api/v1/plugin-manager/repositories/xlr-official/install/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0
Curl
$ curl 'http://localhost:5516/api/v1/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/api/v1/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: 93

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

message

String

Human readable description of what happened

requiresRestart

Boolean

If the server restart is required or not

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 /api/v1/plugin-manager/repositories/xlr-official/update/com.xebialabs.xlrelease.plugins/another-test-plugin
Curl
$ curl 'http://localhost:5516/api/v1/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/api/v1/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 /api/v1/plugin-manager/install?pluginId=test-plugin-name.jar

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=test-plugin-name.jar; filename=test-plugin-name.jar
Content-Type: application/octet-stream

PK        *G�T        �   
   synthetic.xmlUT
  ј�b㘄bј�bux    �        ��;
�0 D{�B���I:�� N�&�,�hA �]�|��  ��j`xozZ3 ��dK1�i�  �  Pk����� �����9�\��^0 �� ��&8��Oh��H��`�K,+2�g��Ц ���%��{Ӎf5 � �� PK  E�\u�   �   PK          *G�TE�\u�   �   
           ��    synthetic.xmlUT
  ј�b㘄bј�bux    �        PK          [   �
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=test-plugin-name.jar; filename=test-plugin-name.jar
Content-Type: application/octet-stream

PK        *G�T        �   
   synthetic.xmlUT
  ј�b㘄bј�bux    �        ��;
�0 D{�B���I:�� N�&�,�hA �]�|��  ��j`xozZ3 ��dK1�i�  �  Pk����� �����9�\��^0 �� ��&8��Oh��H��`�K,+2�g��Ц ���%��{Ӎf5 � �� PK  E�\u�   �   PK          *G�TE�\u�   �   
           ��    synthetic.xmlUT
  ј�b㘄bј�bux    �        PK          [   �
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/install?pluginId=test-plugin-name.jar' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json' \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1' \
    -F 'test-plugin-name.jar=@test-plugin-name.jar;type=application/octet-stream' \
    -F 'test-plugin-name.jar=@test-plugin-name.jar;type=application/octet-stream'
HTTPie
$ http --multipart POST 'http://localhost:5516/api/v1/plugin-manager/install?pluginId=test-plugin-name.jar' \
    'Accept:application/json' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1' \
    'test-plugin-name.jar'@'test-plugin-name.jar' \
    'test-plugin-name.jar'@'test-plugin-name.jar'

A response:

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

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

message

String

Human readable description of what happened

requiresRestart

Boolean

If the server restart is required or not

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 /api/v1/plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=another-test-plugin.jar; filename=another-test-plugin.jar
Content-Type: application/octet-stream

PK        QU�T        �   
   synthetic.xmlUT
  {��b㘄b{��bux    �        ��; �0 D{Na���$�E8 �Ҥ5ƊW� �+��>  �2S�4zo:Z {�hE�!��� �g
PJQ���[�^�� ^ֻh.��M�N6��&8�Սh� I� ars�+2�g�PӦ �5�9�� {S�&�7�t�� PK  dP �   �   PK        QU�T        �       __MACOSX/._synthetic.xmlUT
  {��b���b���bux    �        c` cg`b`�MLV� V�P� �  '   q  ��  � �!!AP&H�   @Sˆ �J���K,(�I��I,.)-NMII,IU   ),�ؒ �K &�5  PK  V8��\   �   PK          QU�TdP �   �   
           ��    synthetic.xmlUT
  {��b㘄b{��bux    �        PK          QU�TV8��\   �               ���   __MACOSX/._synthetic.xmlUT
  {��b���b���bux    �        PK          �   � 
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=another-test-plugin.jar; filename=another-test-plugin.jar
Content-Type: application/octet-stream

PK        QU�T        �   
   synthetic.xmlUT
  {��b㘄b{��bux    �        ��; �0 D{Na���$�E8 �Ҥ5ƊW� �+��>  �2S�4zo:Z {�hE�!��� �g
PJQ���[�^�� ^ֻh.��M�N6��&8�Սh� I� ars�+2�g�PӦ �5�9�� {S�&�7�t�� PK  dP �   �   PK        QU�T        �       __MACOSX/._synthetic.xmlUT
  {��b���b���bux    �        c` cg`b`�MLV� V�P� �  '   q  ��  � �!!AP&H�   @Sˆ �J���K,(�I��I,.)-NMII,IU   ),�ؒ �K &�5  PK  V8��\   �   PK          QU�TdP �   �   
           ��    synthetic.xmlUT
  {��b㘄b{��bux    �        PK          QU�TV8��\   �               ���   __MACOSX/._synthetic.xmlUT
  {��b���b���bux    �        PK          �   � 
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json' \
    -H 'Cookie: XSRF-TOKEN=1' \
    -H 'X-XSRF-TOKEN: 1' \
    -F 'another-test-plugin.jar=@another-test-plugin.jar;type=application/octet-stream' \
    -F 'another-test-plugin.jar=@another-test-plugin.jar;type=application/octet-stream'
HTTPie
$ http --multipart POST 'http://localhost:5516/api/v1/plugin-manager/update?existingPluginName=another-test-plugin&newPluginId=another-test-plugin.jar' \
    'Accept:application/json' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1' \
    'another-test-plugin.jar'@'another-test-plugin.jar' \
    'another-test-plugin.jar'@'another-test-plugin.jar'

A response:

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

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

message

String

Human readable description of what happened

requiresRestart

Boolean

If the server restart is required or not

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 /api/v1/plugin-manager/delete/xlr-official/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0
Curl
$ curl 'http://localhost:5516/api/v1/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/api/v1/plugin-manager/delete/xlr-official/com.xebialabs.xlrelease.plugins/another-test-plugin/10.1.0' \
    'Cookie:XSRF-TOKEN=1' \
    'X-XSRF-TOKEN:1'
Table 180. /api/v1/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 /api/v1/plugin-manager/repositories/xlr-official/update
Curl
$ curl 'http://localhost:5516/api/v1/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/api/v1/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: 50

{
  "lastDownloaded" : "11-18-2024 07:38:41 CET"
}
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 /api/v1/plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/plugin-manager/repositories/xlr-official/logo/com.xebialabs.xlrelease.plugins/test-plugin'
Table 181. /api/v1/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 /api/v1/plugin-manager/search/test
Curl
$ curl 'http://localhost:5516/api/v1/plugin-manager/search/test' -i -X GET
HTTPie
$ http GET 'http://localhost:5516/api/v1/plugin-manager/search/test'
Table 182. /api/v1/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__)

[].plugin.packaging

String

The packaging of plugin on the Nexus repository

[].versions[].repository

String

Plugin repository identifier

[].versions[].version

String

Plugin version