General
This article describes the internal workflow logic, actions, and processing behavior of the Autodesk Forma Module. It is intended for advanced configuration and troubleshooting.
For general behavior, see: [CROSS-REFERENCE: Autodesk Forma Module Overview]
For client configuration, see: [CROSS-REFERENCE: Autodesk Forma Client Setup]
Transaction Processing Flow
The module processes transactions in the following order:
- Read incoming structure and metadata
- Create folder structure
- Evaluate document existence
- Create or update items
- Apply metadata and custom attributes
Each step depends on the previous step being completed successfully.
Preprocess Workflow Actions
Get Custom Attribute Definitions
Purpose
Fetches all custom attribute definitions from the target folder.
Behavior
- Stores definitions in the transaction property
Definitions - Enables mapping of attribute names to definition IDs
Usage
- Must run before any attribute updates
- Placed in preprocess workflow between "Has Document Mode" and "Document Workflow"
Get Item Action
Purpose
Determines whether a file already exists.
Behavior
- Checks folder contents
- Sets status to Exist or New
- Supports version-aware detection
Add the action in the Preprocess Document workflow and place it at the top.
Required Parameters
- ParentReferenceId (source folder reference)
- DisplayName (file name)
Structure Workflow Actions
Create Folder Structure
Purpose
Ensures required folder hierarchy exists.
Behavior
- Checks if folder exists
- Creates folder if missing
- Stores resolved folder identifiers
This action is used in the structure workflow and should be used it the beginning of the workflow.
Required Parameter
- FolderName (mapped from source)
Output
- Target folder identifiers used by document actions
Document Workflow Actions
Workflow example:
Item Exist Action
Purpose
Evaluates existence status from previous step.
Behavior
- Returns true if item exists
- Returns false if item is new
Create Item Action
Purpose
Creates a new file in Autodesk Forma.
Behavior
- Resolves target folder
- Uploads file
- Creates initial version
Required Parameters
- DisplayName
PreMapped Properties
- APIParentReferenceIdKey
- APIItemIdKey
Update Item Action
Purpose
Uploads a new version to an existing item.
Behavior
- Adds version to existing file
- Maintains version sequence
Required Parameters
- DisplayName
Custom Attribute Handling
Update Custom Attribute Action
Purpose
Applies metadata to a specific version.
Behavior
- Reads VersionId
- Uses stored Definitions
- Maps attribute names to IDs
- Sends update request
Important Notes
- Attributes must exist in Autodesk Forma
- Matching is based on attribute name
- Missing attributes are skipped with warning
Attribute Mapping
Each attribute requires:
- Name matching Autodesk Forma definition
- Value mapped from source metadata
Incoming custom attribute values from the transaction are presented in the transaction JSON.
Version Processing Logic
When multiple versions exist:
- Oldest version is created first
- Subsequent versions are added sequentially
- Metadata is applied per version
This guarantees accurate version history replication.
Error Handling and Throttling
The module must handle Autodesk API limits.
Behavior under throttling
- Requests may be delayed
- Retries may occur
- Temporary failures possible
Mitigation
- Enable rate limiter in client
- Reduce request volume
- Optimize workflow design
Best Practices
- Always fetch attribute definitions before updating metadata
- Ensure folder structure is created before document processing
- Use consistent attribute naming
- Limit transaction size when possible
- Validate mappings carefully