Open a Potential Change Order (PCO)
This tutorial demonstrates how to open a potential change order (PCO) through a workflow action.
Before You Begin
- Register an app.
- Acquire a 3-legged OAuth token with
data:create
data:read
anddata:write
scopes. - Verify that you have access to the relevant BIM 360 account and BIM 360 project.
- Retrieve the project container ID for your project as described in Retrieve container id.
- Ensure that there is a PCO in the project. If there isn’t a PCO in the project, see Create a Potential Change Order (PCO) to create one.
Step 1: Find a PCO in BIM 360 Cost Management
Find the ID of the PCO by calling GET PCO. In this example, assume that the container ID is 18ece8b1-204d-11e8-ad71-d73b169f902a
.
Request
curl 'https://developer.api.autodesk.com/cost/v1/containers/18ece8b1-204d-11e8-ad71-d73b169f902a/change-orders/pco?limit=100&offset=0' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0'
Response
{
"results": [{
"id": "55254a50-44d9-11e9-99d7-79aa05d3109e",
"...":"...",
}],
"pagination": {
"totalResults": 1,
"limit": 100,
"offset": 0
}
}
In this example, the PCO ID is in the first part of the response (results[0].id
) which is 55254a50-44d9-11e9-99d7-79aa05d3109e
. You’ll use it in the next step.
Step 2: Find the Available Actions For the PCO
Use the PCO ID (55254a50-44d9-11e9-99d7-79aa05d3109e
) to call GET actions to get the available actions for the PCO.
All the actions are associated to an items in Cost Management, for example change order, by the associationId and associationType. For a PCO, the associationId value is the PCO ID 55254a50-44d9-11e9-99d7-79aa05d3109e
and the associationType value is FormInstance
.
Request
curl 'https://developer.api.autodesk.com/cost/v1/containers/18ece8b1-204d-11e8-ad71-d73b169f902a/workflows/FormInstance/5254a50-44d9-11e9-99d7-79aa05d3109e/actions' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0' -H 'Content-Type: application/json'
Response
[{
"name": "open",
"transforms": [{
"key": "budgetStatusId",
"to": "open"
},
{
"key": "costStatusId",
"to": "open"
}
],
"rules": [{
"key": "budgetStatusId",
"only": ["draft"]
},
{
"key": "costStatusId",
"only": ["draft"]
}
]
}]
The name open
is the action we can perform on this PCO. The transforms are what the action will perform on the PCO in this action: setting budgetStatusId
and costStatusId
to``open``. The rules are the conditions required to perform the action. For example, we can only perform the open
action when both the budgetStatus
and costStatus
are set to draft
, otherwise the action will fail.
Step 3: Open the PCO
Use the action open
and the PCO ID to call POST cost/v1/containers/:containerId/workflows/actions
Request
curl -X POST 'https://developer.api.autodesk.com/cost/v1/containers/18ece8b1-204d-11e8-ad71-d73b169f902a/workflows/actions' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0' \
-H 'Content-Type: application/json'
-d '[
{
"action": "open",
"associationId": "55254a50-44d9-11e9-99d7-79aa05d3109e",
"associationType": "FormInstance",
}
]'
Response
[
{
"action": "open",
"associationId": "55254a50-44d9-11e9-99d7-79aa05d3109e",
"associationType": "FormInstance",
"errors": []
}
]
If the action succeeded, the errors
value in the response will be empty. If the action failed, the errors
value will include details about why the action failed.
Congratulations! You have opened the PCO and now can start using other change processes.