Retrieve Forma Assets Data
This tutorial demonstrates how to fetch your complete set of Forma Asset data and project settings. This can be for the entirety of your Asset data, or filtered to a subset of Asset data.
This set will include the assets themselves, as well as all of the surrounding Asset project settings:
- categories
- status sets / Asset statuses
- Asset custom attributes
- Assignments of status sets and Asset custom attributes to categories
Usage of pagination and batch-fetch endpoints are subject to rate limiting. For more details on Assets API rate limits, see the Assets Rate Limits.
Pagination
Most of the endpoints detailed below are paginated. Assets API uses cursor-based pagination, in which an opaque cursorState token is used to track the state of the pagination. Each paginated response will contain a results section, in which the relevant entities themselves will be returned, and a pagination section which will return the information needed to continue the pagination to fetch the full set of result entities. Pagination fields are described as follows -
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:readscope. - 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: Fetch Assets
To get the assets themselves, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v2/projects/:projectId/assets.
You will want to ensure you set the query parameter includeCustomAttributes=true if you wish to include Asset custom attribute data in your fetch. If you want to include deleted assets, you can set the query parameter includeDeleted=true as well.
If you want to fetch a more targeted set of assets, you can provide additional filters in your request. This could include filtering by category, status, a specific location or a location hierarchy, custom attribute value(s), or any combination thereof. A complete list of the filters available, and how they are used, can be found in the query parameter documentation for the asset pagination endpoint. Filters provided in the initial pagination request will automatically be added to the nextUrl field to continue the filtered pagination.
If you want to include only assets that have changed since previously retrieving assets, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...
Request
Response
Step 2: Fetch Categories
To get the categories, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/categories.
If you want to include only active categories, you can set the query parameter filter[isActive]=true. Note that filtering to only active or inactive categories can result in the returned tree not being fully intact.
If you want to include only categories that have changed since previously retrieving categories, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...
Request
Response
Step 3: Fetch Status Sets And Asset Statuses
To get the status sets, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/status-step-sets.
If you want to include deactivated status sets and Asset statuses, you can set the query parameter includeDeleted=true.
Note: If you just want to fetch the Asset statuses directly, you can call GET assets/v1/projects/:projectId/asset-statuses, but all statuses will be returned nested by fetching the full set of status sets as well.
If you want to include only status sets that have changed since previously retrieving status sets, you can use the query parameter filter filter[updatedAt]={previousFetchTime}... Note that this will only reflect updates to the status sets themselves, not any of the contained statuses. To fetch Asset statuses that have been changed since a given time, you can call GET assets/v1/projects/:projectId/asset-statuses with filter[updatedAt]={previousFetchTime}...
Request
Response
Step 4: Fetch Status Set to Category Assignments
To get the status set to category assignments, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) and category IDs obtained in Step 3 to call POST assets/v1/projects/:projectId/category-status-step-sets/status-step-sets:batch-get.
By default this will only return the status sets explicitly assigned to the given categories. If you wish to return each category’s effective status set assignment (taking inheritance into account), you can set the query parameter includeInherited=true.
Request
Response
Step 5: Fetch Asset Custom Attributes
To get the Asset custom attributes, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/custom-attributes.
If you want to include deactivated custom attributes, you can set the query parameter includeDeleted=true.
If you want to include only custom attributes that have changed since previously retrieving custom attributes, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...
Request
Response
Step 6: Fetch Category to Asset Custom Attribute Assignments
To get the Asset custom attributes assigned to a category, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) and category IDs obtained in Step 3 to call GET assets/v1/projects/:projectId/categories/:categoryId/custom-attributes.
A batch endpoint doe not yet exist for this call, so at this time a call must be made for each category ID individually to get the full set of assignments.
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 7: Fetch Locations
The Locations API can be used to fetch location data for the locationId field on an asset via the GET Nodes endpoint.
In this example the Project ID is f6a1e3b5-abaa-4b01-b33a-5d55f36ba047.
Request
Response
Step 8: Fetch Asset Relationships
Assets can be associated with other entities such as Issues, Forms, Photos, etc. You can use the Relationship API to search for all relationships associated with your project, or for a given Asset directly.
For the Relationship API, your Container ID will simply be your Project ID.
See the Relationship v2 APIs documentation.
You can search for all relationships in your project which include an “asset” type using the following query parameters:
Supported Related Domains and Types
Note that this list of Parameters is not exhaustive. More information on the Relationship API will be provided as it becomes available.
Also note that different Domains and Types are available for Forma asset relationships than for BIM30 asset relationships, and that this is not necessarily determined by the domain itself. For example, and issue in the autodesk-bim360-issue domain can be related to a Forma asset, as seen in the table below.
Example
In this example the Project ID and Relationship container ID is f6a1e3b5-abaa-4b01-b33a-5d55f36ba047. We would like to query the Relationship API for all relationships with assets within this project.
Request
Response
For more information on querying the Relationship API, see the Relationship Querying Tutorial.
Once you have the entities and their relationships to the given assets you can use the relevant APIs to fetch the data for the given entities. This may require setting up access to other APIs, depending on what type of entities are linked to your Assets. See Retrieve Issues and Get Forms Endpoint for examples of retrieving related entities.
Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/assets/retrieve-assets-data.