Skip to main content

Introduction

Relation Types define typed connections between two Types. A relation connects an instance of the From type to an instance of the To type and can store its own attributes, enforce relationship constraints, and run trigger programs when the connection changes.

For example, a ProjectToTask relation can connect a Project to one or more Tasks. The related instances can then be displayed in relation widgets, queried through OData, or used by programs and workflows.

Relation Type settings​

SettingDescription
NameThe internal relation name. It is required and may contain letters and numbers only. After creation, the name should be treated as immutable because other schema elements can reference it.
Display NameThe label shown to administrators and users.
CardinalityControls how many instances can be connected at each end of the relation. Supported values include OneToOne, OneToMany, and ManyToMany.
Relationship ConstraintsDefines the From Type and To Type that the relation connects. A relation must have valid endpoint types before it can be used.
Allow DuplicateControls whether the same pair of instances can be connected more than once through the relation.
Allow Link Only on ScanRestricts linking through this relation to scan-based workflows.
AttributesAssociates reusable attributes with the relation itself. These values belong to the connection, not to either related instance.
Attribute Required ConditionsApplies conditional required rules to relation attributes.

Creating a relation​

  1. Open Admin App > Schema > Relation Types.
  2. Select Add and enter a unique internal Name and Display Name.
  3. Select the Cardinality.
  4. Add the relationship constraint and choose the From Type and To Type.
  5. Add any attributes that describe the relationship itself.
  6. Configure duplicate and scan-only linking behavior as needed.
  7. Select trigger programs for connect, disconnect, or update events when automation is required.
  8. Save the relation type and verify it from the related Types and layouts that use it.

Cardinality​

Cardinality determines the allowed number of connections:

CardinalityUse when
OneToOneEach instance can be connected to at most one instance at the other end.
OneToManyOne instance can connect to multiple instances, while each instance at the other end is limited to one connection.
ManyToManyBoth ends can connect to multiple instances.

The selected cardinality should reflect the business relationship before data is created. Tightening cardinality later can fail if existing connections do not satisfy the new constraint.

Relation attributes​

Relation attributes describe the link rather than the related records. For example, a ProjectToContractor relation could have a Role or Start Date attribute. Relation attributes are available to relation widgets, edit-relation forms, exports, and programs that operate on the connection.

Use Attribute Required Conditions when a relation attribute is required only under a particular rule or lifecycle condition. The referenced attribute must be included in the relation's attribute list.

Trigger programs​

Relation Types support trigger programs for these events:

Use pre-events to validate or prepare a change before it is committed. Use post-events to react after the connection or its relation attributes have been changed.

Using relations​

After a Relation Type is created, it can be used to:

  • Show related instances in a relation widget or View layout tab.
  • Create or link related instances from a parent record.
  • Filter and query related instances using the relation name and direction.
  • Read relation attributes separately from the attributes of the related Type.
  • Enforce access, validation, and automation rules around connections.

Use the exact relation name when configuring widgets, query definitions, OData $expand expressions, or programs. Relation names are case-sensitive in these references. Programs can retrieve related instances with InstanceService.GetRelatedInstances, and expressions can navigate relationships with @Relation.

Example​

The following configuration defines a one-to-many relationship from Project to Task:

{
"name": "ProjectToTask",
"displayName": "Project To Task",
"allowDuplicate": false,
"cardinality": "OneToMany",
"relationshipConstraints": [
{
"fromType": "Project",
"toType": "Task"
}
],
"attributes": [],
"selectedPreConnectTriggerPrograms": [],
"selectedPostConnectTriggerPrograms": [],
"selectedPreDisconnectTriggerPrograms": [],
"selectedPostDisconnectTriggerPrograms": [],
"selectedPreUpdateTriggerPrograms": [],
"selectedPostUpdateTriggerPrograms": []
}