Skip to navigation
How-to GuideRelationships

Create Relationships

View as Markdown

This tutorial demonstrates how to create a relationship between two entities (for example, an asset and a document). The steps include verifying compatibility of entity types in the Relationships service, finding information about the entities you want to create a relationship for, and creating the relationship between the entities. For information about the Relationships API, see the Field Guide.

Note that in order to create a relationship between two entities, the entities must already exist, and the caller must have permission to access both entities in the proposed relationship.

Before You Begin

  • Register an app, and select the Data Management and BIM 360 APIs.
  • Acquire a 3-legged OAuth token with data:create data:read and data:write scopes.
  • Verify that you have access to the relevant hub, project, folder and contents.
  • Find the relationships container ID for the relevant project.

Note that this tutorial assumes you are familiar with the BIM 360 Assets and Document Management APIs.

Step 1: Verify Entity Compatibility

You first need to check whether the entities you want to associate with each other are compatible.

To verify compatibility, call GET utility/relationships:writable, and find the object containing the relationship domain and entity type you want to create a relationship against. For example, check whether you can create a relationship between an asset and a document. The asset domain is autodesk-bim360-asset, and the entity type is asset. In this example, the allow attribute contains an array of entity types that assets can have a relationship with. For a list of domains and their entity types, see the Relationship Querying tutorial.

Note that some domains have a bim360 prefix, and others have a construction prefix.

Request

curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/utility/relationships:writable' \
     -H 'Authorization: Bearer <token>'

Response (200)

[
 {
   "domain": "autodesk-bim360-asset",
   "entityTypes": [
     {
       "entityType": "asset",
       "allow": [
         {
           "domain": "autodesk-bim360-documentmanagement",
           "entityTypes": [
             "documentlineage"
           ]
         },
         {
           "domain": "autodesk-construction-photo",
           "entityTypes": [
             "photo"
           ]
         },
         {
           "domain": "autodesk-construction-form",
           "entityTypes": [
             "form"
           ]
         }
       ]
     },
     {
       "entityType": "category",
       "allow": [
         {
           "domain": "autodesk-construction-form",
           "entityTypes": [
             "formtemplate"
           ]
         }
       ]
     }
   ]
 }
 (...)
 {
       "domain": "autodesk-construction-photo",
       "entityTypes": [
           {
               "entityType": "photo",
               "allow": [
                   {
                       "domain": "autodesk-bim360-asset",
                       "entityTypes": [
                           "asset"
                       ]
                   },
                   {
                       "domain": "autodesk-construction-form",
                       "entityTypes": [
                           "form",
                           "formfield"
                       ]
                   }
               ]
           }
       ]
 }
]

Step 2: Find Information About Entities

You need to find information about the entities you want to create a relationship for. For example, to create a relationship between an asset and a document, you need to call GET assets to find the ID of the asset, and GET folders/:folder_id/contents to find the ID of the document.

Step 3: Create a Relationship

To create relationships between compatible entities, use the information you found in the previous steps and the container ID to call PUT containers/:containerId/relationships. Note that one entity may be related to a batch of up to 20 entities within a single API call.

In this example, we are creating a relationship between an asset and a document.

Example Request

curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/fbd6cb57-7d0e-4961-8c2c-69646514ef44/relationships' \
    -X PUT \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    -d '[
            {
                "entities": [
                    {
                        "domain": "autodesk-bim360-asset",
                        "type": "asset",
                        "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0"
                    },
                    {
                        "domain": "autodesk-bim360-documentmanagement",
                        "type": "documentlineage",
                        "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w"
                    }
                ]
            }
        ]'

Example Response

[
 {
     "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f",
     "createdOn": "2021-10-21T16:32:22Z",
     "isReadOnly": false,
     "isService": false,
     "isDeleted": false,
     "entities": [
         {
             "domain": "autodesk-bim360-asset",
             "type": "asset",
             "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0"
         },
         {
             "domain": "autodesk-bim360-documentmanagement",
             "type": "documentlineage",
             "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w"
         }
     ]
 }
]

Note that you can create relationships by supplying your own relationship IDs (UUID). For example, you can choose to use b544a7eb-3c64-4a56-a7ff-392d0441015f as the ID. If the ID is already in use, the server will reject the request with an HTTP 409 Conflict error.

Example Request

curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/fbd6cb57-7d0e-4961-8c2c-69646514ef44/relationships' \
    -X PUT \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    -d '[
            {
                "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f",
                "entities": [
                    {
                       "domain": "autodesk-bim360-asset",
                        "type": "asset",
                        "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0"
                    },
                    {
                        "domain": "autodesk-bim360-documentmanagement",
                        "type": "documentlineage",
                        "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w"
                    }
                ]
            }
        ]'

Example Conflict Response

{
    "conflict": [
        {
            "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f",
            "actual": {
                "id": "74b70bb8-8802-a1fd-f201-890375a60c8f",
                "createdOn": "2021-10-21T16:32:22Z",
                "isReadOnly": false,
                "isService": false,
                "isDeleted": false,
                "entities": [
                    {
                       "domain": "autodesk-bim360-asset",
                        "type": "asset",
                        "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0"
                    },
                    {
                        "domain": "autodesk-bim360-documentmanagement",
                        "type": "documentlineage",
                        "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w"
                    }
                ]
            }
        }
    ]
}

Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/relationships/relationships-create.