Integrating Cost Management with External ERP Systems
This tutorial demonstrates how to integrate entities, such as budgets, with an external ERP system. It covers two options: integrating an existing BIM 360/ACC budget with an external ERP system and integrating an existing budget from an external ERP system into a BIM 360/ACC budget. The steps include finding the relevant budget, updating the integration-related fields, and verifying synchronization between the systems.
Note that we support integrating the following entities with external ERP systems: budgets, contracts, main contracts, main contract items, cost items, expenses, expense items, change orders, and schedules of values.
For more information about external ERP system integrations, see the Help documentation.
Before You Begin
- Register an app
- Acquire a 3-legged OAuth token with
data:read
anddata:write
scopes. - Verify that you have access to the relevant BIM 360 or ACC account and BIM 360 or ACC project.
- Retrieve the container ID for your project, as described in Retrieve container id. Assume the container ID is
71e6b356-a101-4277-b4ca-98989bff4a90
. - For this tutorial, use the external ERP system
Morpheus
, and assume that the external ID isM001
, and the integration state islocked
. - Ensure that you have a budget created in your BIM 360/ACC project and that a corresponding budget exists in the external ERP system.
Option 1: Sync BIM 360/ACC Budget Information to an ERP System
This option demonstrates how to sync an existing budget from BIM 360/ACC to an external ERP system. The steps include retrieving the budget ID from BIM 360/ACC, updating the integration-related fields, and mapping it to the external ERP system.
Step 1: Find a Budget in BIM 360/ACC Cost Management
Call GET budgets with the container ID 71e6b356-a101-4277-b4ca-98989bff4a90
to retrieve the budget ID needed to sync the BIM 360/ACC budget with the external ERP system.
Request
curl 'https://developer.api.autodesk.com/cost/v1/containers/71e6b356-a101-4277-b4ca-98989bff4a90/budgets?limit=100&offset=0' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5I00'
Response
{
"results": [{
"formattedCode": "001",
"origCommitment": "50.0000",
"id": "bb8cf933-a5ab-47f1-9103-fe6804303f07",
"...":"...",
}],
"pagination": {
"totalResults": 1,
"limit": 100,
"offset": 0
}
}
Use the budget ID bb8cf933-a5ab-47f1-9103-fe6804303f07
to update the budget with integration information in the next step.
Step 2: Create a Mapping to the ERP System
To map the budget in BIM 360/ACC to the external ERP system, use the retrieved budget ID (bb8cf933-a5ab-47f1-9103-fe6804303f07
), container ID (71e6b356-a101-4277-b4ca-98989bff4a90
), external system name (Morpheus
), external ID (M001
), and set the integration state to locked
by calling PATCH budgets.
Request
curl -v 'https://developer.api.autodesk.com/cost/v1/containers/71e6b356-a101-4277-b4ca-98989bff4a90/budgets/ bb8cf933-a5ab-47f1-9103-fe6804303f07' -X 'PATCH' -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' -H 'Content-Type: application/json' \
-d '{
"externalMessage": "success",
"externalSystem": "morpheus",
"externalId": "M001",
"integrationState": "locked",
"lastSyncTime": "2024-02-27T10:00:00.354Z"
}'
Response
{
"formattedCode": "l1",
"id": "bb8cf933-a5ab-47f1-9103-fe6804303f07",
"containerId": "71e6b356-a101-4277-b4ca-98989bff4a90",
"parentId": null,
"rootId": null,
"name": "l1",
"code": "l1",
"scope": "budgetAndCost",
"description": null,
"quantity": 1,
"unitPrice": "100.00000000",
"...": "...",
"externalSystem": "morpheus",
"externalId": "M001",
"externalMessage": "success",
"integrationState": "locked",
"lastSyncTime": "2024-02-27T10:00:00.354Z",
"mainContract": {
"id": "d1109c69-d70e-49df-bc88-05032089ead9",
"name": "mainContract1"
},
"...": "..."
}
The budget in BIM 360 is now integrated with the external ERP system. The integrated items’ information can be retrieved from the external ERP system by calling GET budgets.
Option 2: Sync an ERP System to a BIM 360/ACC Budget
This option demonstrates how to sync an existing budget from an external ERP system into BIM 360/ACC. The steps include creating a synchronized budget in BIM 360/ACC with the relevant integration information and setting the integration state.
Step 1: Create a BIM 360/ACC Budget with Integration Information
This step will create the budget inside of Cost Management, linking it to the specified external ERP system.
To sync an existing budget from an external ERP system into BIM 360/ACC, use the container ID (71e6b356-a101-4277-b4ca-98989bff4a90
), the external system (MORPHEUS
), the external ID (M001
), and set the integration state to locked
to call POST budgets.
Request:
curl --location 'https://developer.api.autodesk.com/construction/cost/v1/projects/71e6b356-a101-4277-b4ca-98989bff4a90/budgets' \
--header 'Content-Type: application/json' \
--data '{
"code": "1",
"name": "1",
"quantity": 1,
"unitPrice": 0,
"unit": "ea",
"segmentCodeMap": {},
"externalSystem": "morpheus",
"externalId": "M001",
"externalMessage": "success",
"integrationState": "locked",
"lastSyncTime": "2024-01-23T21:51:57.775Z"
}'
Response:
{
"formattedCode": "",
"id": "b16ac870-e151-11ee-b31d-0969f47312bd",
"containerId": "71e6b356-a101-4277-b4ca-98989bff4a90",
"name": "1",
"code": "1",
"scope": "budgetAndCost",
"description": null,
"quantity": 1,
"unitPrice": "0.00000000",
"inputQuantity": null,
"ratio": 1,
"unit": "ea",
"originalAmount": "0.0000",
"budgetCodeId": "b1683060-e151-11ee-b31d-0969f47312bd",
"contractId": null,
"mainContractId": "d1109c69-d70e-49df-bc88-05032089ead9",
"mainContractItemId": null,
"creatorId": "WHA2J3KBMHKRQCHD",
"changedBy": "WHA2J3KBMHKRQCHD",
"createdAt": "2024-03-13T15:52:28.024Z",
"updatedAt": "2024-03-13T15:52:28.049Z",
"integrationStateChangedAt": "2024-03-13T15:52:28.024Z",
"integrationStateChangedBy": "WHA2J3KBMHKRQCHD",
"isTracked": false,
"distributionItemId": null,
"externalSystem": "morpheus",
"externalId": "MB002",
"externalMessage": null,
"integrationState": "locked",
"lastSyncTime": "2024-01-23T21:51:57.775Z",
"mainContract": {
"id": "d1109c69-d70e-49df-bc88-05032089ead9",
"name": "mainContract1"
},
"mainContractItem": null,
"properties": [],
"budgetCode": "l1",
"...": "..."
}
Congratulations! The budget is now synchronized between BIM 360/ACC and the external ERP system.