Attach BIM 360 Document Management Files to Issues (new)
This tutorial demonstrates how to attach BIM 360 Document Management files to an issue. The steps include verifying the item ID of the file that you uploaded to BIM 360 Document Management and attaching the file to an issue. For information about uploading the file to BIM 360 Docs, see the Upload Document tutorial.
Before You Begin
- Register an app
- Acquire a 3-legged OAuth token with
data:create
data:read
anddata:write
scopes. - Upload the file to BIM 360 Document Management. See the Upload Document tutorial for instructions.
- Verify the ID of the issue you want to attach the file to. For more details see the Retrieve Issue IDs tutorial.
- Verify that you have access to the relevant BIM 360 account and BIM 360 project.
- (To create a new issue, see the Create Issues tutorial)
Step 1: Find the Hub ID for the BIM 360 Account
The first few steps of the tutorial demonstrate how to find the item ID for the file that you want to attach to the issue, which invovles iterating through several Forge Data Management endpoints..
Call GET hubs to find the hub ID for the BIM 360 account that contains the file that you want to attach to the issue.
Note that the BIM 360 account ID corresponds to a Data Management hub ID. To convert an account ID into a hub ID you need to add a “b." prefix. For example, an account ID of c8b0c73d-3ae9 translates to a hub ID of b.c8b0c73d-3ae9.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" "https://developer.api.autodesk.com/project/v1/hubs"
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/project/v1/hubs"
}
},
"data": [
{
"type": "hubs",
"id": "b.cGVyc29uYWw6cGUyOWNjZjMy",
"attributes": {
"name": "My First Account",
"extension": {
"type": "hubs:autodesk.bim360:Account",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.bim360:Account-1.0"
},
"data": {}
}
}
}
]
}
In this example, assume that the issue that contains the file that you want to attach is called My First Account
hub.
Find the hub (data.name
), and note the hub ID - b.cGVyc29uYWw6cGUyOWNjZjMy
.
Step 2: Find the Project ID
Use the hub ID (b.cGVyc29uYWw6cGUyOWNjZjMy
) to call GET hubs/:hub_id/projects to get a list of all the projects in the hub. Find the project ID of the project that contains the file that you want to attach to the issue.
Note that the project ID in BIM 360 corresponds to the project ID in the Data Management API. To convert a project ID in BIM 360 to a project ID in the Data Management API, you need to add a “b." prefix. For example, a project ID of a4be0c34a-4ab7 translates to a project ID of b.a4be0c34a-4ab7.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" "https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects"
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects"
}
},
"data": [
{
"type": "projects",
"id": "b.cGVyc29uYWw6d2l",
"attributes": {
"name": "My First Project",
"extension": {
"type": "projects:autodesk.core:Project",
"version": "1.0"
}
},
"relationships": {
"hub": {
"data": {
"type": "hubs",
"id": "b.cGVyc29uYWw6cGUyOWNjZjMy"
},
"links": {
"related": {
"href": "https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy"
}
}
},
"rootFolder": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.O7ZwaiGAQOueskTkQqPoxQ"
}
},
"issues": {
"data": {
"type": "issueContainerId",
"id": "be00f32e-c03c-4c7b-9ec4-d2614bf1980c"
}
}
}
}
]
}
In this example, assume that My First Project
is the project that contains the file that you want to attach to the issue.
Find the project (data.attributes.name
), and note the project ID (data.attributes.id
) - b.cGVyc29uYWw6d2l
.
Step 3: Find the Project Files or Plans Folder ID
Use the hub ID (b.cGVyc29uYWw6cGUyOWNjZjMy
) and the project ID (b.cGVyc29uYWw6d2l
) to call GET hubs/:hub_id/projects/:project_id/topFolders to get the Project Files folder and Plans Folder IDs.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
"https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects/b.cGVyc29uYWw6d2l/topFolders"
Response
{
"jsonapi": {
"version": "1.0"
},
"data": [
{
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA",
"attributes": {
"name": "Project Files",
"displayName": "Project Files",
"createTime": "2017-07-17T13:06:56.0000000Z",
"createUserId": "",
"createUserName": "",
"lastModifiedTime": "2017-09-24T07:46:08.0000000Z",
"lastModifiedUserId": "X9WYLGPNCHSL",
"lastModifiedUserName": "John Smith",
"objectCount": 4,
"hidden": false,
"extension": {
"type": "folders:autodesk.bim360:Folder",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
},
"data": {
"visibleTypes": [
"items:autodesk.bim360:File"
],
"actions": [
"CONVERT"
],
"allowedTypes": [
"items:autodesk.bim360:File",
"folders:autodesk.bim360:Folder"
]
}
}
}
}
]
}
Assume that the file is in the Project Files folder (data.attributes.name
), and note the folder ID (data.id
) - urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA
If you want to attach a document from a folder nested under the Project Files folder, you need to call GET projects/:project_id/folders/:folder_id/contents repeatedly through the hierarchy of folders until you find the Folder ID of the folder you want to upload the document to. For the first iteration, use the Project Files ID (urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA
).
Step 4: Find the Item ID for the File
Use the project ID (b.cGVyc29uYWw6d2l
) and the Projet Files folder ID (urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA
) to call GET projects/:project_id/folders/:folder_id/contents to get the item ID for the file.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
"https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/folders/urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA/contents"
Response
{
"jsonapi": {
"version": "1.0"
},
"data": [
{
"type": "items",
"id": "urn:adsk.wip:dm.lineage:SNQsll0mTReGtfPcbEuboC",
"attributes": {
"displayName": "My First File.dwg",
"createTime": "2017-11-27T14:01:17.0000000Z",
"createUserId": "X9WYLGPNCHVK",
"createUserName": "John Smith",
"lastModifiedTime": "2017-11-27T14:01:48.0000000Z",
"lastModifiedUserId": "X9WYLGPNCHVK",
"lastModifiedUserName": "John Smith",
"hidden": false,
"reserved": false,
"extension": {
"type": "items:autodesk.bim360:File",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/items:autodesk.bim360:File-1.0"
},
"data": {
"sourceFileName": "My First File.dwg"
}
}
},
"relationships": {
"storage": {
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/72d5e7e4-89a7-4cb9-9da0-2e2bbc61ca8e.dwg"
},
"meta": {
"link": {
"href": "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/72d5e7e4-89a7-4cb9-9da0-2e2bbc61ca8e.dwg"
}
}
}
}
}
]
}
In this example, assume that My First Files
is the file that you want to attach.
Find the file (data.attributes.displayName
) and note the item ID (data.type
) - urn:adsk.wip:dm.lineage:SNQsll0mTReGtfPcbEuboC
.
Step 5: Attach the File to the Issue
Use the container ID (6c8e8341-a4da-4959-a90d-e3b16c60ffd4
), the issue ID (98b84d33-b8a8-49e4-bc37-83ecdaff9a75
), and the item ID (urn:adsk.wip:dm.lineage:SNQsll0mTReGtfPcbEuboC
) to call POST issues/attachments.
Note that the request payload urnType
must be dm
.
Note that you cannot upload a file to a closed issue.
Request
curl --location --request POST 'https://developer.api.autodesk.com/issues/v2/containers/6c8e8341-a4da-4959-a90d-e3b16c60ffd4/issues/98b84d33-b8a8-49e4-bc37-83ecdaff9a75/attachments' \
--header 'Authorization: Bearer 0123456789ABCDEF' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "document to issue",
"urnType": "dm",
"urn": "urn:adsk.wip:dm.lineage:SNQsll0mTReGtfPcbEuboC"
}'
Response
{
"id": "8c81f143-b631-4b4a-be51-6b86adba5e26",
"name": "document to issue",
"urnType": "dm",
"urn": "urn:adsk.wip:dm.lineage:SNQsll0mTReGtfPcbEuboC",
"status": "completed",
"attachmentType": "document",
"issueId": "98b84d33-b8a8-49e4-bc37-83ecdaff9a75",
"clientVersion": {
"origin": "",
"appName": null,
"browser": "",
"isIosApp": null,
"serviceId": "...",
"appVersion": null,
"user_agent": "...",
"isAndroidApp": null,
"browserVersion": ""
},
"updatedAt": "2022-10-18T12:59:34.587Z",
"createdAt": "2022-10-18T12:59:34.587Z",
"createdBy": "...",
"updatedBy": "...",
"deletedAt": null,
"urnPage": ...,
"markupMetadata": ...,
"resourceUrns": ...,
"urnVersion": ...,
"wipUrn": ...,
"setWipUrnRetries": ...,
"deletedBy": ...,
"sync_version": ...,
"permittedActions": [
"remove_attachment"
],
"permittedAttributes": [
"name"
]
}
Congratulations! You have added an attachment to an issue.