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

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

For example:

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

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

Identifiers

You need to know the identifiers that releases, phases, and tasks have in the database. Both templates and releases have an ID of the form Applications/ReleaseXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, where XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is a thirty-two-digit alpha-numeric sequence (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/FolderXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-FolderXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-ReleaseXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

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

To get the identifiers of phases and tasks, first do a REST call to get the contents of a release, and then inspect the results to find the IDs.
Properties that start with '$' sign are considered internal properties - i.e. may change between product versions. Please do not rely on those properties to be present.

Authentication

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

Error codes

400

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

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

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

402

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

403

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

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

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

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

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

Finding templates, releases, phases, tasks

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

Find template/release by ID

To find a template or release using a specific ID, send this request:

HTTP Request
GET /api/v1/templates/Applications/Release1a
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/Applications/Release1a' 'Accept:application/json'

Using the following parameters

  • for template:

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

templateId

Full template identifier; for example, Applications/Release1

  • for release:

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

releaseId

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

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

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

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

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Find archived release by ID

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

HTTP Request
GET /api/v1/releases/archived/Applications/Release1a
Curl
$ curl 'http://localhost:5516/api/v1/releases/archived/Applications/Release1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/archived/Applications/Release1a' 'Accept:application/json'

Using the following parameters:

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

releaseId

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

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

Find release by title

Note that you cannot find a template by title.

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

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

[ {
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Find me",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

Find phase by ID

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

HTTP Request
GET /api/v1/phases/Applications/Release1a/Phase1a
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release1a/Phase1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/Applications/Release1a/Phase1a' 'Accept:application/json'

Using the following parameters:

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

phaseId

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

The response contains the phase as JSON:

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

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

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

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

originId

String

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

Find task by ID

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

HTTP Request
GET /api/v1/tasks/Applications/Release1a/Phase1a/Task1a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a' 'Accept:application/json'

Using the following parameters:

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

taskId

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

The response contains the task as JSON:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:53.011+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Search phases in a release by title

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

HTTP Request
GET /api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release1a
Curl
$ curl 'http://localhost:5516/api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/byTitle?phaseTitle=find%20me&releaseId=Applications/Release1a' 'Accept:application/json'

Using the following parameters:

Parameter Description

phaseTitle

The phase title

releaseId

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

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

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

[ {
  "id" : "Applications/Release1a/Phase1a",
  "type" : "xlrelease.Phase",
  "title" : "find me",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release1a",
  "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/Release1a&phaseVersion=ALL
Curl
$ curl 'http://localhost:5516/api/v1/phases/search?phaseTitle=DEV&releaseId=Applications/Release1a&phaseVersion=ALL' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/phases/search?phaseTitle=DEV&releaseId=Applications/Release1a&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-Type: application/json
Content-Length: 254

[ {
  "id" : "Applications/Release1a/Phase1a",
  "type" : "xlrelease.Phase",
  "title" : "DEV",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release1a",
  "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/Release1a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/Release1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/byTitle?taskTitle=find%20me&phaseTitle=phase%20title&releaseId=Applications/Release1a' 'Accept:application/json'

Using the following parameters:

Parameter Description

taskTitle

The task title

phaseTitle

The phase title

releaseId

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

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

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

[ {
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "find me",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:50.736+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false
} ]

Listing planned or active releases

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

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

Using the following parameters:

Parameter Description

page

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

resultsPerPage

Number of results per page, default value is 100

depth

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

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

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

[ {
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}, {
  "id" : "Applications/Release2b",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release2b",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
} ]

Listing templates

To list a page of release templates send this request:

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

Using the following parameters:

Parameter Description

page

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

resultsPerPage

Number of results per page, default value is 100

depth

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

title

Title of the release

tag

Tag of the release

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

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

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

Release life cycle

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

Create a release from template

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

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

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

{
  "releaseTitle" : "release from api",
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release1a/create' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "releaseTitle" : "release from api",
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false
}'
HTTPie
$ echo '{
  "releaseTitle" : "release from api",
  "releaseVariables" : { },
  "releasePasswordVariables" : { },
  "scheduledStartDate" : null,
  "autoStart" : false
}' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release1a/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

releaseVariables

Object

Release variables

releasePasswordVariables

Object

Release password variables

scheduledStartDate

Null

Date when the release is supposed to start.

autoStart

Boolean

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

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

{
  "releaseTitle": "release from api",
  "releaseVariables": {
    "variable1": "value1"
  },
  "releasePasswordVariables": {
    "passwordVariable": "passwordValue"
  }
}
To create and start the release 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-Type: application/json
Content-Length: 1167

{
  "id" : "Applications/Release66b01bfa0d164917aec7d1c86cc6cd01",
  "type" : "xlrelease.Release",
  "title" : "release from api",
  "owner" : "admin",
  "scheduledStartDate" : "2019-08-22T19:56:55.053+02:00",
  "dueDate" : "2019-08-23T03:56:55.053+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:55.053+02:00",
  "queryableEndDate" : "2019-08-23T03:56:55.053+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarLinkToken" : "-5955572381848223525",
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "originTemplateId" : "Applications/Release1a",
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
}

All the variables in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Start a planned release

To start a planned release, send this request:

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

Using the following parameters:

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

releaseId

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

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

Get active tasks

To retrieve a list of active tasks from a release, send this request:

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

Using the following parameters:

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

releaseId

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

The response contains a list of active tasks:

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

[ {
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "startDate" : "2019-08-22T19:56:47.375+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

[].attachments

Array

List of file attachments on this task.

[].status

String

The state the task is in.

[].team

String

The name of the team this task is assigned to.

[].waitForScheduledStartDate

Boolean

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

[].delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

[].precondition

String

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

[].failuresCount

Number

The number of times this task has failed.

[].variableMapping

Object

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

[].tags

Array

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

Assign a task to a user

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

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

Using the following parameters:

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

taskId

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

username

The user name of the assigned user

The response contains the task as JSON:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Add a comment to a task

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/comment

{
  "comment" : "Important step in our pipeline"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/comment' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

taskId

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

comment

String

The comment to associate with the action

The response contains the modified task with the added comment:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Commentab50f547b6404b58b8c0fa3b299b5481",
    "type" : "xlrelease.Comment",
    "text" : "Important step in our pipeline",
    "author" : "admin",
    "date" : "2019-08-22T19:56:54.609+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false
}

Complete a task

To complete a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/complete

{
  "comment" : "Task completed!"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/complete' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

taskId

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

comment

String

The comment to associate with the action

The response contains the completed task with the added comment.

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:51.822+02:00",
  "endDate" : "2019-08-22T19:56:51.878+02:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Commentd1f25dc6b2fe4569b386e77181c030ed",
    "type" : "xlrelease.Comment",
    "text" : "Task completed!",
    "author" : "admin",
    "date" : "2019-08-22T19:56:51.902+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "COMPLETED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

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/Release1a/Phase1a/Task1a/reopen

{
  "comment" : "Reopen a task that has been completed in advance."
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/reopen' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Commentd4acf01b1a2c48749c602fcfd7e8165e",
    "type" : "xlrelease.Comment",
    "text" : "Reopen a task that has been completed in advance.",
    "author" : "admin",
    "date" : "2019-08-22T19:56:53.764+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Fail a task

To fail a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/fail

{
  "comment" : "Task failed :-("
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/fail' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

taskId

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

comment

String

The comment to associate with the action

The response contains the failed task with the added comment:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:53.397+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Commenteb4410e28540428c9e1de9c53e8ac4ed",
    "type" : "xlrelease.Comment",
    "text" : "Task failed :-(",
    "author" : "admin",
    "date" : "2019-08-22T19:56:53.517+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "FAILED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 1,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Retry a failed task

To retry a failed task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/retry

{
  "comment" : "Retry failed task."
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/retry' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:51.322+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Comment9867a01e25ef450da8805fdb0496468b",
    "type" : "xlrelease.Comment",
    "text" : "Retry failed task.",
    "author" : "admin",
    "date" : "2019-08-22T19:56:51.353+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Skip a task

To skip a task, send this request:

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/skip

{
  "comment" : "Task skipped"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/skip' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

taskId

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

comment

String

The comment to associate with the action

The response contains the skipped task and the added comment:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "owner" : "admin",
  "startDate" : "2019-08-22T19:56:54.730+02:00",
  "endDate" : "2019-08-22T19:56:54.859+02:00",
  "flagStatus" : "OK",
  "flagComment" : "",
  "overdueNotified" : false,
  "comments" : [ {
    "id" : "Applications/Release1a/Phase1a/Task1a/Comment1010eb31c19f460da2c147e152f2cc10",
    "type" : "xlrelease.Comment",
    "text" : "Task skipped",
    "author" : "admin",
    "date" : "2019-08-22T19:56:54.877+02:00"
  } ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "SKIPPED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Start a task that is waiting for input

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/start

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

Using the following parameters:

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

taskId

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

variables

Array

List of variables

The response contains the task updated:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.UserInputTask",
  "title" : "This task value1",
  "startDate" : "2019-08-22T19:56:54.123+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "IN_PROGRESS",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false,
  "variables" : [ "Applications/Release1a/Variable1a" ]
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

variables

Array

List of variables

Abort a release

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

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

Using the following parameters:

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

releaseId

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

The response contains the release aborted:

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

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Running release, don't abort me",
  "endDate" : "2019-08-22T19:56:44.388+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableEndDate" : "2019-08-22T19:56:44.388+02:00",
  "realFlagStatus" : "OK",
  "status" : "ABORTED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault"
}

Resume release

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

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

Using the following parameters:

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

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "startDate" : "2019-08-22T19:56:44.023+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release1a/Phase1a",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release1a/Phase1a",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release1a/Phase1a/Task1a",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release1a/Phase1a/Task1a",
      "endDate" : "2019-08-22T19:56:43.844+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release1a/Phase1a",
      "attachments" : [ ],
      "status" : "SKIPPED",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false
    } ],
    "release" : "Applications/Release1a",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release1a/Phase2b",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release1a/Phase2b",
    "startDate" : "2019-08-22T19:56:44.027+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release1a/Phase2b/Task1a",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release1a/Phase2b/Task1a",
      "startDate" : "2019-08-22T19:56:44.031+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release1a/Phase2b",
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false
    } ],
    "release" : "Applications/Release1a",
    "status" : "IN_PROGRESS"
  } ],
  "queryableStartDate" : "2019-08-22T19:56:44.023+02:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

Restart a phase

Restarts the release from a given phase and task.

HTTP Request
POST /api/v1/releases/Applications/Release1a/restart?fromPhaseId=Applications/Release1a/Phase1a&fromTaskId=Applications/Release1a/Phase1a/Task1a&phaseVersion=ALL&resume=true

fromPhaseId=Applications%2FRelease1a%2FPhase1a&fromTaskId=Applications%2FRelease1a%2FPhase1a%2FTask1a&phaseVersion=ALL&resume=true
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/restart?fromPhaseId=Applications/Release1a/Phase1a&fromTaskId=Applications/Release1a/Phase1a/Task1a&phaseVersion=ALL&resume=true' -i -X POST -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/releases/Applications/Release1a/restart?fromPhaseId=Applications/Release1a/Phase1a&fromTaskId=Applications/Release1a/Phase1a/Task1a&phaseVersion=ALL&resume=true' 'Accept:application/json'

Using the following parameters:

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

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "startDate" : "2019-08-22T19:56:45.050+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Release1a/Phase1a",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release1a/Phase1a",
    "startDate" : "2019-08-22T19:56:44.991+02:00",
    "endDate" : "2019-08-22T19:56:44.991+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release1a/Phase1a/Task1a",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release1a/Phase1a/Task1a",
      "startDate" : "2019-08-22T19:56:44.858+02:00",
      "endDate" : "2019-08-22T19:56:44.996+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release1a/Phase1a",
      "attachments" : [ ],
      "status" : "SKIPPED",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false
    } ],
    "release" : "Applications/Release1a",
    "status" : "SKIPPED"
  }, {
    "id" : "Applications/Release1a/Phase24afdc0538424aa095496485f2f5dc87",
    "type" : "xlrelease.Phase",
    "title" : "Applications/Release1a/Phase1a (2)",
    "startDate" : "2019-08-22T19:56:45.050+02:00",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ {
      "id" : "Applications/Release1a/Phase24afdc0538424aa095496485f2f5dc87/Task1a",
      "type" : "xlrelease.Task",
      "title" : "Applications/Release1a/Phase1a/Task1a",
      "startDate" : "2019-08-22T19:56:45.050+02:00",
      "flagStatus" : "OK",
      "overdueNotified" : false,
      "comments" : [ ],
      "container" : "Applications/Release1a/Phase24afdc0538424aa095496485f2f5dc87",
      "attachments" : [ ],
      "status" : "IN_PROGRESS",
      "waitForScheduledStartDate" : true,
      "delayDuringBlackout" : false,
      "postponedDueToBlackout" : false,
      "hasBeenFlagged" : false,
      "hasBeenDelayed" : false,
      "failuresCount" : 0,
      "variableMapping" : { },
      "tags" : [ ],
      "dueSoonNotified" : false
    } ],
    "release" : "Applications/Release1a",
    "status" : "IN_PROGRESS",
    "originId" : "Applications/Release1a/Phase1a"
  } ],
  "queryableStartDate" : "2019-08-22T19:56:45.050+02:00",
  "realFlagStatus" : "OK",
  "status" : "IN_PROGRESS",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 1,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    },
    "blackout" : { }
  }
}

Building templates and releases

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

Templates

Create a template

To create a new template, send this request:

HTTP Request
POST /api/v1/templates/

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "scheduledStartDate" : "2019-08-22T19:56:55.501+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:55.501+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null
  }
}
Curl
$ curl 'http://localhost:5516/api/v1/templates/' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "scheduledStartDate" : "2019-08-22T19:56:55.501+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:55.501+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null
  }
}'
HTTPie
$ echo '{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "scheduledStartDate" : "2019-08-22T19:56:55.501+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:55.501+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "globalVariables" : null
  }
}' | http POST 'http://localhost:5516/api/v1/templates/' 'Content-Type:application/json' 'Accept:application/json'

Using the following fields:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

The response contains the template JSON:

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

{
  "id" : "Applications/Releasef4b6229826a044b3b26af37d7cb72ef5",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "scheduledStartDate" : "2019-08-22T19:56:55.501+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ {
    "id" : "Applications/Releasef4b6229826a044b3b26af37d7cb72ef5/Team2f961ac2644944ddbd1fc776ffd8fd92",
    "type" : "xlrelease.Team",
    "teamName" : "Template Owner",
    "members" : [ "admin" ],
    "roles" : [ ],
    "permissions" : [ "template#edit", "template#view", "template#edit_triggers", "template#edit_security", "template#create_release" ]
  }, {
    "id" : "Applications/Releasef4b6229826a044b3b26af37d7cb72ef5/Team110357e59344bca308f40b3dc551c8",
    "type" : "xlrelease.Team",
    "teamName" : "Release Admin",
    "members" : [ ],
    "roles" : [ ],
    "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "template#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ]
  } ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ {
    "id" : "Applications/Releasef4b6229826a044b3b26af37d7cb72ef5/Phase5d9680907cb64685b9b391d417f6e154",
    "type" : "xlrelease.Phase",
    "title" : "New Phase",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "tasks" : [ ],
    "release" : "Applications/Releasef4b6229826a044b3b26af37d7cb72ef5",
    "status" : "PLANNED"
  } ],
  "queryableStartDate" : "2019-08-22T19:56:55.501+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "riskProfile" : "Configuration/riskProfiles/RiskProfileDefault",
  "$metadata" : {
    "security" : {
      "permissions" : [ "template#edit", "template#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
      "teams" : [ "Template Owner" ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Import a template, serialized in XLR format

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

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

Phases

The following operations are valid for both templates and releases.

Add a phase to a release

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

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

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

Using the following parameters:

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

id

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

id

String

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

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

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

originId

String

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

The response contains the created phase:

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

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

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

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

originId

String

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

Copy a phase in a release

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

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

  • You cannot copy completed phase

Usage example:

HTTP Request
POST /api/v1/phases/Applications/Release1a/Phase1a/copy?targetPosition=1

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

Using the following path parameters:

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

{
  "id" : "Applications/Release1a/Phaseddb588819280467d8454f3ffdef53d3b",
  "type" : "xlrelease.Phase",
  "title" : "Applications/Release1a/Phase1a (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ {
    "id" : "Applications/Release1a/Phaseddb588819280467d8454f3ffdef53d3b/Task1a",
    "type" : "xlrelease.GateTask",
    "title" : "Applications/Release1a/Phase1a/Task1a",
    "flagStatus" : "OK",
    "overdueNotified" : false,
    "comments" : [ ],
    "container" : "Applications/Release1a/Phaseddb588819280467d8454f3ffdef53d3b",
    "attachments" : [ ],
    "status" : "PLANNED",
    "waitForScheduledStartDate" : true,
    "delayDuringBlackout" : false,
    "postponedDueToBlackout" : false,
    "hasBeenFlagged" : false,
    "hasBeenDelayed" : false,
    "failuresCount" : 0,
    "variableMapping" : { },
    "tags" : [ ],
    "dueSoonNotified" : false,
    "conditions" : [ ],
    "dependencies" : [ ]
  } ],
  "release" : "Applications/Release1a",
  "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/Release1a/Phase1a

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

Using the following path parameters:

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

phaseId

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

Using the following query parameters:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

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

originId

String

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

The response contains the updated phase:

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

{
  "id" : "Applications/Release1a/Phase1a",
  "type" : "xlrelease.Phase",
  "title" : "new title",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "tasks" : [ ],
  "release" : "Applications/Release1a",
  "status" : "PLANNED",
  "color" : "#FFFF00"
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Phase'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

tasks

Array

The list of tasks in this phase.

release

Varies

The release this phase belongs to.

status

String

The state the phase is in.

color

String

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

originId

String

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

Tasks

Add a task in a phase or in another task

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/tasks

{
  "id" : "null",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task"
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/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/Release1a/Phase1a/tasks' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

containerId

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

id

String

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

type

String

This field represents type of 'xlrelease.Task'.

title

String

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

The response contains the created task:

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

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

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

variables

Array

List of variables

Add a task to a specific position inside a phase

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

HTTP Request
POST /api/v1/phases/Applications/Release1a/Phase1a/tasks?position=0

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/phases/Applications/Release1a/Phase1a/tasks?position=0' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false
}'
HTTPie
$ echo '{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.UserInputTask",
  "title" : "input task",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : false
}' | http POST 'http://localhost:5516/api/v1/phases/Applications/Release1a/Phase1a/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 24. /api/v1/phases/{phaseId}/tasks
Parameter Description

phaseId

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

id

String

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

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

comments

Array

The comments on the task.

container

Varies

The phase or task this task is contained in.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

The response contains the created task:

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

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

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

variables

Array

List of variables

Copy a task to a specific position inside a phase

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/copy/?targetContainerId=Applications/Release1a/Phase1a&targetPosition=1

targetContainerId=Applications%2FRelease1a%2FPhase1a&targetPosition=1
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/copy/?targetContainerId=Applications/Release1a/Phase1a&targetPosition=1' -i -X POST
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/copy/?targetContainerId=Applications/Release1a/Phase1a&targetPosition=1'

Using the following path parameters:

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

{
  "id" : "Applications/Release1a/Phase1a/Task7db72a1d16f040dc9401e458f186cc09",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release1a/Phase1a/Task1a (copy)",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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/Release1a/Phase1a/Task1a

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

Using the following parameters:

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

taskId

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

id

String

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

type

String

This field represents type of 'xlrelease.Task'.

title

String

The title of the task.

The response contains the updated task:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.Task",
  "title" : "new title",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

Task types

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

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

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

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

Task Task Type Extension Type

Gate

xlrelease.GateTask

-

Manual

xlrelease.Task

-

User Input

xlrelease.UserInputTask

-

Create Release

xlrelease.CreateReleaseTask

-

Jenkins

xlrelease.CustomScriptTask

jenkins.Build

JIRA Create Issue

xlrelease.CustomScriptTask

jira.CreateIssue

JIRA Query

xlrelease.CustomScriptTask

jira.Query

Jira Update Issue

xlrelease.CustomScriptTask

jira.UpdateIssue

Jira Update Issues

xlrelease.CustomScriptTask

jira.UpdateIssues

Jira Update Issues by Query

xlrelease.CustomScriptTask

jira.UpdateIssuesByQuery

Jira Query

xlrelease.CustomScriptTask

jira.Query

Notification

xlrelease.NotificationTask

-

Remote Unix script

xlrelease.CustomScriptTask

remoteScript.Unix

Remote Win script

xlrelease.CustomScriptTask

remoteScript.Windows

Remote Win SSH script

xlrelease.CustomScriptTask

remoteScript.WindowsSsh

Remote Z/os script

xlrelease.CustomScriptTask

remoteScript.Zos

Jython script

xlrelease.ScriptTask

-

Groovy script

xlrelease.GroovyScriptTask

-

Webhook XML

xlrelease.CustomScriptTask

webhook.XmlWebhook

Webhook JSON

xlrelease.CustomScriptTask

webhook.JsonWebhook

XL Deploy

xlrelease.CustomScriptTask

xldeploy.Deploy
Change task type

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/changeType?targetType=xlrelease.GateTask

targetType=xlrelease.GateTask
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/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 27. /api/v1/tasks/{taskId}/changeType
Parameter Description

taskId

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

The response contains the updated task:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a",
  "type" : "xlrelease.GateTask",
  "title" : "Applications/Release1a/Phase1a/Task1a",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "comments" : [ ],
  "container" : "Applications/Release1a/Phase1a",
  "attachments" : [ ],
  "status" : "PLANNED",
  "waitForScheduledStartDate" : true,
  "delayDuringBlackout" : false,
  "postponedDueToBlackout" : false,
  "hasBeenFlagged" : false,
  "hasBeenDelayed" : false,
  "failuresCount" : 0,
  "variableMapping" : { },
  "tags" : [ ],
  "dueSoonNotified" : 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.

attachments

Array

List of file attachments on this task.

status

String

The state the task is in.

team

String

The name of the team this task is assigned to.

waitForScheduledStartDate

Boolean

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

delayDuringBlackout

Boolean

The task is to be delayed when a blackout period is active.

precondition

String

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

failuresCount

Number

The number of times this task has failed.

variableMapping

Object

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

tags

Array

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

conditions

Array

Conditions

dependencies

Array

Dependencies

Gate tasks

Add a condition to a gate task

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

HTTP Request
POST /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/conditions

{
  "title" : "this must be true to go on",
  "checked" : false
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/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 28. /api/v1/tasks/{taskId}/conditions
Parameter Description

taskId

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

The response contains the created gate condition:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a/GateCondition70750459c75448f798f401546dbce39c",
  "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/Release1a/Phase1a/Task1a/GateCondition1

{
  "title" : "my first condition",
  "checked" : true
}
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/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 29. /api/v1/tasks/{conditionId}
Parameter Description

conditionId

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

The response contains the updated gate condition:

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

{
  "id" : "Applications/Release1a/Phase1a/Task1a/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/Release1a/Phase1a/Task1a/GateCondition1
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/GateCondition1' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/GateCondition1'

Using the following parameters:

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

conditionId

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

You will receive this empty response:

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

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

HTTP Request
POST /api/v1/tasks/Applications/Release2b/Phase1a/Task1a/dependencies/Applications/Release1a/Phase1a/Task1a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release2b/Phase1a/Task1a/dependencies/Applications/Release1a/Phase1a/Task1a' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json'
HTTPie
$ http POST 'http://localhost:5516/api/v1/tasks/Applications/Release2b/Phase1a/Task1a/dependencies/Applications/Release1a/Phase1a/Task1a' 'Content-Type:application/json' 'Accept:application/json'

Using the following parameters:

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

taskId

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

targetId

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

The response contains the new dependency:

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

{
  "id" : "Applications/Release2b/Phase1a/Task1a/Dependency1f157401e9de4172be5d75967e66d7bf",
  "type" : "xlrelease.Dependency",
  "gateTask" : "Applications/Release2b/Phase1a/Task1a",
  "target" : "Applications/Release1a/Phase1a/Task1a",
  "targetId" : "Applications/Release1a/Phase1a/Task1a",
  "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/Release1a/Phase1a/Task1a/Dependency1a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/Dependency1a' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/Dependency1a'

Using the following parameters:

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

Attachments

Download an attachment

To download an attachment, send this request:

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

Using the following parameter:

Table 33. /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/Release1a/Phase1a/Task1a/attachments

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


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


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


-----011000010111000001101001--
' | http POST 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/attachments' 'Content-Type:multipart/form-data;boundary=---011000010111000001101001' 'Accept:multipart/form-data, application/json'

Using the following parameter:

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

[ {
  "id" : "Applications/Release1a/Attachment8518a342bbf7409b874a4706c9215ca8",
  "type" : "xlrelease.Attachment",
  "release" : "Applications/Release1a",
  "contentType" : "application/xml",
  "exportFilename" : "attachments/Attachment8518a342bbf7409b874a4706c9215ca8-Dummy.xml",
  "fileUri" : "sql:Applications%2FRelease1a%2FAttachment8518a342bbf7409b874a4706c9215ca8"
} ]

Delete attachment from a task

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

HTTP Request
DELETE /api/v1/tasks/Applications/Release1a/Phase1a/Task1a/attachments/Applications/Release1a/Attachment48e906e358594225bb6794c4a0e0038a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/attachments/Applications/Release1a/Attachment48e906e358594225bb6794c4a0e0038a' -i -X DELETE -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/attachments/Applications/Release1a/Attachment48e906e358594225bb6794c4a0e0038a' 'Accept:application/json'

Using the following parameters:

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

Properties

Update template properties

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

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

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

Using the following parameters:

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

templateId

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

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

The response the updated template:

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

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "Applications/Release1a",
  "scheduledStartDate" : "2019-08-22T19:56:55.371+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:55.371+02:00",
  "realFlagStatus" : "OK",
  "status" : "TEMPLATE",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Update release properties

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

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

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

Using the following parameters:

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

releaseId

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

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

The response contains the updated release:

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

{
  "id" : "Applications/Release1a",
  "type" : "xlrelease.Release",
  "title" : "new title",
  "scheduledStartDate" : "2019-08-22T19:56:45.599+02:00",
  "dueDate" : "2019-08-22T19:56:45.599+02:00",
  "flagStatus" : "OK",
  "overdueNotified" : false,
  "maxConcurrentReleases" : 100,
  "releaseTriggers" : [ ],
  "teams" : [ ],
  "memberViewers" : [ ],
  "roleViewers" : [ ],
  "attachments" : [ ],
  "phases" : [ ],
  "queryableStartDate" : "2019-08-22T19:56:45.599+02:00",
  "queryableEndDate" : "2019-08-22T19:56:45.599+02:00",
  "realFlagStatus" : "OK",
  "status" : "PLANNED",
  "tags" : [ ],
  "variables" : [ ],
  "calendarPublished" : false,
  "tutorial" : false,
  "abortOnFailure" : false,
  "allowConcurrentReleasesFromTrigger" : true,
  "runningTriggeredReleasesCount" : 0,
  "createdFromTrigger" : false,
  "extensions" : [ ],
  "autoStart" : false,
  "automatedResumeCount" : 0,
  "riskScore" : "000",
  "totalRiskScore" : "0000",
  "$metadata" : {
    "security" : {
      "permissions" : [ ],
      "teams" : [ ]
    },
    "globalVariables" : {
      "id" : "Configuration/variables/global",
      "type" : "xlrelease.GlobalVariables",
      "variables" : [ ]
    }
  }
}

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.Release'.

title

String

The title of the item.

description

String

The description of the item.

owner

String

The owner of the item.

scheduledStartDate

String

The date that the item is supposed to start.

dueDate

String

The date that the item is supposed to end.

startDate

String

The actual start date.

endDate

String

The actual end date.

plannedDuration

Number

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

flagStatus

String

Flags indicate that an item needs attention.

flagComment

String

The reason the item is flagged.

releaseTriggers

Array

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

teams

Array

The teams configured on the release.

attachments

Array

File attachments of the release.

phases

Array

The list of phases in the release.

realFlagStatus

String

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

status

String

The state the release is in.

tags

Array

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

variables

Array

List of variable CIs representing variables in this release or template

abortOnFailure

Boolean

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

allowConcurrentReleasesFromTrigger

Boolean

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

originTemplateId

String

The ID of the template that created this release.

createdFromTrigger

Boolean

True if release was created by a trigger.

scriptUsername

String

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

scriptUserPassword

String

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

extensions

Array

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

startedFromTaskId

String

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

autoStart

Boolean

If true, the release will automatically start at scheduledStartDate.

riskScore

String

Risk score

totalRiskScore

String

Total risk score

riskProfile

Varies

Risk profile used in risk calculations

Delete commands for task, phase, template, or release

Delete a task

To delete a task, send this request:

HTTP Request
DELETE /api/v1/tasks/Applications/Release1a/Phase1a/Task1a
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a' -i -X DELETE
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a'

Using the following parameters:

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

taskId

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

You will receive this empty response:

HTTP/1.1 204 No Content

Delete a phase

To delete a phase, send this request:

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

Using the following parameters:

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

Delete template

To delete a template, send this request:

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

Using the following parameters:

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

templateId

Full template identifier; for example, Applications/Release1

You will receive this empty response:

HTTP/1.1 204 No Content

Delete release

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

To delete a release, send this request:

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

Using the following parameters:

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

releaseId

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

You will receive this empty response:

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

Folders

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

Listing the root folders

To list the root folders, send this request:

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

You receive a response containing a list of folders:

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

[ {
  "id" : "Applications/Folder9bdc5fb24f16426e893219bee265cc19",
  "type" : "xlrelease.Folder",
  "$token" : "b555b4b8-8546-4496-a304-7b98e43c661e",
  "title" : "Microservices",
  "children" : [ {
    "id" : "Applications/Folder9bdc5fb24f16426e893219bee265cc19/Folderc21dd31b5d7b413f8de40f2780362470",
    "type" : "xlrelease.Folder",
    "$token" : "05a8f145-8947-458c-b7d5-f12cb766a1a7",
    "title" : "Invoice processing service",
    "children" : [ ],
    "$metadata" : {
      "security" : {
        "permissions" : [ "release#edit", "template#edit", "release#reassign_task", "template#edit_security", "template#create_release", "release#edit_security", "release#view", "release#start", "release#edit_blackout", "template#view", "folder#view", "template#edit_triggers", "folder#edit_security", "release#abort", "folder#edit", "release#edit_task" ],
        "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
      }
    }
  } ],
  "$metadata" : {
    "security" : {
      "permissions" : [ "release#edit", "template#edit", "release#reassign_task", "template#edit_security", "template#create_release", "release#edit_security", "release#view", "release#start", "release#edit_blackout", "template#view", "folder#view", "template#edit_triggers", "folder#edit_security", "release#abort", "folder#edit", "release#edit_task" ],
      "teams" : [ "Template Owner", "Release Admin", "Folder Owner" ]
    }
  }
} ]

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

Path Type Description

[].id

String

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

[].type

String

This field represents type of 'xlrelease.Folder'.

[].title

String

User provided title of the folder

[].children

Array

Sub-folders of this folder

Creating folders

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

For example, to create a top-level folder titled "New folder", send this request:

HTTP Request
POST /api/v1/folders/Applications

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

Using the following parameters:

Path Type Description

id

Null

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

type

String

This field represents type of 'xlrelease.Folder'.

title

String

User provided title of the folder

children

Array

Sub-folders of this folder

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

Listing folders inside another folder

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

HTTP Request
GET /api/v1/folders/Applications/Folderdda5dcc570014aba9d4eba767371e90d/list
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folderdda5dcc570014aba9d4eba767371e90d/list' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folderdda5dcc570014aba9d4eba767371e90d/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 42. /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 -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/Folder46fae36644304dd0bd87b3938fc4a867/Folder495b1feb6434ef18d209ad0d772029a
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder46fae36644304dd0bd87b3938fc4a867/Folder495b1feb6434ef18d209ad0d772029a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder46fae36644304dd0bd87b3938fc4a867/Folder495b1feb6434ef18d209ad0d772029a' 'Accept:application/json'

Using the following parameters:

Table 43. /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/Folder442444112f694daf9039828a435117b0/Foldera9d26a51e7c34ed1b6874c2acca7bd9b/templates
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder442444112f694daf9039828a435117b0/Foldera9d26a51e7c34ed1b6874c2acca7bd9b/templates' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder442444112f694daf9039828a435117b0/Foldera9d26a51e7c34ed1b6874c2acca7bd9b/templates' 'Accept:application/json'

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

Using the following parameters:

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

folderId

The id of the folder
Parameter Description

depth

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

page

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

resultsPerPage

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

Move templates

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

To move a template from one folder to another, send this request:

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

Using the following parameters:

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

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

Using the following parameters:

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

Using the following parameters:

Table 47. /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/Folder97d31ad55ced48139fafd60c68922c0f/move?newParentId=Applications/Foldercff019158333438b859b77915a76d6c6

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

Using the following parameters:

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

folderId

The id of the folder to move
Parameter Description

newParentId

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

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

Rename folders

To rename a folder, send this request:

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

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

Using the following parameters:

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

folderId

The id of the folder to move
Parameter Description

newName

The new name of the folder

Working with variables

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

Types of variables

Table 50. 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/Release1a/variables
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/variables' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release1a/variables' 'Accept:application/json'

Using the following path parameters:

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

releaseId

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

The response contains a list of variables:

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

[ {
  "id" : "Applications/Release1a/Variable1a",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "value1"
} ]

All the variables in the response and their description:

Path Type Description

[].id

String

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

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

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

[].requiresValue

Boolean

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

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

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

Find release/template variable by ID

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

HTTP Request
GET /api/v1/releases/Applications/Release1a/Variable1a
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/Variable1a' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release1a/Variable1a' 'Accept:application/json'

Using the following path parameters:

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

variableId

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

All the fields in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.StringVariable'.

key

String

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

requiresValue

Boolean

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

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

label

String

Label of the variable

description

String

Description of the variable

valueProvider

Varies

Configuration of the variable values provider

value

String

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

Create new release/template variable

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

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

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

Using the following path parameters:

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

releaseId

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

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/Release1a/Variable1a
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/Variable1a' -i -X DELETE -H 'Accept: application/json'
HTTPie
$ http DELETE 'http://localhost:5516/api/v1/releases/Applications/Release1a/Variable1a' 'Accept:application/json'

Using the following path parameters:

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

variableId

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

You will receive this empty response:

HTTP/1.1 204 No Content

Update variable

To update a single variable, send this request:

HTTP Request
PUT /api/v1/releases/Applications/Release1a/Variable1a

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

Using the following path parameters:

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

variableId

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

Update variables

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

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

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

Using the following path parameters:

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

releaseId

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

The response contains a list of updated variables:

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

[ {
  "id" : "Applications/Release1a/Variable1a",
  "type" : "xlrelease.StringVariable",
  "key" : "var1",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "updated value"
} ]

Advanced

Variable values

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

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

Using the following path parameters:

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

variableId

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

The response contains the list of values:

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

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

Verify variable usage

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

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

Using the following path parameters:

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

variableId

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

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

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

false

Replacing a variable

To replace one or more variables, send this request:

HTTP Request
POST /api/v1/releases/Applications/Release1a/Variable1a/replace

{
  "variable" : "${var2}",
  "value" : "value2"
}
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/Variable1a/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/Release1a/Variable1a/replace' 'Content-Type:application/json'

Using the following path parameters:

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

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/Release1a/Phase1a/Task1a/variables
Curl
$ curl 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/variables' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/tasks/Applications/Release1a/Phase1a/Task1a/variables' 'Accept:application/json'

With the following path parameters:

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

taskId

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

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

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

[ {
  "id" : "Applications/Release1a/Variable1a",
  "type" : "xlrelease.StringVariable",
  "key" : "title",
  "requiresValue" : true,
  "showOnReleaseStart" : true,
  "value" : "value1"
} ]

All the fields in the response and their description:

Path Type Description

[].id

String

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

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

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

[].requiresValue

Boolean

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

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

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

Global variables

List global variables

To list all the global variables, send this request:

HTTP Request
GET /api/v1/config/Configuration/variables/global
Curl
$ curl 'http://localhost:5516/api/v1/config/Configuration/variables/global' -i -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-Type: application/json
Content-Length: 203

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

All the fields in the response and their description:

Path Type Description

[].id

String

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

[].type

String

This field represents type of 'xlrelease.StringVariable'.

[].key

String

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

[].requiresValue

Boolean

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

[].showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

[].label

String

Label of the variable

[].description

String

Description of the variable

[].valueProvider

Varies

Configuration of the variable values provider

[].value

String

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

Find global variable by ID

To obtain a specific global variable, 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 -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 61. /api/v1/config/{variableId}
Parameter Description

variableId

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

The response contains the global variable:

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

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

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,
  "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,
  "valueProvider" : null
}'
HTTPie
$ echo '{
  "id" : null,
  "key" : "global.newVar",
  "type" : "xlrelease.StringVariable",
  "requiresValue" : false,
  "showOnReleaseStart" : false,
  "value" : "new value",
  "label" : null,
  "description" : 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-Type: application/json
Content-Length: 236

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

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

Using the following path parameters:

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

variableId

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

All the variables in the response and their description:

Path Type Description

id

String

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

type

String

This field represents type of 'xlrelease.StringVariable'.

key

String

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

requiresValue

Boolean

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

showOnReleaseStart

Boolean

Shows if this variable will be shown on create release page

label

String

Label of the variable

description

String

Description of the variable

valueProvider

Varies

Configuration of the variable values provider

value

String

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

The response contains the updated global variable:

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

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

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

Shared 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
Curl
$ curl 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/config/byTypeAndTitle?configurationType=jira.Server&title=my%20JIRA%20server' 'Accept:application/json'

Using the following parameters:

Parameter Description

configurationType

Type of the Configuration object

title

The title of the Configuration object

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

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

[ {
  "id" : "Configuration/Custom/Configuration2d79d45facfe4fcd869d16cd9072d4ee",
  "type" : "jira.Server",
  "title" : "my JIRA server"
} ]

Get configuration object

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

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

Using the following parameters:

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

{
  "id" : "Configuration/Custom/Configurationdde1762bbe374e4d9797b73c70b3c7a0",
  "type" : "jira.Server",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "{aes:v0}FbCmNcKBHOcDaD/zxR5pYjcs/odzcIlUUCwypRC/2sc=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}Dmyr6jER6SiTWMUkAj4myMxOCb9CLPyU7zVlOEGEF1wSUZfgUWS/JhsWT50D6D6a"
}

Create configuration

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

HTTP Request
POST /api/v1/config

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

The response contains the created configuration object:

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

{
  "id" : "Configuration/Custom/Configuration7f30b95d9d3647c59da3058031ca98c6",
  "type" : "jira.Server",
  "title" : "Jira server configuration",
  "url" : "http://localhost:4323/jira",
  "username" : "jira username",
  "password" : "{aes:v0}0dt4pGjCi0fM9hxjtLtfW8dyMcslQ1dFDamvOuJ3hGo=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}2Pj+VC/h2/kanNUqeMd88HrOD+vdx9324of+10+VO9k+y0ozjlL2DR1gDAAMPU8a"
}

Update configuration

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

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

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

Using the following parameters:

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

{
  "id" : "Configuration/Custom/Configuration52f07888f5ae4ea8bfe8f471d97bbba5",
  "type" : "jira.Server",
  "title" : "Changed jira title",
  "url" : "http://localhost:8438/jira-server",
  "username" : "jira username",
  "password" : "{aes:v0}qXjQqXEvh8d4aQ8yr6tzNDQ5crQfkdrAsnY/ImF2MYo=",
  "proxyHost" : "http://localhost",
  "proxyPort" : "3533",
  "proxyUsername" : "proxyUsername value",
  "proxyPassword" : "{aes:v0}jUjzw0Fm/D4WpbJ8xVDmyrHuR0rW+KLg8PLd8+qgeY9DJRUHkeL+XOyvq5gFhF+z"
}

Delete configuration

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

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

Using the following parameters:

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

Working with DSL

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

triggers, 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/Release1a
Curl
$ curl 'http://localhost:5516/api/v1/dsl/export/Applications/Release1a' -i
HTTPie
$ http GET 'http://localhost:5516/api/v1/dsl/export/Applications/Release1a'

Using the following parameters:

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

templateId

Full template identifier; for example, Applications/Release1

You will receive DSL code that defines a template, in the attachment:

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="Releasefile.groovy"
Content-Type: text/plain;charset=UTF-8
Content-Length: 1630

// Exported from:        http://jenkins-slave6-xlr.xebialabs.com:4516/#/templates/Release1a/releasefile
// XL Release version:   7.5.8-SNAPSHOT
// Date created:         Thu Aug 22 19:56:34 CEST 2019

def server(type, title) {
    def cis = configurationApi.searchByTypeAndTitle(type, title)
    if (cis.isEmpty()) {
        throw new RuntimeException("No CI found for the type '${type}' and title '${title}'")
    }
    if (cis.size() > 1) {
        throw new RuntimeException("More than one CI found for the type '${type}' and title '${title}'")
    }
    cis.get(0)
}
def jiraServer1 = server('jira.Server','XL JIRA test instance')
xlr {
  release('Sample XLR template') {
    variables {
      stringVariable('manualTaskTitle') {
        value 'Manual task title'
      }
      passwordVariable('jiraPassword') {
        value '{aes:v0}OyH3P1DfWA/mH8P7qerEdJAX0uhM8XLnem08NF+jzNw='
      }
      mapVariable('foundIssues') {

      }
    }
    description 'XLR template to demonstrate DSL export functionality'
    // no DSL renderer found for property 'riskProfile' of type 'xlrelease.Release'
    phases {
      phase('Sample phase') {
        tasks {
          manual('${manualTaskTitle}') {

          }
          custom('Query JIRA') {
            script {
              type 'jira.Query'
              jiraServer jiraServer1
              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 -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-Type: application/json
Content-Length: 466

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

You can also search for users using query parameters:

HTTP Request
GET /api/v1/users?email=email@mail.com
Curl
$ curl 'http://localhost:5516/api/v1/users?email=email@mail.com' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/users?email=email@mail.com' '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.

page

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

resultsPerPage

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

The response fields explained:

Path Type Description

[].username

String

The username.

[].external

Boolean

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

[].profileId

String

The CI ID of the user profile.

[].email

Varies

The email of the user.

[].fullName

Varies

The full name of the user.

[].loginAllowed

Boolean

Whether user is allowed to login or not

[].dateFormat

Varies

The profile setting for the date format.

[].timeFormat

Varies

The profile setting for the time format.

[].firstDayOfWeek

Number

The profile setting for the first day of week.

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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/users/user1' 'Accept:application/json'
Table 68. /api/v1/users/{username}
Parameter Description

username

The username to retrieve information from.

Create new users

You can create single users as follows:

HTTP Request
POST /api/v1/users/user2

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

email

String

The email of the user.

fullName

String

The full name of the user.

loginAllowed

Boolean

The login permission for the user.

dateFormat

Varies

The profile setting for the date format.

timeFormat

Varies

The profile setting for the time format.

firstDayOfWeek

Number

The profile setting for the first day of week.
Table 69. /api/v1/users/{username}
Parameter Description

username

The username from the user to be created.

User preferences

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

username

The username from the user to be updated.

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

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

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

HTTP Request
PUT /api/v1/users

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

Change password

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

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

currentPassword

String

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

newPassword

String

The new password of the user.
Table 72. /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 73. /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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/global-permissions' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 202

[ "admin", "security#edit", "report#view", "template#create", "release#create", "reports#view", "global_variables#edit", "folder#create_top_level", "global_calendar#edit_blackout", "risk_profile#edit" ]

List all roles

To list global roles, execute this command:

HTTP Request
GET /api/v1/roles?page=0&resultsPerPage=2
Curl
$ curl 'http://localhost:5516/api/v1/roles?page=0&resultsPerPage=2' -i -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-Type: application/json
Content-Length: 277

[ {
  "name" : "Developers",
  "permissions" : [ ],
  "principals" : [ {
    "username" : "devans",
    "fullname" : null
  } ]
}, {
  "name" : "Operations",
  "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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/roles/Developers' 'Accept:application/json'

with the following path parameters:

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

roleName

Name of the role

which returns:

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

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

Response fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

Create a new role

To create a single role, execute this command:

HTTP Request
POST /api/v1/roles/Testers

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

with the following path parameters:

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

roleName

Name of the role

Request fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

Create a list of roles

To create multiple roles, execute this command:

HTTP Request
POST /api/v1/roles

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

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]permissions

Array

This field contains permissions granted to the role.

[]principals

Array

This field contains principals.

Update a role

To update a role, execute this command:

HTTP Request
PUT /api/v1/roles/Developers

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

with the following path parameters:

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

roleName

Name of the role

Request fields and their description:

Path Type Description

name

String

This field contains name of the role.

permissions

Array

This field contains permissions granted to the role.

principals

Array

This field contains principals.

Update a list of roles

To update a list of roles, execute this command:

HTTP Request
PUT /api/v1/roles

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

Request fields and their description:

Path Type Description

[]name

String

This field contains name of the role.

[]permissions

Array

This field contains permissions granted to the role.

[]principals

Array

This field contains principals.

Rename role

To rename a role, execute this command:

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

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

with the following path parameters:

Table 77. /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 78. /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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/permissions' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 331

[ "folder#view", "folder#edit", "folder#edit_security", "template#create_release", "template#view", "template#edit", "template#edit_security", "template#edit_triggers", "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#reassign_task", "release#edit_blackout" ]

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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/permissions' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 277

[ "template#create_release", "template#view", "template#edit", "template#edit_security", "template#edit_triggers", "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#reassign_task", "release#edit_blackout" ]

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 -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/permissions' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 164

[ "release#view", "release#edit", "release#edit_security", "release#start", "release#abort", "release#edit_task", "release#reassign_task", "release#edit_blackout" ]

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/Folder6bd95026e6ef4f048b48876ba54a2494/teams
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder6bd95026e6ef4f048b48876ba54a2494/teams' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/folders/Applications/Folder6bd95026e6ef4f048b48876ba54a2494/teams' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1258

[ {
  "id" : "Applications/Folder6bd95026e6ef4f048b48876ba54a2494/Teamed372ae45b55447faf6e878af9397f17",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "folder#view", "folder#edit_security", "folder#edit" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder6bd95026e6ef4f048b48876ba54a2494/Team2e8492dfafa647d19d3be48e90d01c43",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "folder#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder6bd95026e6ef4f048b48876ba54a2494/Team16c1265f520649db8041fa6225eaab12",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "template#edit", "template#view", "folder#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

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

[]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/Release1a/teams
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release1a/teams' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/templates/Applications/Release1a/teams' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 469

[ {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

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

[]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/Release1a/teams
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/teams' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/releases/Applications/Release1a/teams' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 469

[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

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

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

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

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

[ {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Teamd069330b4a374084977e1cf89e6fb787",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "folder#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team8827d4fb1acf4c6cbf6531e270401905",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "template#edit", "template#view", "folder#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team191aded494f14e59891728eea21998be",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "folder#view", "folder#edit_security", "folder#edit", "release#edit" ],
  "systemTeam" : true
} ]
Curl
$ curl 'http://localhost:5516/api/v1/folders/Applications/Folder402c9888f8934202bb0fafc011426c98/teams' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '[ {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Teamd069330b4a374084977e1cf89e6fb787",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "folder#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team8827d4fb1acf4c6cbf6531e270401905",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "template#edit", "template#view", "folder#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team191aded494f14e59891728eea21998be",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "folder#view", "folder#edit_security", "folder#edit", "release#edit" ],
  "systemTeam" : true
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Teamd069330b4a374084977e1cf89e6fb787",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "folder#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team8827d4fb1acf4c6cbf6531e270401905",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "template#edit", "template#view", "folder#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team191aded494f14e59891728eea21998be",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "folder#view", "folder#edit_security", "folder#edit", "release#edit" ],
  "systemTeam" : true
} ]' | http POST 'http://localhost:5516/api/v1/folders/Applications/Folder402c9888f8934202bb0fafc011426c98/teams' 'Content-Type:application/json' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1274

[ {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Teamd069330b4a374084977e1cf89e6fb787",
  "teamName" : "Release Admin",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit", "release#start", "release#reassign_task", "release#edit_blackout", "folder#view", "release#edit_security", "release#abort", "release#view", "release#edit_task" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team8827d4fb1acf4c6cbf6531e270401905",
  "teamName" : "Template Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "template#edit", "template#view", "folder#view", "template#edit_triggers", "template#edit_security", "template#create_release" ],
  "systemTeam" : true
}, {
  "id" : "Applications/Folder402c9888f8934202bb0fafc011426c98/Team191aded494f14e59891728eea21998be",
  "teamName" : "Folder Owner",
  "members" : [ {
    "name" : "admin",
    "fullName" : "XL Release Administrator",
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "folder#view", "folder#edit_security", "folder#edit", "release#edit" ],
  "systemTeam" : true
} ]

See the following table for applicable path parameters:

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

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Set all teams and permissions on a template

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

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

[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]
Curl
$ curl 'http://localhost:5516/api/v1/templates/Applications/Release1a/teams' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]' | http POST 'http://localhost:5516/api/v1/templates/Applications/Release1a/teams' 'Content-Type:application/json' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 547

[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

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

[]permissions

Array

Names of the team permissions.

[]systemTeam

Boolean

Marks teams provided by the system.

Set all teams and permissions on a release

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

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

[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]
Curl
$ curl 'http://localhost:5516/api/v1/releases/Applications/Release1a/teams' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]'
HTTPie
$ echo '[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]' | http POST 'http://localhost:5516/api/v1/releases/Applications/Release1a/teams' 'Content-Type:application/json' 'Accept:application/json'
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 547

[ {
  "id" : "Applications/Release1a/Team1a",
  "teamName" : "Development team",
  "members" : [ {
    "name" : "john",
    "fullName" : null,
    "type" : "PRINCIPAL"
  }, {
    "name" : "mdavis",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#view" ],
  "systemTeam" : false
}, {
  "id" : "Applications/Release1a/Team2b",
  "teamName" : "Test team",
  "members" : [ {
    "name" : "fred",
    "fullName" : null,
    "type" : "PRINCIPAL"
  } ],
  "permissions" : [ "release#edit" ],
  "systemTeam" : false
} ]

See the following table for applicable path parameters:

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

[]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/Release70e2111883cd4977b0ea0069711d77f4/Risk
Curl
$ curl 'http://localhost:5516/api/v1/risks/Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk' 'Accept:application/json'

Using the following path parameters:

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

{
  "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
  "type" : "xlrelease.Risk",
  "score" : 30,
  "totalScore" : 30,
  "riskAssessments" : [ {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentf1cd8ab85cff420585f60222f7d9e9e3",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseDueDateRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 30,
    "headline" : "Release is overdue",
    "messages" : [ "Applications/Release1a is overdue since 2019-08-22T19:56:49.072" ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentd22f2ae0381840b5b442e1596b730253",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment81541664b1f443fe99234d29057d0365",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmenta874977f36b942229eba8c6591d11870",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailedRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentaa72949f66b548d087ff1efa384988e2",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/MoreThanOneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentca56f2331e6f47bf8c4f75368793d4fe",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor3Retries",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment5c55c580fbf241dfb6d41b3fcb63081e",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor5Retries",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment6bd9214f914040b8bff7bd9a09843e91",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithFourFiveOrSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentc2e9bbf5ad364eda82e79f34d6b62ca6",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseStatusFailingRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment5ad4975ec7f6447c837fe9df7fb8c8a1",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAtRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentd8a3fc36ef2045aebbd24345eedc205b",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor2Retries",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment66bb6cbfbe2d41f190bf466fbf1aa72f",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentdb9beba0bfad4874b30caf5a6a19dfb3",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/OneTaskOverDueRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment2e6c9406bc874e26a7b85a96c262620d",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessorMoreThan5Retries",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentb72daf8d4b194e90a8dec9f17966de3b",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentb782632796484a99b56441a5baf8f680",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/ReleaseFlaggedAttentionNeededRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment99dd7e1115234faca788c3c4e4b946c4",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment3e948f129cba4d08854d5d6e33402653",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithOneFlagAtRiskRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment92d6b2f487d141a895d33a63ecb486bd",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskRetriesRiskAssessor4Retries",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessment5206715e84e5471a8ad6008de5068b78",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithMoreThanSixFlagsAtRiskRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk",
    "score" : 0,
    "headline" : "Release is on track",
    "messages" : [ ]
  }, {
    "id" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/Risk/RiskAssessmentd4ca4dbd6d9c4786a889a84fe4b330d0",
    "type" : "xlrelease.RiskAssessment",
    "riskAssessorId" : "Applications/TaskWithTwoOrThreeFlagsNeedsAttentionRiskAssessor",
    "risk" : "Applications/Release70e2111883cd4977b0ea0069711d77f4/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 -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-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-Type: application/json
Content-Length: 1205

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

Listing all risk profiles

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

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

Fields in the response and their description:

Path Type Description

[].id

String

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

[].type

String

This field represents type of 'xlrelease.RiskProfile'.

[].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/RiskProfile4bfa540689734c1cad49bd7b515b140f
Curl
$ curl 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile4bfa540689734c1cad49bd7b515b140f' -i -H 'Accept: application/json'
HTTPie
$ http GET 'http://localhost:5516/api/v1/risks/profiles/Configuration/riskProfiles/RiskProfile4bfa540689734c1cad49bd7b515b140f' 'Accept:application/json'

Using the following path parameters:

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

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

Update risk profile

To update a risk profile, send this request:

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

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

Using the following path parameters:

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

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

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

Delete risk profile

To delete risk profile, send this request:

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

Using the following path parameters:

Table 89. /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 90. /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-Type: application/json
Content-Length: 1504

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

Listing all risk assessors

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

HTTP Request
GET /api/v1/risks/assessors
Curl
$ curl 'http://localhost:5516/api/v1/risks/assessors' -i -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-Type: application/json
Content-Length: 5893

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