Directly Attach Local Files to Cost Item (deprecated)
This workflow is deprecated. We will continue to support it until November 30th, 2022. We recommend migrating to the new direct-to-S3 workflow.
This tutorial demonstrates how to attach local files directly to a cost item in BIM 360 cost management. The attachment folder is a hidden folder and does not appear in the BIM 360 Document Management UI. If you directly attach a local file, it does not get associated with other BIM 360 feature, such as BIM 360 Document Management; it remains as an attachment only for the cost item. The steps below include getting a folder for the cost item, creating an empty storage object for the file in the folder, uploading the file to the storage object, and attaching the file to the cost item.
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.
- Have the project’s projectId and the appropriate cost management containerId or acquire one: Retrieve container id.
Step 1: Find a Cost Item in BIM 360 Cost Management
Find the cost item ID to which you want to attach the file by calling GET CostItems. 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/cost-items?limit=100&offset=0' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0'
Response
{
"results": [{
"id": "328f3a40-3167-11e8-a044-01a43a3d152c",
"...": "..."
}],
"pagination": {
"totalResults": 7,
"limit": 100,
"offset": 0
}
}
In this example, the first ID in the response is the cost item ID: 328f3a40-3167-11e8-a044-01a43a3d152c
.
Step 2: Find the Attachment Folder of the Cost Item
To get the cost item’s attachment folder, use CostItem
as associationType and the cost item ID (328f3a40-3167-11e8-a044-01a43a3d152c
) you retrieved above as associationId, and call POST cost/v1/containers/{containerId}/attachment-folder.
Request
curl 'https://developer.api.autodesk.com/cost/v1/containers/18ece8b1-204d-11e8-ad71-d73b169f902a/attachment-folders' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0' \
-H 'Content-Type: application/json' \
-d '{"associationType":"CostItem","associationId":"328f3a40-3167-11e8-a044-01a43a3d152c"}'
Response
{
"id": "80b446f0-4261-11e9-9f1f-e19f7c813519",
"urn": "urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA",
"..." : "..."
}
The URN urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA
is the folder URN you’ll use to access storage service in the next step(step 3). You’ll use the ID 80b446f0-4261-11e9-9f1f-e19f7c813519
to create attachments in the last step(step 6) to attach the file to the cost item. .
Note: Instead of using this folder, you can also use an existing folder retrieved from BIM 360 Docs. Follow the tutorial Upload Files to BIM 360 Document Management to upload a file to BIM 360 Docs directly, then jump to step 6 to add the file as an attachment to the cost item.
The following steps 3 to 5 are the same as generic uploading process if you are already familiar with Data Management API.
Step 3: Create a Storage Object in the Attachment Folder
For this example, assume the project ID is b.6b975448-835b-4625-ad1a-0e9961749de3
. (The prefix b.
denotes this as a BIM 360 project). The attachment folder URN is (urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA
). Use them to call POST projects/:project_id/storage to create an empty storage object for the file in the folder.
Request
curl -X POST "https://developer.api.autodesk.com/data/v1/projects/b.6b975448-835b-4625-ad1a-0e9961749de3/storage" \
-H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0" \
-d '{
"jsonapi": { "version": "1.0" },
"data": {
"type": "objects",
"attributes": {
"name": "My First File.jpg"
},
"relationships": {
"target": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA" }
}
}
}
}'
Response
{
"jsonapi": { "version": "1.0" },
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg",
"relationships": {
"target": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA"
},
}
}
}
}
The response contains the object ID (data.id
) - urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg
. The object ID parses into these three sections: <urn:adsk.objects:os.object>:<bucket_key>/<object_name>
. In this example response, the bucket key is wip.dm.prod
and the object name is 2a6d61f2-49df-4d7b.jpg
Step 4: Upload the File to the Storage Object
To upload the file to the storage object, use the bucket key (wip.dm.prod
) and the object name (2a6d61f2-49df-4d7b.jpg
) to call PUT buckets/:bucket_key/objects/:object_name.
Request
curl -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" -T @D:\My First File.jpg "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/2a6d61f2-49df-4d7b.jpg"
Response
{
"bucketKey" : "wip.dm.prod",
"objectId" : "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg",
"objectKey" : "2ac28abc-9f6e-463d-bcc4-5c194d552beb.jpg",
"sha1" : "a4b31905990233a2b0374b2b3a666116cfef12ca",
"size" : 879394,
"contentType" : "application/octet-stream",
"location" : "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects2a6d61f2-49df-4d7b.jpg"
}
The file has now been uploaded to the storage object.
Step 5: Create a Version of the Uploaded File
Before attaching the file to the cost item, you need to create the first version of the file. Use the project ID (b.6b975448-835b-4625-ad1a-0e9961749de3
), the folder URN (urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA
), and the Object ID (urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg
) to call POST projects/:project_id/items.
Request
curl -X POST -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" -H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json"
"https://developer.api.autodesk.com/data/v1/projects/b.6b975448-835b-4625-ad1a-0e9961749de3/items" -d '{
"jsonapi": { "version": "1.0" },
"data": {
"type": "items",
"attributes": {
"displayName": "My First File.jpg",
"extension": {
"type": "items:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"tip": {
"data": {
"type": "versions", "id": "1"
}
},
"parent": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.p0G_54wNRUuAfQQc4DCPEA"
}
}
}
},
"included": [
{
"type": "versions",
"id": "1",
"attributes": {
"name": "My First File.jpg",
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"storage": {
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg"
}
}
}
}
]
}'
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/items"
}
},
"data": {
"type": "items",
"id": "urn:adsk.wipprod:dm.lineage:AeYgDtcTSuqYoyMweWFhhQ",
"attributes": {
"displayName": "My First File.jpg",
"createTime": "2016-05-30T15:32:05+00:00",
"createUserId": "KPN8P8P65K",
"createUserName": "John Smith",
"lastModifiedTime": "2016-05-30T15:32:05+00:00",
"lastModifiedUserId": "KPN8P8P65K",
"lastModifiedUserName": "John Smith",
"extension": {
"type": "items:autodesk.bim360:File",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/items%3Aautodesk.bim360%3AFile-1.0"
},
"data": {}
}
},
"included": [
{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.AeYgDtcTSuqYoyMweWFhhQ?version=1",
"attributes": {
"name": "My First File.jpg",
"displayName": "My First File.jpg",
"createTime": "2016-05-30T15:32:05+00:00",
"createUserId": "KPN8P8P65K",
"createUserName": "John Smith",
"lastModifiedTime": "2016-05-30T15:32:05+00:00",
"lastModifiedUserId": "KPN8P8P65K",
"lastModifiedUserName": "John Smith",
"versionNumber": 1,
"mimeType": "application/image",
"fileType": "jpg",
"storageSize": 879394,
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/versions%3Aautodesk.bim360%3AFile-1.0"
},
"data": {}
}
},
The file is now ready to be attached to the cost item. Note the versioned file ID urn:adsk.wipprod:fs.file:vf.AeYgDtcTSuqYoyMweWFhhQ?version=1
. You’ll use it in the next step.
Step 6: Attach the File to the Cost Item
Use the container ID (18ece8b1-204d-11e8-ad71-d73b169f902a
), the cost item ID (328f3a40-3167-11e8-a044-01a43a3d152c
), and the versioned file ID (urn:adsk.wipprod:fs.file:vf.AeYgDtcTSuqYoyMweWFhhQ?version=1
) to call POST cost/v1/containers/{containerId}/attachments
Note that folderId is not required if you’re saving the attachment into an existing folder in BIM 360 Docs. In this example, the folderId is from the Step 2 above.
Request
curl 'https://developer.api.autodesk.com/cost/v1/containers/18ece8b1-204d-11e8-ad71-d73b169f902a/attachments' -H 'Accept: application/json' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0' -H 'Content-Type: application/json' -d '{
"urn":"urn:adsk.wipprod:fs.file:vf.ywE-g1asTFO2LVyI9TiiwA?version=1",
"folderId":"80b446f0-4261-11e9-9f1f-e19f7c813519",
"name":"My First File.png",
"associationType":"CostItem",
"associationId":"328f3a40-3167-11e8-a044-01a43a3d152c",
"type":"Upload"
}'
Response
{
"id": "891F5C5A-4356-482E-AC9C-585ED7DE1611",
"urn":"urn:adsk.wipprod:fs.file:vf.ywE-g1asTFO2LVyI9TiiwA?version=1",
"folderId":"80b446f0-4261-11e9-9f1f-e19f7c813519",
"name":"My First File.png",
"associationType":"CostItem",
"associationId":"328f3a40-3167-11e8-a044-01a43a3d152c",
"type":"Upload"
}
Congratulations! You have added an attachment to a cost item.