External API Use Cases

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

Article Contents

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 GUIDs 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

 

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"
}

Link a New Parent to a Form Instance

PUT /FormInstance/SetFormInstanceParentId?id={im-form-instance-id}&parentFormInstanceId={parent-im-form-instance-id}

Link a New Child to a Form Instance

PUT /FormInstance/SetFormInstanceParentId?id={child-im-form-instance-id}&parentFormInstanceId={im-form-instance-id}

Unlink a Parent from a Form Instance

DELETE /FormInstance/RemoveParentFormInstance?id={im-form-instance-id}&parentFormInstanceId={parent-im-form-instance-id}

Retrieve Core Parent Links for a Form Instance

GET /FormInstance/GetFormInstanceActiveCoreParents/{im-form-instance-id}

Retrieve All Child and Parent Links for a Form Instance

GET /FormInstance/GetDirectParentsAndChildrenFormInstances/{im-form-instance-id}

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.

 

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

 

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"
}

 

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:

Back to the top arrow

Be the first to find out about new features. Subscribe to the Release Notes email. Subscribe Now
2 found this helpful.