Setup Forma Assets Project Settings
This tutorial demonstrates how to setup a new Forma project’s Asset settings. This will include:
- Creating new categories
- Creating new status sets with Asset statuses
- Creating new Asset custom attributes
- Assigning status sets to the desired categories
- Assigning Asset custom attributes to the desired categories
- Adding relationships between categories and other entities (e.g. form templates)
For more details about Forma Assets API, see the Assets Field Guide.
Before You Begin
- Register an app, and select the Data Management and Forma APIs.
- Acquire a 3-legged OAuth token with
data:createdata:readanddata:writescopes. - Verify that you have access to the relevant Forma hub, project, and folder.
- Retrieve the relevant Forma hub and project ID. In this tutorial we will use the example project ID
f6a1e3b5-abaa-4b01-b33a-5d55f36ba047, but you should replace that with the project ID you have retrieved for your project.
Step 1: Create Categories
Categories are the core organizational structure for assets. Every asset must have a category assignment. The category of an asset in turn determines which Asset statuses are valid for the asset, as well as which custom attributes the asset has. For more discussion on how assets, categories, status sets / statuses, and custom attributes all fit together conceptually, please see the Assets Field Guide Data Model.
To create a category, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call POST assets/v1/projects/:projectId/categories.
Every project has a ROOT category created automatically that cannot be altered. When creating a new category, a parentId must be included. For the first category creation(s), you may need to call GET assets/v1/projects/:projectId/categories to obtain the ROOT category ID to use as the parentId. In this tutorial we will use the example ROOT category ID 123, but you should replace that with the ROOT category ID you have retrieved for your project.
[2022-10-08] You can now add a query parameter includeUid to return the universally unique category ID for the category. This universally unique ID will be generated upon creation regardless of the query parameter, but will not be included in the response unless flagged to do so. This universally unique category ID will be used with upcoming versions of category APIs.
Request
Response
There is no batch-create API for categories at this time, so each desired category must be created individually. Create requests are subject to the relevant rate limits. For more details on Assets API rate limits, see the Assets Rate Limits.
Step 2: Create Status Sets and Statuses
Every project has a Default status set created automatically. If additional status sets are desired, status sets and Asset statuses can be created in conjunction to reduce API calls.
To create a status set with statuses, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call POST assets/v1/projects/:projectId/status-step-sets.
Request
Response
If you wish to add more statuses to the status set, you can use POST assets/v1/projects/:projectId/asset-statuses to create statuses directly.
There is no batch-create API for status sets or statuses at this time, so each desired status set must be created individually. Create requests are subject to the relevant rate limits. For more details on Assets API rate limits, see the Assets Rate Limits.
Step 3: Assign Status Sets to Categories
Once the desired categories and status sets with statuses have been created, you can assign status sets to categories to specify which statuses are available to assets in the given category.
To assign a status set to a category, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047), category ID (124), and status set ID (6eb35939-e5fb-453a-98ed-e2e11f326e73) to call PUT assets/v1/projects/:projectId/categories/:categoryId/status-step-set/:statusStepSetId. Note: there is no body for this request.
Request
Response
There is no batch API for status set to category assignments at this time, so each assignment must be created individually. Create requests are subject to the relevant rate limits. For more details on Assets API rate limits, see the Assets Rate Limits.
Step 4: Create Custom Attributes
To create custom attributes, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call POST assets/v1/projects/:projectId/custom-attributes.
The exact schema of the body to create a custom attribute depends on the type of custom attribute being created -
Request
Response
There is no batch-create API for Assets custom attributes at this time, so each Assets custom attribute must be created individually. Create requests are subject to the relevant rate limits. For more details on Assets API rate limits, see the Assets Rate Limits.
Step 5: Assign Custom Attributes to Categories
Once the desired categories and custom attributes have been created, you can assign custom attributes to categories to specify which attributes are available to assets in the given category.
To assign a custom attribute to a category, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047), category ID (124), and custom attribute ID (3063f212-6ce9-494e-b749-eb73b4445bf0) to call PUT assets/v1/projects/:projectId/categories/:categoryId/custom-attributes/:customAttributeId.
This endpoints will return the custom attributes assigned to the given category. By default this will only return the custom attributes explicitly assigned to the given category. If you wish to return the full set of custom attributes assigned to the given category, you can set the query parameter includeInherited=true. When includeInherited=true is set, an additional field will be included in the response for each returned custom attribute inheritedFromCategoryId which will indicate from which explicit category assignment the custom attribute is inherited from.
Request
Response
Step 6: Create Category Attachments
Once the desired categories have been created, you can attach form templates to the categories to specify which forms are available to assets in a given category.
You can obtain the available form template IDs for your project using GET forms/v1/projects/:projectId/form-templates. In this tutorial we will use the example form template ID 2f634a22-779d-4930-9f08-8391a41fea05, but you should replace that with your own form template ID.
To attach a form template to a category, the preferred means is to use the Relationship API. For more information on how to create relationships please see Create Relationships tutorial</en/docs/bim360/v1/tutorials/relationships/relationships-create/>.
[2022-10-08] It is preferred to create category relationships with the new universally unique category ID. The type with which to create you category relationship depends on which type of category ID you are using - to create a realtionship with the new universally unique category ID, please use the "type": "categoryuid", to create a realtionship with the legacy category integer ID, please use "type": "category". The example below uses the new categoryuid type along with the universally unique category ID obtained above fc24ff3b-1ad9-4327-a91d-84700bc16a5e.
Request
Response
Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/assets/create-assets-project-settings.