External API Use Cases

Plutora’s API has a number of use cases to keep in mind.


User Management

As an administrator of Plutora, I want to manage a User’s Roles so that they can perform their job.

PATCH /Users/{id}

The editable parameters are:

  • Roles: {“Roles”:[“{UserId}”,”{RoleId}”]}
  • User Groups: {“Groups”:[“{UserId}”,”{UserGroupId}”]}
  • Portfolio Associations: {“OrganizationID”:”{UserId}”}
  • Account Statuses:
    • Active + Indefinitely: {“Status”:”Active”}
    • Active + Valid Until: {“Status”:”Active”,”ValidUntilDate”: “2021-07-29T13:18:01.340Z”}
    • Inactive: {“Status”:”Inactive”}
  • Receive Notifications:
    • On: {“CanReceiveEmailNotifications”:true}
    • Off: {“CanReceiveEmailNotifications”:false}
  • Allow Login:
    • On: {“CanLogin”:true}
    • Off: {“CanLogin”:false}


Environment Health Check

Health Variable

"health": 1,

0 – Unknown
1 – Online
2 – Offline
3 – Issue

Update Environment Health Check Status

POST /environmentHealthCheck

Request body in JSON format:

{
 "environmentId": "{id}",
 "health": 1,
 "testName": "test name"
}

Request in cURL format for Postman:

curl --location --request POST 'https://[Plutora API URL]/environmentHealthCheck' \
--header 'Authorization: Bearer [token]' \
--header 'Content-Type: application/json' \
--data-raw '{
 "environmentId": "[environment id]",
 "health": 1,
 "testName": "[test name]"
}'

Update Environment Health Check Status and attach a Log File

POST /environmentHealthCheck

Request in cURL format for Postman:

curl --location --request POST 'https://[Plutora API URL]/environmentHealthCheck' \
--header 'Authorization: Bearer [token]' \
--header 'Content-Type: application/json' \
--form 'logFile=@[log file name].txt' \
--form 'environmentId=[environment id]' \
--form 'health=1' \
--form 'testName=[test name]' 

Request in cURL format for Swagger:

curl -X POST --header "Content-Type: multipart/form-data" 
--header "Accept: application/json"
--header "Authorization: bearer [token]"
-F environmentId=[environment id]
-F health=[0-3]
-F testName=[test name]
-F "logFile=@[log file name].txt"
"https://[Plutora API URL]/environmentHealthCheck"

Release Use Cases

Manage Release Phases or Gates

As a Release Manager, I want to view the Phases and Gates from a Release:

Retrieve Phases or Gates from the Customization:

GET /WorkitemNames/Gates 
GET /WorkitemNames/Phases

Link a Phase or Gate to Release, using previously retrieved GUID of the Phases or Gates (workItemNameID):

POST /Releases/{id}/phases
POST /Releases/{id}/Gates
{"startDate": "string",
"endDate": "string",
"isIgnore": false,
"isIgnoreChild": false,
"workItemNameID": "string"}

Notice that your response body here will return you a newly generated GUID of the Phase or Gate associated with the Release. This is different to the generic GUID of Phase or Gate retrieved from Customization in the previous API request. You will need the new GUID of the Phase or Gate associated with the Release in the next step.

Notice that workItemNameId is the GUID of the Phase or Gate retrieved from the Customization (the first API call in this list).

Update Phase/Gate in Release:

PUT /Releases/{id}/phases/{id}
PUT /Releases/{id}/gates/{id}
{"id": "string",
"startDate": "string",
"endDate": "string",
"isIgnore": false,
"isIgnoreChild": false,
"workItemNameID": "string"}

Notice that workItemNameId is the GUID of the Phase or Gate retrieved from the Customization (the first API call in this list).

Retrieve the individual Phase or Gate associated with the Release:

GET /Releases/{id}/phases/{id}
GET /Releases/{id}/gates/{id}

Retrieve all Phases/Gates from Release:

GET /Releases/{id}/phases
GET /Releases/{id}/gates
 

Change Use Cases

Manage Delivery Releases

As a Product Manager, I want to view the Delivery Releases from a Change.

Retrieve Actual Delivery Release and all Target Releases:

GET /changes/{id}/deliveryReleases

Notice that your response body here will return you even potential Target Releases which have the same Impacted System(s).

Retrieve Actual Delivery Release or any of Target Releases:

GET /changes/{id}/deliveryReleases/{releaseId}

Update Actual Delivery Release and/or Target Release:

PUT /changes/{id}/deliveryReleases/{releaseId}

General Rules for Change API Request

  • A Change must be linked to the same system as a Release in order for any potential relationship to be created

  • A Change cannot be linked to a Release with an Implementation Date in the past via the UI but this can be done via the API by adding ‘?IncludePastRelease=True’ to the query string

  • A Change cannot be linked to a Release in an End-State (e.g. the status mode is Completed or Cancelled) via the UI but this can be done via the API

  • A Change can be linked to multiple releases with a ‘TargetRelease’ relationship but only one release with an ‘ActualDeliveryRelease’ relationship

  • The ‘TargetRelease’ will be automatically set to True once you set the ‘ActualDeliveryRelease’ to True

Example request body:

{
“releaseId”: “00000000-0000-0000-0000-000000000000”,
“targetRelease”: true,
“actualDeliveryRelease”: true
}

Initiative Management (IM) Use Cases

Retrieve All IM Forms

As a Release Manager, I want to view all the available IM forms:

GET /Form/GetAll

Retrieve All IM Form Instances

As a Release Manager, I want to view all the available IM Form Instances:

GET /FormInstance/GetAll

Filter IM Form Instances

Filter IM Form Instances using the following parameters:

  • Id.
  • Identifier.
  • Name.
  • Status.
  • WorkflowStatus.
  • LastModifiedByFullName.
  • LastModifiedDate.
  • CreatedByFullName.
  • CreatedDate.
  • Custom Field – Text.
  • Custom Field – Checkbox.
  • Custom Field – Checkbox Group.
  • Custom Field – Radiobutton.
  • Custom Field – Date.
  • Custom Field – Number.
  • Custom Field – Select Release (single select).
  • Custom Field – Select Release (multi select).
  • Custom Field – Select System (single select).
  • Custom Field – Select System (multi select).
  • Custom Field – Select Environment (single select).
  • Custom Field – Select Environment (multi select).
  • Custom Field – Select User (single select).
  • Custom Field – Select User (multi select).
  • Custom Field – Select Team (single select).
  • Custom Field – Select Team (multi select).
  • Custom Field – Select IM Form Instance (single select).
  • Custom Field – Select IM Form Instance (multi select).
  • Custom Field – HTML Editor.
  • ParentFormInstanceName.
  • ChildFormInstanceName.

See Filter and Paginate API Calls for how to use filters in Plutora’s external API, including operators and backticks.

Retrieve the Structure of Your Form Instance

As a Release Manager, I want to retrieve all the details of a Form Instance, including parameters, data types, and so on, so I can use them in another request:

GET /formInstance/getFormInstanceStructure/{formId}/{formInstanceId}

Retrieve Values from a Form Instance

As a Release Manager, I want to retrieve the values of fields from a Form Instance:

GET /formInstance/getFormInstanceValues/{formInstanceId}

Retrieve Combo Box Values

As a Release Manager, I want to retrieve a list of available values from a combo box:

Combo boxes can contain Releases, Systems, Environments, Users, IM Teams, IM Form Instances, or customer-created values.

GET /formInstance/{formInstanceId}/ComboBoxElementFilter/{elementId}

Generate a New Form Instance

As a Release Manager, I want to create a new Form Instance from an IM form:

POST /formInstance/GetNewFormInstance/{formId}

Update a Field Value in your Form Instance

POST /Forminstance/SetElementValue

As a Release Manager, I want to update the value of a “checkbox” custom field:

{
"FormElementId": "{checkbox-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 2,
"ValueBoolean": true,
"ValueText": “on”
}

As a Release Manager, I want to update a “date” custom field:

{
"FormElementId": "{datefield-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 3,
"ValueDate": "{date}"
}

As a Release Manager, I want to update a “number” custom field:

{
"FormElementId": "{numberfield-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 4,
"ValueNumber": 123
}

As a Release Manager, I want to update “text” custom field:

{
"FormElementId": "{textfield-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 5,
"ValueText": "string"
}

As a Release Manager, I want to update a “text area” custom field:

{
"FormElementId": "{textarea-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 6,
"ValueText": "string"
}

As a Release Manager, I want to update a “checkbox group” custom field:

{
"FormElementId": "{checkboxgroup-id}",
"FormInstanceId": "{im-form-instance-id}",
"ValueIds": ["{checkboxgroup-value1-id}","{checkboxgroup-value2-id}"],
"ElementType": 10
}

As a Release Manager, I want to update a “radio group” custom field:

{
"FormElementId": "{radiogroup-id}",
"FormInstanceId": "{im-form-instance-id}",
"ValueIds": ["{radiogroup-value1-id}"],
"ElementType": 11
}

As a Release Manager, I want to update a “select” custom field:

{
"FormElementId": "{selectoption-id}",
"FormInstanceId": "{im-form-instance-id}",
"ValueIds": ["{selectoption-value1-id}","{selectoption-value2-id}"],
"ElementType": 12
}

As a Release Manager, I want to update an “HTML editor” custom field:

{
"FormElementId": "{htmleditor-id}",
"FormInstanceId": "{im-form-instance-id}",
"ElementType": 13,
"ValueText": "string"
}

Update Multiple Field Values in your Form Instances

As a Release Manager, I want to update multiple values in a Form Instance:

POST /formInstance/SetElementsValue

Update the Name of a Form Instance

As a Release Manager, I want to change the name of my Form Instance:

PUT /formInstance/UpdateName

{
	"Id": "{im-form-instance-id}",
	"Name": "string"
}
PUT /FormInstance/SetFormInstanceParentId?id={im-form-instance-id}&parentFormInstanceId={parent-im-form-instance-id}
PUT /FormInstance/SetFormInstanceParentId?id={child-im-form-instance-id}&parentFormInstanceId={im-form-instance-id}
DELETE /FormInstance/RemoveParentFormInstance?id={im-form-instance-id}&parentFormInstanceId={parent-im-form-instance-id}
GET /FormInstance/GetFormInstanceActiveCoreParents/{im-form-instance-id}
GET /FormInstance/GetDirectParentsAndChildrenFormInstances/{im-form-instance-id}

Retrieve the Audit History of a Form Instance

POST /audit/search

Request body (JSON example):

{
  "startDate": "2020-07-11",
  "endDate": "2020-07-21T12:48:29.732Z",
  "userIds": [
    "37327d40-41c4-ea11-aa62-8522294b29ae"
  ],
  "entityId": "37327d40-41c4-ea11-aa62-8522294b29ae",
  "auditEntityType": "FormInstance",
  "eventTypes": [
    "Added", "Modified", "Deleted"
  ],
  "recordsPerPage": 10,
  "pageNum": 1
}

Deployment Plan Use Cases

Deployment Plan business logic applies to the API. If you contradict business logic, your request will generate an error message and fail.

When sending a PUT request, avoid removing data by including all the data from the existing Deployment Plan. For example, when your Deployment Plan has an externalIdentifier value if the PUT request is sent without this value, the externalIdentifier value will be deleted.

The maximum number of records returned for Plutora API requests is 100. Use a filter to make sure you return the records you require within the 100 returned. For example, to search for any kind of Deployment Plan – Master or regular:

GET /DeploymentPlanBase/GetDeployments?request.liveSearch=abc

Draft Mode

Here are some examples of use cases for Master and regular Deployment Plans in Draft Mode.

Create a Deployment Plan

As a Deployment Manager, I want to create a Deployment Plan called dp name with two Systems:

POST /DeploymentPlan/Create

{
 "name": "dp name",
 "description": "dp description",
 "externalIdentifier": "dp external identifier",
 "OrganizationID": "organization",
 "SystemIDs": ["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"],
 "releaseId": "1dec0ad9-af16-4d95-a0a6-8cc461b70ff4"
}

Create a Master Deployment Plan

As a Deployment Manager, I want to create a Master Deployment Plan called mdp name with two child Deployment Plans:

POST /MasterDeploymentPlan/Create

{
 "name": "mdp name",
 "description": "mdp description",
 "externalIdentifier": "mdp external identifier",
 "OrganizationID": "organization",
 "DeploymentPlanIds":["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"],
 "ReleaseIds": ["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"]
}

Add Deployment Plan Activities

As a Deployment Manager, I want to add Deployment Plan Activities to my Deployment Plan:

POST /DeploymentPlanActivities/BatchCreate?deploymentPlanId={id}

[
 {
   "name": "activity name",
   "planID": "1dec0ad9-af16-4d95-a0a6-8cc461b70ff4",
   "responsibleID": "1dec0ad9-af16-4d95-a0a6-8cc461b70ff4",
   "systemIDs": ["1dec0ad9-af16-4d95-a0a6-8cc461b70ff4"],
   "description": "activity description",
   "isMilestone": true,
   "isAutomated": false,
   "isOptional": true,
   "startDateTimePlanned": "2019-05-02T12:59:31.603Z",
   "endDateTimePlanned": "2019-05-02T12:59:31.603Z",
   "isDowntime": true,
   "activitySetsIds": ["1dec0ad9-af16-4d95-a0a6-8cc461b70ff4"]
 }
]

Note: As many Activities as desired can be added in an array [].

Update Deployment Plan Activity Dependencies

As a Deployment Manager, I want to update the dependencies of the Activities in my Deployment Plan:

PUT /DeploymentPlanActivities/BatchUpdate?deploymentPlanId={id}

{
  	"id": "0fddff99-2cc7-4194-9132-6f6409d6a7f6",
    "name": "2019-11-21T15:21:50.472Z POST ACTIVITY BULK 2 - updated",
    "sortOrder": 1,
    "planID": "5f43b99b-87f4-e911-aa12-f24de9ed7ee4",
    "responsibleID": "d2450c29-7e78-476f-b0c9-05a3b6db9d9e",
    "systemIDs": ["a78ae7bb-0c7c-4360-a958-50446739076f"],
    "description": "2019-11-21T15:21:50.472Z POST ACTIVITY BULK 2 - updated",
    "isMilestone": true,
    "isAutomated": false,
    "isOptional": true,
    "status": "None",
    "startDateTimePlanned": "2019-11-21T15:21:50.472Z",
    "endDateTimePlanned": "2019-11-19T11:21:19.563Z",
    "isDowntime": true,
    "downtimeFrom": "2019-11-21T15:21:50.472Z",
    "downtimeTo": "2019-11-19T11:21:19.563Z",
    "activitySetsIds": ["ceef86d8-add9-e911-aa0b-c8f632e99fb1"],
    "automatedBuildStatus": "NotRun",
    "SortOrder": 1,
    "GroupSortOrder": "1.000000000000000000000000",
    "dependencies": {
      "updated": [
        {
        	"ID": "ed659345-879c-4da1-8f64-6ae5c9f5c81e",
            "DependentActivityId": "d505db00-716a-42ba-aed6-e44b5b6f196b",
            "DependencyType": 1
        }
      ]
    }
  }
]
Notes

As many Activities as desired can be added in an array.

Depending on the action, you should use one of the following parameters: “added”, “updated”, or “deleted”.

If you want to update your Deployment Plan Activities without changing their dependencies, simply use the empty parameter “Dependencies”: {} or just skip it completely.

Duplicate a Deployment Plan (Master or Regular)

As a Deployment Manager, I want to duplicate a Deployment Plan so I don’t have to enter the information manually:

POST /DeploymentPlanBase/DuplicatePlan

{
 "id": "[GUID of dp/mdp to be duplicated]",
 "name": "duplicate dp/mdp name",
 "activities": true,
 "activityStartDate": "2019-05-02T12:59:31.603Z",
 "activityAttachments": true,
 "checkpoints": true,
 "checkpointStartDate": "2019-05-02T12:59:31.603Z",
 "issueQuestions": true
}

Update Deployment Plan Custom Fields

As a Deployment Manager, I want to update a custom field, so that it shows the correct information.

PUT /DeploymentPlan/Update/{ID}

{
"id": "{deployment-plan-guid}",
"name": "{deployment-plan-name}",
"description": {deployment-plan-description}",
"externalIdentifier": "{deployment-plan-external-identifier}",
"OrganizationID": "{deployment-plan-organization-guid}",
"DeploymentPlanIds":["{child-deployment-plan-1-guid}","{child-deployment-plan-2-guid}","{child-deployment-plan-3-guid}"],
"ReleaseIds": ["{release-1-guid}","{release-2-guid}","{release-3-guid}"],
"PlanCustomFieldPrototype": [
{
"LookupID": "{date-picker-field-guid}",
"ValueDate": "{date-picker-field-value}"
},
{
"LookupID": "{decimal-field-guid}",
"ValueDecimal": 12345
},
{
"LookupID": "{currency-field-guid}",
"ValueDecimal": 12345
},
{
"LookupID": "{list-field-field-guid}",
"ValueGuid": "{list-field-field-value}"
},
{
"LookupID": "{free-text-field-guid}",
"ValueText": "12345"
},
{
"LookupID": "{time-picker-field-guid}",
"ValueTime": "23:59:59"
},
{
"LookupID": "{number-field-guid}",
"ValueNumber": 12345
},
{
"LookupID": "{date-time-picker-field-guid}",
"ValueDateTime": "{date-time-picker-field-value}"
},
{
"LookupID": "{list-select-field-guid}",
"ValueGuids": ["{list-select-field-value}"]
}
]
}

Approve a Deployment Plan

As a Deployment Manager, I want to set two Draft mode Deployment Plans to Approved mode:

POST /DeploymentPlanBase/BulkApprove

["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"]

Approved Mode

Here are some examples of use cases for Master and regular Deployment Plans in Approved Mode.

Return Approved Mode Deployment Plans to Draft Mode

As a Deployment Manager, I want to return two Approved mode Deployment Plans to Draft mode:

POST /DeploymentPlanBase/BulkBackToDraft

["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"]

Move Approved Deployment Plans to Execution Mode

As a Deployment Manager, I want to set two Approved mode Deployment Plans to Execution mode:

POST /DeploymentPlanBase/BulkExecute

["ce74d4c1-3398-4c2a-84c0-0069a287f821","2120f59d-e47f-4b45-bfae-b457e0f2823c"]

Execution Mode

Here are some examples of use cases for Master and regular Deployment Plans in Execution Mode.

Retrieve Deployment Plan Activities

As a Deployment Manager, I want to retrieve Deployment Plan Activities:

GET /DeploymentPlanActivities/GetActivity

{
 "activityId": "{GUID of Activity to be updated}",
 "{API Field Name}": "2019-05-02T12:59:31.603Z"
}
UI Value API Field Name
Planned Start Time StartDateTimePlanned
Actual Start Time FactStartDate
Revised Start Time RevisedStartTime
Planned End Time EndDateTimePlanned
Actual End Time FactEndDate
Revised End Time ActualDateTimeCompleted

Update an Activity Status

As a Deployment Manager, I want to update the status of a Deployment Plan Activity in my Deployment Plan:

POST /DeploymentPlanBase/UpdateActivityStatus?activityId={id}&status=X

Where X is a Status number. (0 Not Started, 1 Completed, 2 In Progress, 3 Failed, 4 Issue and -1 N/A)

Update an Activity’s Revised Start Time

As a Deployment Manager, I want to update my Activity’s Revised Start Time:

POST /DeploymentPlanBase/UpdateRevisedStartTime

{
 "activityId": "{GUID of Activity to be updated}",
 "revisedDateTime": "2019-05-02T12:59:31.603Z"
}

Update an Activity’s Revised End Time

As a Deployment Manager, I want to update my Activity’s Revised Start End:

POST /DeploymentPlanBase/UpdateRevisedEndTime

{
"activityId": "{GUID of Activity to be updated}",
"revisedDateTime": "2019-05-02T12:59:31.603Z"
}

Bookings Use Cases

Bookings API enables you to create, read, update and delete Environment and Environment Group bookings within Release or TEBR (with/without Release) via external APIs:

Retrieve all the bookings

Enables you to retrieve all the bookings in Plutora in a paginated format. Also, provides filtering capabilities, so you can retrieve a filtered list of Bookings.

Get /Bookings

Create bookings

You can create Environment, and Environment Group bookings for Release or TEBR (with/without Release)using this API.

Post /Bookings

Example for Booking in Release:

{
  "isEnvironmentGroup": true,
  "environmentId": "{GUID of Environment or Environment Group to be booked}",
  "tebrId": null,
  "releaseId": "{GUID of a Release to be used for a new Booking}",
  "phaseId": "{GUID of a Release Phase to be used for a new Booking}"
}

Example for Booking in TEBR with Release:

{
  "isEnvironmentGroup": true,
  "environmentId": "{GUID of Environment or Environment Group to be booked}",
  "tebrId": "{GUID of a TEBR to be used for a new Booking}",
  "releaseId": "{GUID of a Release to be used for a new Booking}",
  "phaseId": "{GUID of a Release Phase to be used for a new Booking}"
}

Example for Booking in TEBR without Release:

{
  "isEnvironmentGroup": true,
  "environmentId": "{GUID of Environment or Environment Group to be booked}",
  "tebrId": "{GUID of a TEBR to be used for a new Booking}",
  "releaseId": null,
  "phaseId": null
}

Delete a booking

Use this API to delete a booking.

Delete /Bookings/{id}

Retrieve a booking

Enables you to retrieve booking details by its ID.

Get /Bookings/{id}

Update a booking

Use this API to update the Status, Start Date, and/or End Date of a booking.

Patch /Bookings/{id}

Example:

{
  "startDate": "2022-02-18T01:25:12.871Z",
  "endDate": "2022-02-18T01:25:12.871Z",
  "status": "Pending/Approved/Rejected"
}

Track Development Team Task and Hours

As an Engineering Manager, I want to use Plutora’s API to track my development team’s hours and tasks:

To track a development team’s hours and tasks using Swagger:

  1. Go to Swagger and follow steps 1a to 5a to set up a token.
  2.  Go to Users > POST /users/GenerateReport/{startdate}/{enddate}.
  3. Input a:
    • startdate (for example, 2018-12-01).
    • enddate (for example, 2018-12-05).
    • userIdList (for example, [“d2450c29-7e78-476f-b0c9-05a3b6db9d9e”])
  4. Click Try it out!

To track a development team’s hours and tasks using Postman:

  1. Open Postman. (Follow steps 1a (or 1b), 2, and 3 to download and install Postman and set up a token if you haven’t already done so.)
  2. Use the URL format (for example, POST https://auapi.plutora.com/users/GenerateReport/2018-12-01/2018-12-05) with the request body [“d2450c29-7e78-476f-b0c9-05a3b6db9d9e”].
  3. Click Send.

Using POST Entity/filter

The API equivalent of grid column filter for Releases, Changes, TECRs, and TEBRs is /filter with the parameter searchFilters. 

General Rules for Requests “POST [entity]/filter” and “POST [entity]/search”

Plutora API allows the following filter requests to be executed:

  • POST TEBRs/filter.
  • POST Changes/filter.
  • POST Releases/filter.
  • POST TECRs/filter.

Plutora Test API allows the following search requests to be executed:

  • POST Categorysettings/search.
  • POST Defects/search.
  • POST Defects/BulkUpdateSearch.
  • POST Requirement/search.
  • POST Requirement/BulkUpdateSearch.
  • POST Testcase/search.
  • POST Testcase/SearchWithExecutionSummary.
  • POST Testcase/BulkUpdateSearch.
  • POST Testplan/search.

All the above requests allow the following operators to be used:

  • Equals.
  • NotEquals.
  • Contains (not applicable for date, date time, or GUID values).
  • NotContains (not applicable for date, date time, or GUID values).
  • LessThan.
  • LessOrEqual.
  • GreaterOrEqual.
  • GreaterThan.
  • IsWithin (also allows multiple values to be separated by commas).
  • NotWithin.

Filters do not work on custom fields, only main entity fields.

The following is a general request template for Releases, Changes, TECRs, and TEBRs. The property and value will need to be inherent to the entity.

Zero is the first page number. Typing “1” will get the second page number and so on. 

{
  "searchFilters": [
    {
      
      "property": "string",
      "direction": "ASC",
      "value": "string",
      "operator": "Equals"
    }
  ],
  "recordsPerPage": 0,
  "pageNum": 0
}

User Story: Retrieve Changes or Requirements which have the Status “Testing” or “Review”

Retrieve multiple values by using the operator IsWithin and by separating the multiple values with commas.

Filter:

POST Changes/filter or POST Requirements/search.

{
    "searchFilters": [
    {
      "property": "Status",
      "direction": "ASC",
      "value": "Testing,Review",
      "operator": "IsWithin"
    }
  ]
}

Now retrieve the same data showing page 3 of the results with 10 records per page. (Note that attempting to retrieve the page beyond the maximum one with data will return a blank response.)

{
	"PageNum":3,
	"RecordsPerPage":10,
	"searchFilters": [
    {
      "property": "Status",
      "direction": "ASC",
      "value": "Testing,Review",
      "operator": "Equals"
    }
  ]
}

User Story: Retrieve Changes that have “ABC” in the name

{

  "searchFilters": [

    {

      "Property": "name",

      "Direction": "ASC",

      "Value": "ABC",

      "Operator": "Contains"

    }

  ]

}
 

User Story: Retrieve the Changes that were last modified by “John Smith”

{

  "searchFilters": [

    {

      "Property": "lastModifiedBy",

      "Direction": "ASC",

      "Value": "John Smith",

      "Operator": "Contains"

    }

  ]

}

Or:

{

  "searchFilters": [

    {

      "Property": "lastModifiedBy",

      "Direction": "ASC",

      "Value": "John Smith",

      "Operator": "Equals"

    }

  ]

}

Existing Entities Only

Some data cannot be added to an entity at the time the entity is created, but only to an existing entity. For example, Systems, Stakeholders, Phases, and Gates can only be added to existing Releases, not at the time the Release is created.

Entity Add these to existing entities only
Releases Systems, Stakeholders, Phases, Gates, Activities, Criteria, Changes, Comments
Phases Activities
Gates Criteria
Releases, Changes, TECRs, Deployment Plans, and Systems Stakeholders
Environments Hosts
Hosts and Components Layers (cannot save without a Component)

Required IDs and their Location

When performing the following actions, you require the following IDs, which can be found at the following locations.

Action ID Required ID Location
Adding a Phase to a Release Phase ID /workitemnames/phases
Adding a Gate to a Release Gate ID /workitemnames/gates
Adding an Activity to a Phase ID of Phase assigned to Release /releases/{{releaseId}}/phases
Adding a Criterion to a Gate ID of Gate assigned to Release /releases/{{releaseId}}/gates

How to access System Layer data via API

The majority of system customizations settings can be found via the /lookupfields/<type> API calls.

Specifically, StackLayer configurations can be found under: /lookupfields/StackLayer.

To create a Layer, you must first create an Environment (to get environmentId) and Host (to get hostId), separately.  You can then create a new layer with a “child”-entity Component, associated back to the environmentId and hostId.

POST https://{{API_host}}/layers

{

"EnvironmentID": "{{environmentId}}",
"HostID": "{{hostId}}",
"StackLayerID": "{{stackLayerId}}",
"ComponentName": "{{ComponentName}}",
"Version": "{{value}}"

}

The parameters above are arranged in the same way that the fields appear in the UI:

Related Articles

Contents

Be the first to find out about new features. Subscribe to the Release Notes email.

Was this article helpful?

Thanks for your answer!