Get/Create/Delete References(attachment) of ACC Entities by Relationship API

Follow @Xiaodong Liang

On ACC platform, there are a lot of entities such as issue, checklist, asset, working in their functional modules(domain). The specific entity is an instance of the types.  Some of them can be linked as bi-directional references. In ACC UI, the tab References allows you to add/remove the references. Relationships API runs as a shared API component under the hood, managing the references in projects.

GET Relationships

With a project id, we can get all relationships of the project in pages. Each relationship is a pair of domain>>type>>instance. The instance is represented by their ids. e.g. The demo below is a relationship of one photo and one sheet.

In most cases of reality, we may only to query specific relationships. Two smart ways are available with relationship API:

• Search: A GET call. With supplying explict pair of entities in the query parameters, the API call will return all relationships that match the provided parameters. This pair includes either domain+entityType+id, or domain+entityType or domain, e.g. the below call searches all relationships that include an entity in domain autodesk-construction-photo with type photo and also include another entity in domain autodesk-construction-sheet with type sheetlineage.

• Intersect:  A POST call. With supplying a set of entities in fully qualifier (domain+entityType+id), check if any of them have relationships. e.g. this payload will check if the asset, photo are referred with one issue, and if asset and photo has also relationship.

The Relationship Querying tutorial describes the supported relationship service entity types. Relationship API is compatible with BIM360 platform. The name of some domains and types are working for both ACC and BIM360 such as:  autodesk-bim360-asset, autodesk-bim360-issues, autodesk-bim360-documentmanagement, autodesk-bim360-rfi, autodesk-bim360-cost.

Create Relationships

The usage of creating relationship is straightforward. Given two instances id, type and domain, it will create new relationship between two entities. e.g. the request below will create relationship between ACC Photo and an Issue. You will need to call other APIs to get instance id in advance. e.g. Forms API to get form id, Photos API to get photo id.

If you specify the existing relationship's entities in a new relationship, but in reverse, you will also see a 2xx response and the existing relationship will be returned. i.e. the entity order is ignored.

Delete Relationships

The relationship deleting is also easy. The API supports to delete multiple relationships in one call, given the ids array of relationships. When a relationship is deleted, it is “soft” deleted, meaning it can still be retrieved from the search or intersect endpoints using the includeDeleted query parameter.

Supported Relationships

The table of supported relationships does not mean that each relationship type can be created against each other relationship type. The relationships service only permits relationships between specific relationship types. This is to ensure that users can't create relationships between types that aren't supported by the Reference Picker UI in ACC/Docs.

In addition, currently you may be able to create some relationships using the reference picker in the UI, GET the relationship using the read APIs, but you may not be able to create that relationship with the PUT relationships API, because some of them have not been exposed with 3-legged token support.

This is why Relationship API also delivered an endpoint to discover the relationship pairs which can be created: GET utility/relationships:writable.  It helps to determine whether a relationship is supported for the operations of creating/deleting. e.g. the returned data below indicates some supported relationships of Photo v.s. other entities types.