API User Stories

For better performance, GET [entity] requests should use a paginated format. For example, GET releases?pageNum=0&recordsPerPage=100

Plutora’s API has a number of user stories to keep in mind.

*NEW* Deployment Plan User Stories

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 user stories for Master and regular Deployment Plans in Draft Mode.

Create a Deployment Plan

As a Deployment Manager, I would like to create a Deployment Plan called dp name with two Systems.

POST /DeploymentPlan/Create

Request body:

{
 "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 would like to create a Master Deployment Plan called mdp name with two child Deployment Plans.

POST /MasterDeploymentPlan/Create

Request body:

{
 "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 would like to add Deployment Plan Activities to my Deployment Plan.

POST /DeploymentPlanActivities/BatchCreate?deploymentPlanId={id}

Request body:

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

 

Duplicate a Deployment Plan (Master or Regular)

As a Deployment Manager, I would like to duplicate a Deployment Plan so I don’t have to enter the information manually.

POST /DeploymentPlanBase/DuplicatePlan

Request body:

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

 

Approve a Deployment Plan

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

POST /DeploymentPlanBase/BulkApprove

Request body:

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

 

Approved Mode

Here are some examples of user stories 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

Request body:

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

Request body:

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

 

Execution Mode

Here are some examples of user stories for Master and regular Deployment Plans in Execution Mode.

 

Update an Activity Status

As a Deployment Manager, I would like 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 would like to update my Activity’s Revised Start Time.

POST /DeploymentPlanBase/UpdateRevisedStartTime

Request body:

{
 "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 would like to update my Activity’s Revised Start End.

POST /DeploymentPlanBase/UpdateRevisedEndTime

Request body:

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

 

Track Development Team Task and Hours

User Story: 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.

Request body:

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

Request body:

{

  "searchFilters": [

    {

      "Property": "name",

      "Direction": "ASC",

      "Value": "ABC",

      "Operator": "Contains"

    }

  ]

}

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

Request body:

{

  "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

Was this article helpful?

2 found this helpful.