Directly Attach Local Files to an Issue (new)
This tutorial demonstrates how to attach local files directly to an issue item in BIM 360.
Note that the attachment folder is a hidden folder that doesn’t appear in the BIM 360 Document Management UI. If you directly attach a local file, it doesn’t get associated with other BIM 360 features such as BIM 360 Document Management; it remains as an attachment only for the issue item.
The steps here include create an attachment object (it will automatically create an empty storage object in the container folder), uploading the file to the storage object, and update the issue attachments endpoint that the file was uploaded.
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 your project’s
containerId
, or acquire it using the Retrieve an Issues Container ID tutorial. - Have the appropriate
issueId
of the issue you want to retrieve the snapshot from, or acquire one using the GET issues endpoint.
Step 1: Create a storage object in the attachment folder
Use the POST attachments endpoint to create an empty storage object for the file in the folder. using containerId
and issueId
.
Note that the request payload urnType
must be oss
.
Request
curl --request POST 'https://developer.api.autodesk.com/issues/v2/containers/:containerId/issues/:issueId/attachments' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "test_file.png",
"urnType": "oss"
}'
Response
{
"id": "cdd1b6f9-9c05-46f4-92f4-8759fb00e42b",
"name": "test_file.png",
"urnType": "oss",
"urn": "urn:adsk.objects:os.object:wip.dm.prod/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png",
"status": "pre-upload",
"attachmentType": "photo",
"issueId": "ce382c8b-90da-4123-ae9e-414cd02c6427",
"updatedAt": "2022-12-07T13:23:13.892Z",
"createdAt": "2022-12-07T13:23:13.892Z",
"createdBy": "...",
"updatedBy": "...",
"deletedAt": null,
"urnPage": null,
"markupMetadata": null,
"resourceUrns": null,
"urnVersion": null,
"setWipUrnRetries": 0,
"deletedBy": null,
"permittedActions": [
"remove_attachment"
],
"permittedAttributes": [
"name"
]
}
In the response, you’ll find the relevant urn inside the urn
attribute. The value of the urn attribute urn:adsk.objects:os.object:wip.dm.prod/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png
parses into three substrings:
urn:adsk.objects:os.object
(the Object Storage Service)wip.dm.prod
(the bucket key)0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png
(the file object key)
You’ll use these keys to access the storage service in the next step.
Save the attachment ID (id
), you’ll use this id in step 4.
Notice that the status is still pre-upload
.
(In this example, the attachmentType is set to photo because the name suffix is in a photo format, but you can upload any file).
Step 2: Generate a signed S3 URL
Use the Data Management API’s GET buckets/:bucketKey/objects/:objectKey/signeds3upload endpoint to generate a signed URL for the storage object. Include the bucket key (wip.dm.prod
) and the object name (0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png
) that you retrieved in the previous step. This endpoint supports generating multiple signed URLs, which enables you to upload multiple chunks of the same file in parallel.
Request
curl -X GET "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png/signeds3upload" \
-H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
Response
{
"uploadKey": "AQICAHifrJ6-BSHUmjAat4QWI...cdWHJD90Ec7ZAaODsH_1LqXihzMNcJBA==",
"uploadExpiration": "2022-12-10T00:00:00Z",
"urlExpiration": "2022-12-07T13:11:40Z",
"urls": [
"https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/e9367e98-68fd-41b5-9c6d-71e9f8887179?uploadId=gbcGiDs0qWR975_q_VCAZGDWkXSad.XUQfTo4ZqVIlUi.mIe86gV0gXERp_WdfH3OYiimhSJeNSqGG9kTe.2PObko8c9qNE2e5hEFlkr_EbCkP2ag9JFXfbHjhiUcQdBU7ecWdmpkxzSC7.U6HnrNQ--&partNumber=1&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAQaCXVzLWVhc3QtMSJHMEUCIAH4W%2FrhlZBYETNUOjxJ6w7F3orenRlIkX%2BfhBM0V9r%2BAiEAijxxGQG9%2FodHiYgWI8Ico40BjFqzxTPjz5EqNgjWlJsqzAQILRAAGgw2MDQ3MzMwMDk0MDMiDIcNzCG6Ts%2BSju5KuCqpBHpufWy85XlevlAEv4CL84MPidv67kXIGgNZE1QMp%2FfH1ETjCKEQZoEv7i77XLhDW22xheaHRyg1T3vpPNRn6GBbO2jUn5WDeHpyfgPy78xm%2BGtn%2BLPCX6O8smSuVNLW53am7xb7QUuVgDtMblYfjIQ%2BnTZO9YszYbwhnaDI7V6SJhtqJRsOLFSSedmj22WtFf%2Bbw2zFdu0V%2BRfQlD0trwK3J5wvNL%2BBs1OxNxvDiy2%2BMQtJE4lTKz59JdaF0PstNlTrNNtOQP1OpqBruFm426AC30vXWglKuCC9X2yf%2BvqjWahzhbtPUzg4ILD6nzgytVcnjAYEpC39%2F4Z1bv5E%2BeNLY2dOuUFXa6KOtcdOFJfFWa2D3fAF7a5kzdvF%2Bq5PcM0stWmjMywWHLI32IeOjyumYRpOLHtH%2BkyNNUsPqRUpOXUPgjpzrb6Lvg4IDEH2YjJYTN5woYOW3OedTSX4aP2ZgrIRHOUubTxWiPAveemQxsIBktAaTdFqo5ni8pwUQq7cKymDPsL%2BpqJVSb%2BNg31KBY3h0aJ0mS26OUPcGo7tW6JTaelFAGiXRASXq6Eoz%2Byso4oosF8kFeC83AMVZ0vCotuKJqBHojH%2FsK8Zi0QnAk8yLsFgah2zoejAAFr7Ali8MNYOZowVnSOMiRnDnlMr4N1ktRFingdQ1CkT1f2vJ5ERYMyDbm6tHxHqaCM3m4%2BKANa08q3VDrFcji%2FO1QBoQQKyJEc1SPQwi%2B%2FBnAY6qQEpRV9jIR%2B3hdY8M%2BaCe7r9xImzHrmHBPc%2BxrkK4EP5gWxaZDs8Jfdp08BBG2T072%2FR9e4TfUprycO14B2z6YkhwSJThMDlQTvrJwztetAiXge5vttSTrnp6QA5UHvvpg8b2tn1LS3hHVNP5ghhj4QVNvdCpT9SPdN4G9g%2Fs8jjbRnDxNLz3URJi4qcFwAqYAu%2B7YfDJ50B%2FYJKA61PUSNk0O%2FmV6nfVgS7&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221207T130940Z&X-Amz-SignedHeaders=host&X-Amz-Expires=119&X-Amz-Credential=ASIAYZTHFNX522TA6XO4%2F20221207%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=d784e982910dc4ad0061ae05259ef9fbe6b52c0e61cd66c463d41f344592d3e2"
]
}
Note the uploadKey
and the urls
attributes, which you’ll use in the next steps.
Step 3: Initiate upload of a file to the signed URL
To upload the file to the signed URL, use a PUT method and the previously returned urls
attribute as the URI.
Note that a bearer token is not required.
Request
curl -X PUT --data-binary @D:\test_file.png "https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/e9367e98-68fd-41b5-9c6d-71e9f8887179?uploadId=[UPLOAD_ID]&partNumber=1&X-Amz-Security-Token=[AMZ_TOKEN]X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221207T130940Z&X-Amz-SignedHeaders=host&X-Amz-Expires=119&X-Amz-Credential=[AMZ_CREDENTIAL]%2F20221207%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=[AMZ_SIGNATURE]"
A successful call (``200``) returns an empty response.
Step 4: Complete the Upload
Use the bucket key (wip.dm.prod
) the object key (0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png
) and the upload key (AQICAHifrJ6-BSHUmjAat4QWI...cdWHJD90Ec7ZAaODsH_1LqXihzMNcJBA==
) to call POST buckets/:bucket_key/objects/:object_key/signeds3upload to complete the upload.
This endpoint needs to be called within 24 hours from the time you began uploading the file.
Request
curl -X POST -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" --data-raw '{"uploadKey":"AQICAHifrJ6-BSHUmjAat4..........QWI-fuvghN23akgePMdmykV"}' "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/2a6d61f2-49df-4d7b-9aed-439586d61df7.jpg/signeds3upload"
curl -X POST 'https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png/signeds3upload' \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-H 'Content-Type: application/json' \
--data-raw '{ "uploadKey":"AQICAHifrJ6-BSHUmjAat4QWI...cdWHJD90Ec7ZAaODsH_1LqXihzMNcJBA=="}'
Repsonse
{
"bucketKey" : "wip.dm.prod",
"objectId" : "urn:adsk.objects:os.object:wip.dm.prod/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png",
"objectKey" : "0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png",
"size" : 2393038,
"contentType" : "application/octet-stream",
"location" : "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/0ff06f5b-0f81-4d58-bd5c-16d204cd661e.png"
}
The file has been uploaded to the storage object.
Step 5: Update issue service that the file uploaded
Use the POST attachments/:attachmentId endpoint to update issues service that the file uploaded to oss (s3).
Use the container ID (6c8e8341-a4da-4959-a90d-e3b16c60ffd4
), the issue ID (ce382c8b-90da-4123-ae9e-414cd02c6427
), and the attachment ID (cdd1b6f9-9c05-46f4-92f4-8759fb00e42b
) from step 1.
Note that the ?task=post-upload-process
query parameter in this endpoint, use to update the server that the file was attached to attachment folder of the issue.
Request
curl -X POST 'https://developer.api.autodesk.com/issues/v2/containers/:containerId/issues/:issueId/attachments/:attachmentId?task=post-upload-process' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0' \
-H 'Content-Type: application/json'
Response
{
"id": "436aa3c4-9b79-4980-b2bd-1cdc274d34d5",
"issueId": "ce382c8b-90da-4123-ae9e-414cd02c6427",
"name": "test_file.png",
"urn": "urn:adsk.objects:os.object:wip.dm.prod/fc158b4f-3d78-4201-8d6b-8f319c068987.png",
"createdBy": "...",
"updatedBy": "...",
"createdAt": "2022-12-07T12:46:22.771Z",
"updatedAt": "2022-12-07T13:15:02.232Z",
"deletedAt": null,
"markupMetadata": null,
"attachmentType": "photo",
"status": "file-uploaded",
"urnType": "oss",
"wipUrn": null,
"deletedBy": null,
"permittedActions": [
"remove_attachment"
],
"permittedAttributes": [
"name"
]
}
Note that status
is set to file-uploaded.
Use the GET attachments endpoint to see status: "completed"
.
Congratulations! You have added a local attachment to an issue.