Define related objects in a data model

Related objects, also known as foreign-key relationships or references, are connections between objects in a data source. Including related objects in your data model enables workflow process builders to traverse objects when configuring workflows (shown in the animation below), select properties across them, and query multiple objects for data read and write steps. This topic explains the requirements to define these relationships in the data model that your data IO extension app returns to Docusign.

Display related objects in workflow configuration screens

If you want Docusign to display related objects in workflow configuration screens, your extension app must include foreign-key relationships in the Get Type Definitions response. Docusign sends a Get Type Definitions request to retrieve object and property details from an external data source. If the response defines object relationships, process builders will be able to navigate among objects and select their properties when defining data read and write steps.

Below is an example from a Get Type Definitions response that specifies a relationship between the Account object’s msrecord2 property and the MasterRecordId object.

{
  "$class": "concerto.metamodel@1.0.0.ConceptDeclaration",
  "name": "Account",
  "isAbstract": false,
  "properties": [
    {
      "$class": "concerto.metamodel@1.0.0.StringProperty",
      "name": "Id",
      "isArray": false,
      "isOptional": false,
      "decorators": [
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Term",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Account ID"
            }
          ]
        },
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Crud",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Readable"
            }
          ]
        }
      ],
      "lengthValidator": {
        "$class": "concerto.metamodel@1.0.0.StringLengthValidator",
        "minLength": 0,
        "maxLength": 18
      }
    },
    {
      "$class": "concerto.metamodel@1.0.0.RelationshipProperty",
      "name": "msRecord2",
      "type": {
        "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
        "name": "MasterRecordId"
      },
      "isArray": false,
      "isOptional": true,
      "decorators": [
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Term",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Master Record Relationship"
            }
          ]
        },
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Crud",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Createable,Readable,Updateable"
            }
          ]
        }
      ]
    }
  ],
  "identified": {
    "$class": "concerto.metamodel@1.0.0.IdentifiedBy",
    "name": "Id"
  },
  "decorators": [
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "name": "Term",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Account"
        }
      ]
    },
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "name": "Crud",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Createable,Readable,Updateable"
        }
      ]
    }
  ]
}

Below are descriptions of key relationship elements:

"type": {
  "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
  "name": "MasterRecordId"
}

{
  "$class": "concerto.metamodel@1.0.0.Decorator",
  "name": "Term",
  "arguments": [
    {
      "$class": "concerto.metamodel@1.0.0.DecoratorString",
      "value": "Master Record Relationship"
    }
  ]
}

Based on the example relationship property definition, the workflow step configuration screen displays Master Record as a related object under the Account object, as shown below. A process builder can navigate from the Account object to the Master Record object and select properties in both objects.

Example data model with related objects

This example from a data model defined in a model.cto file shows a portion of an Account object definition. It includes an msRecord2 property that is defined as a relationship, indicated by the --> notation.

See the model.cto file in the data IO reference implementation for additional relationship examples.

@Term("Account")
@Crud("Createable,Readable,Updateable")
concept Account identified by Id {
	@Term("Account ID")
	@Crud("Readable")
	o String Id length=[0, 18]
	@Term("Account Name")
	@Crud("Createable,Readable,Updateable")
	o String Name optional
	@Term("Master Record Relationship")
	@Crud("Createable,Readable,Updateable")
	--> MasterRecordId msRecord2 optional
}

Frequently asked questions

Can I build workflows with foreign-key relationships across multiple objects?

Yes. If the data model that your extension app returns to Docusign includes related objects, you can traverse those objects when configuring data read and write steps in a workflow. See Display related objects in workflow configuration screens for details.

Are one-to-many (1:M) relationships supported?

Yes, Docusign supports one-to-many relationships.

Are nested relationships supported?

Yes. For example, the Account object can have a relationship to the MasterRecordId object, which in turn can have a relationship to the Address object.

Is there a limit on the number of related objects?

No, Docusign does not limit the number of related objects that can be returned in a Get Type Definitions response.

Next steps

• Review the requirements for data model definitions.
• Get details about the structure of the Get Type Definitions response.
• Find out about options to test an extension app.
• Get started with data IO by cloning the data IO reference implementation.