Autodesk Construction Cloud Submittals API Update - Manage Item Transitions & Attachments

We are pleased to announce that Autodesk has released a new set of Autodesk Construction Cloud (ACC) Submittals API endpoints, which are mainly for managing item transitions and attachments.

Submittals is one of the modules in Autodesk Build. It provides a tool to easily create and organize submittal items, such as shop drawings and specifications, to submit/notify for review and distribution among stakeholders, and to track progress and report. You can find information about the Submittals feature in the product help.

In this third phase of Submittals API, we have released eleven (11) new endpoints, where ten (10) are needed for managing item transitions and attachments, and one read-only endpoint for retrieving item revisions:

WRITE endpoints

POST item:transition: Transitions a submittal item in the submittal process workflow (Changing its state).
POST task:close: Closes a review task (Adding review comment and response).
PATCH update item: Updates attributes of an existing submittal item (Note: only fields listed in the permittedActions object can be modified).
POST attachments: Adds an attachment to a submittal item to include relevant files as part of the submittal process (transition).
PATCH update attachment: Updates the upload status of an attachment associated with an item. (Note: For attaching local files only)

READ endpoints

GET item revisions: Retrieves the revision history of a submittal item.
GET templates: Retrieves a list of submittal review templates for a project.
GET item steps: Retrieves a list of review steps associated with an item.
GET one item step: Retrieves information about a single review step associated with an item.
GET tasks: Retrieves a list of tasks associated with a review step of a submittal item, representing reviewers for the item.
GET one task: Retrieves details of a single task associated with a review step in an item.

Updates

POST items: Added a new field, `templateId,` to specify the submittal review template so that predefined steps and tasks can be applied when creating a submittal item.
- Note. Currently, the Submittals API does not support creating custom steps or tasks directly. Instead, the recommended approach is associating the submittal item with a review template that already includes predefined steps and tasks.

The following Q&A may answer some of your questions:

Q1. How do we know if we have corresponding permissions to interact with the Submittals API, for example, creating items, updating attachments, making item transitions?

A1. This is straightforward. We only need to check whether the permittedActions array in the response contains related objects. The permittedActions array reflects the permitted actions in submittals that the three-legged access token passed to the API call can do. A three-legged access token represents an actual user in an ACC project. So, what we can do with the Submittals API depends on the three-legged access token we passed to the API endpoints.

For example, here are some permitted actions we would use frequently when playing Submittals API. For more instructions, please check our tutorials.

"Item::create" - indicates the current user, the three-legged access token, is permitted to create a new submittal item.
"Item::partial_update" - indicates the current user is permitted to update the item.
"Item::wf_transition" - indicates the current user can transit the item to other states in the submittal process workflow.
"Attachment::create" - indicates the current user can create a new attachment.
"Attachment::partial_update" - indicates the current user can update the attachment.
"Task::close" - indicates the current user can add a review to the item under review state.

Q2. The API reference lists many fields in the request payload, e.g. POST item:transition, PATCH update item, or POST attachments. How do we know which field to pass when calling the API endpoint?

A2. First, API reference lists possible fields we can use for the API endpoints. However, in common cases, the submittal item's current state determines which field to use or which is required when calling the API. We can call corresponding API to check whether the permittedActions array in the response contains the objects related to the actions we want to perform, and check values in fields and mandatoryFields to determine which fields are supported and which are required.

fields - represents which field we can use when calling the API.
mandatoryFields - represents which field is required when calling the API.

Taking the tutorial step 5: Retrieve the Review Task and Step IDs as an example. We can see POST task:close support fields like "responseComment", "responseId", "saveAttachmentDrafts", and "duplicateAttachments" for the review task under the current state, and only the "responseId" is required. For more instructions, please check our tutorials.

{
   "id":"Task::close",
   "fields":{
      "responseComment":[],
      "responseId":[],
      "saveAttachmentDrafts":[],
      "duplicateAttachments":[]
   },
   "mandatoryFields":[
      "responseId"
   ],
   "transitions":[]
}

Q3. What is the value for "urnTypeId" when calling POST attachments?

A3. According to the API reference and tutorials related to add attachments(1)(2), the value for "urnTypeId" is always "2". API will return an error message when "urnTypeId" is not "2" when calling POST attachments.

Q4. How can I do when I forget specifying "isFileUploaded=true" when adding an attachment from ACC Files? The file status on ACC Web UI always shows "Uploading...".

A4. In supported workflow, PATCH update attachment works for attaching local files as attachments. However, to solve this issue, we could try to call PATCH update attachment to make "isFileUploaded=true" for that attachment. Before doing this, please ensure you have permission to update the attachment. We can call GET attachments to find the attachment we want to update and review if there is an object with id: "Attachment::partial_update" in the permittedActions array for that attachment.

Q5. How can I copy existing attachments when making item transitions, as the "Copy attachment" feature of ACC Web UI does?

A5. We can leverage the "duplicateAttachments" field when making item transitions by calling POST item:transition for non-review states or POST task:close when the item is under review (stateId: rev). Please check the blog post Copy attachments when transiting an item using Submittals API for detailed instructions.

Q6. What value will be for stepDueDate when making item transition from mgr-1 to rev?

A6. The stepDueDate value is calculated from the current date + daysToRespond in GET item steps.

Documentation

Field Guide: This page describes the terminology and background information about Submittals and Submittals API. It also includes information about the scope of the current release and its limitations.
Reference Guide: This section lists a set of endpoints for creating and retrieving submittal items and spec sections, as well as retrieving user permissions, submittal managers, packages, item types, responses, and attachments.
Tutorials
- Step-by-step Tutorial - Manage Submittal Item Transitions: This newly added page provides instructions on how to transition submittal items through the submittal lifecycle in an ACC project.
- Step-by-step Tutorial - Attach Files From the ACC Files Tool to Submittals: This newly added page provides instructions on how to attach files from the ACC Files tool, Files in Autodesk Docs, to a submittal item.
- Step-by-step Tutorial - Attach Local Files to Submittals: This newly added page provides instructions on how to attach local files to a submittal item.
- Updated Step-by-step Tutorial - Create a Submittal Item: This page has been updated to include a topic on how to create a submittal item with submittal review template.