Manage Submittal Item Transitions
This tutorial demonstrates how to transition submittal items through the submittal lifecycle for a Forma project. The steps include verifying the user’s permissions and transitioning the submittal item to different states.
For more information about working with submittals, see the Help documentation.
Before You Begin
-
Acquire a 3-legged OAuth token with
data:readdata:writescopes. -
Verify that you have access to the relevant hub and Forma project.
-
Find the relevant project ID for the project you want to create an item in by following the Retrieve a Forma Hub ID and Project ID tutorial. In this example, assume the project ID is
91b5ea71-e3ea-495b-999d-57443a8af6a4. -
Ensure you have assigned manager-level permissions to at least one user for the project via the UI. You will need to assign the submittal item to a user with manager-level permissions during the tutorial. For instructions on setting up roles and permissions see the Help documentation.
-
This tutorial assumes an item was created in Submit state
sbc-1by a user with manager permissions. For more information on creating a submittal item, see the Create a Submittal Item tutorial. -
This tutorial assumes that a review workflow has already been added to the item and that the workflow includes one step with one required task. Currently, the Submittals API does not support creating custom steps or tasks directly. The recommended approach is to associate the submittal item with a review template that already includes predefined steps and tasks. See the Create Submittal Items tutorial (step 6) for more details.
-
Some transitions, such as transitioning to the Review (
rev) state, require a custom identifier. For more information on custom numbering and retrieving the next sequential identifier, see Step 4 of the Create a Submittal Item Tutorial. -
The Submittal Item workflow progresses through several sequential states. Below are the states in the UI and their equivalent API names:
Step 1: Verify User Permissions
Call GET item using the project ID (2570d4e5-9aef-4b41-8e45-a454f2f3fd65) and the item ID (2ae22463-83d2-4f1a-9b2f-6898e616bfc3) to retrieve the relevant permissions for the user for the submttal item in Submit (sbc-1) state.
-
Look for the
permittedActionsarray in the response. -
Verify that the user can transition the submittal item by checking that the object with
id: "Item::wf_transition"appears in this array. -
Find the relevant transition in the
transitionsarray within this object (e.g.,"sbc-1::mgr-1"for theSubmit to Managertransition). -
You need to note two sets of mandatory fields for transitioning the submittal item:
> - General mandatory fields: These are listed under
"mandatoryFields"in the object withid: "Item::wf_transition". > - Specific mandatory fields: These are listed under"mandatoryFields"in thetransitionsarray for the specific transition (e.g.,"sbc-1::mgr-1").
Note that calling GET item at any stage in the workflow will return the permitted actions for the user at that point in the workflow for that submittal item.
Request
Response
-
Locate the
permittedActionsarray. -
Within the
permittedActionsarray, identify the object withid: "Item::wf_transition". This object contains two types of mandatory fields:> - General mandatory fields: Listed under the
mandatoryFieldsproperty of theItem::wf_transitionobject itself. These apply to actions related to workflow transitions in general. This includesstateId-mgr-1. This indicates the target state. > - Specific mandatory fields: Found within thetransitionsarray inside theItem::wf_transitionobject. Each transition (e.g.,sbc-1::mgr-1) includes its ownmandatoryFieldsproperty that lists fields required specifically for that transition. This includesmanagerandmanagerType, which specify the manager assigned to the submittal and the type of manager.
Step 2: Transition the Submittal Item to Prepare for Review (mgr-1) State
To promote the submittal item in the workflow and transition it from Submit (sbc-1) state to Prepare for Review (mgr-1) state, use POST item:transition.
Use the following mandatory values collected in Step 1:
stateId: The target state ID (mgr-1).manager: The assigned manager’s ID (MFEGJ9W5GGQL).managerType: The type of manager (1).
Request
Response
The submittal item has transitioned to mgr-1 state.
Step 3: Retrieve Details for Transition to Review (rev) State
Before transitioning from Prepare for Review (mgr-1) state to Review (rev) state, you need to use the project ID and item ID to call GET item to retrieve the information necessary for the transition (mgr-1::rev).
-
Look for the
permittedActionsarray in the response. -
Verify that the user can transition the submittal item by checking that the transition object appears (
id: Item::wf_transition). -
Find the relevant transition in the transitions array (
Submit to Review - "mgr-1::rev"). -
You need to note 2 sets of mandatory fields you will need to transition the submittals item:
> - The general mandatory fields (
"permittedActions"."mandatoryFields"). > - Mandatory fields for this transition (permittedActions."id": "Item::wf_transition"."transitions"."mandatoryFields").
Request
Response
Note the following values from the response, located within the Item::wf_transition object:
- General mandatory fields: These are listed under the
mandatoryFieldsproperty of theItem::wf_transitionobject itself. For example,stateIdindicates the target state (revin this case). - Specific mandatory fields for the transition
mgr-1::rev:These are located in themandatoryFieldsproperty within the relevant transition object in thetransitionsarray. For example,customIdentifieris required for this specific transition.
Step 4: Transition to Review (rev) State
Use POST item:transition to transition the submittal item to Review (rev) state, using the values retrieved in Step 3:
stateId: The target state ID (rev).customIdentifier: A unique identifier for the item. You can set it either before or as part of the transition request. In this example, it was set beforehand when creating the item.
As mentioned earlier, this tutorial assumes the submittal item already has a review workflow (steps and tasks associated with the item). This is a prerequisite for transitioning the item to the rev state. Once transitioned, the first review step will turn in-progress and become active.
Request
Response
Note the stateId which is now in the Review (rev) state.
Step 5: Retrieve the Review Task and Step IDs
Once transitioned to the Review (rev) state, the first review step and task will start and become in-progress.
In submittals, a task represents a specific review action within a step. Each task corresponds to a review being carried out, with details about the assigned reviewer provided for context. The main objective of this step is to retrieve the Step ID and Task ID required to perform actions in later steps (e.g., submitting the reviewer’s review in Step 7).
Additionally, the API identifies Task::close in the permittedActions array, defining the allowed action for submitting the reviewer’s review. This action requires specific fields, such as responseId, to be provided in POST task/🆔close, ensuring the review is submitted and the workflow progresses.
Request
Response
Note the following:
- Step ID (
results.id):e00a643d-e862-4be1-a6a3-aaa6acb118f0- identifies the review step. - Task ID (
results.tasks.id):00369989-8bf3-4ed2-beaf-99352393688c- identifies the active task for the review. - Mandatory Fields for Task Closure: Within the
permittedActionsarray, locate the object withid: "Task::close". ThemandatoryFieldsproperty of this object lists the required fields. For example,responseIdis required to submit the reviewer’s review. Task::closeAction: This action allows the reviewer to submit their review, transitioning the task’s status fromin-progresstocompletedwithin the review workflow. TheresponseIdfield is mandatory for this action, as described in Step 7.- Assigned Reviewer (
results.tasks.assignedTo): TheassignedTofield (MFEGJ9W5GGQL) provides the user ID of the reviewer.
Step 6: Retrieve the List of Possible Responses
To complete the review, the reviewer must submit a response. Use GET responses to fetch the available options.
Request
Response
Select the appropriate Response ID (results.id) to complete the review in the next step. For example, 38ffb07d-d734-4aa6-bbf4-cb121c56972f for Approved.
Step 7: Submit the Reviewer’s Review
The reviewer submits a review by adding the selected response using POST task/🆔close.
As seen in Step 5, the Task::close permitted action requires the responseId field, and optionally, a responseComment can be included. When the last required task in a review step is submitted, the item transitions to the next step. If this is the final review step in the Review (rev) state, the workflow automatically advances to the Close and Distribute (mgr-2) state.
Request
Response
Note that the status field in the Task model is now updated to completed, indicating that the reviewer has submitted their review. This action transitions the workflow to the next step, as appropriate.
Step 8: Transition to Close and Distribute (mgr-2)
After each reviewer completes their assigned task (representing their review), the system transitions the workflow automatically to the Close and Distribute (mgr-2) state. To confirm the transition or check for additional tasks or steps, start by calling GET steps. This will verify whether there are any remaining tasks or review steps.
Once you confirm that all tasks and review steps are complete, use GET item to verify the submittal’s overall state and retrieve the permitted actions required for transitioning to the Closed (sbc-2) state.
Request
Response
Note the following:
- State ID:
mgr-2confirms that the submittal is in the Close and Distribute state, indicating readiness for the next transition. - Permitted Actions: The
permittedActionsarray includes the transition withid='mgr-2::sbc-2'. Ensure that this transition is listed and note the required field, such asresponseId, which is mandatory for progressing to the Closed (sbc-2) state.
Step 9: Close the Submittal Item
To close the submittal item, transition it to the Closed (sbc-2) state using POST item:transition. See Step 6 for the required responseId.
Request
Response
- The
stateIdis nowsbc-2, confirming the submittal has transitioned to the Closed state. - The
statusIdis3, indicating that the submittal item is officially closed and the workflow is complete.
Congratulations! You have successfully transitioned submittal items through their lifecycle in Forma.
Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/submittals/submittal-transitions.rst.