Create and update table relationships using the Web API

Article
06/12/2023

The Web API supports working with relationship definitions (metadata). The concepts described in Table relationship definitions also apply to the Web API.

Eligibility for relationships

Before you create a table (entity) relationship you should confirm whether the table is eligible to participate in the relationship. You can use the actions listed in the following table to determine eligibility. These actions correspond to the SDK for .NET messages described in Table relationship eligibility.

Action	Description
CanBeReferenced Action	Checks whether the specified entity can be the primary entity (one) in a one-to-many relationship.
CanBeReferencing Action	Checks whether the specified entity can be the referencing entity (many) in a one-to-many relationship.
CanManyToMany Action	Checks whether the entity can participate in a many-to-many relationship.
GetValidManyToMany Function	Returns the set of entities that can participate in a many-to-many relationship.
GetValidReferencedEntities Function	Returns the set of entities that are valid as the primary entity (one) from the specified entity in a one-to-many relationship.
GetValidReferencingEntities Function	Returns the set of entities that are valid as the related entity (many) to the specified entity in a one-to-many relationship.

Create a one-to-many relationship

When you create a one-to-many relationship, you define it by using the OneToManyRelationshipMetadata EntityType. This definition includes the lookup attribute, which is defined by using LookupAttributeMetadata EntityType and also requires complex properties using AssociatedMenuConfiguration ComplexType, CascadeConfiguration ComplexType, Label ComplexType and LocalizedLabel ComplexType. The lookup attribute is set to the Lookup single-valued navigation property of the OneToManyRelationshipMetadata object and gets created at the same time using deep insert. More information: Create related table rows in one operation and Table relationship metadata

If you want to apply a custom navigation property name for a one-to-many relationship you can set values for the ReferencingEntityNavigationPropertyName and ReferencedEntityNavigationPropertyName properties.

Once you have generated the necessary JSON to define the relationship and the lookup attribute, POST the JSON to the RelationshipDefinitions entity set. You must include the @odata.type property value of Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata to clarify the type of relationship you're creating because this same entity set is used to create many-to-many relationships. The uri for the resulting relationship is returned in the response.

Request:

POST [Organization URI]/api/data/v9.2/RelationshipDefinitions HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{  
 "SchemaName": "new_contact_new_bankaccount",  
 "@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",  
 "AssociatedMenuConfiguration": {  
  "Behavior": "UseCollectionName",  
  "Group": "Details",  
  "Label": {  
   "@odata.type": "Microsoft.Dynamics.CRM.Label",  
   "LocalizedLabels": [  
    {  
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
     "Label": "Bank Accounts",  
     "LanguageCode": 1033  
    }  
   ],  
   "UserLocalizedLabel": {  
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
    "Label": "Bank Accounts",  
    "LanguageCode": 1033  
   }  
  },  
  "Order": 10000  
 },  
 "CascadeConfiguration": {  
  "Assign": "Cascade",  
  "Delete": "Cascade",  
  "Merge": "Cascade",  
  "Reparent": "Cascade",  
  "Share": "Cascade",  
  "Unshare": "Cascade"  
 },  
 "ReferencedAttribute": "contactid",  
 "ReferencedEntity": "contact",  
 "ReferencingEntity": "new_bankaccount",  
 "Lookup": {  
  "AttributeType": "Lookup",  
  "AttributeTypeName": {  
   "Value": "LookupType"  
  },  
  "Description": {  
   "@odata.type": "Microsoft.Dynamics.CRM.Label",  
   "LocalizedLabels": [  
    {  
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
     "Label": "The owner of the account",  
     "LanguageCode": 1033  
    }  
   ],  
   "UserLocalizedLabel": {  
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
    "Label": "The owner of the account",  
    "LanguageCode": 1033  
   }  
  },  
  "DisplayName": {  
   "@odata.type": "Microsoft.Dynamics.CRM.Label",  
   "LocalizedLabels": [  
    {  
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
     "Label": "Account Owner",  
     "LanguageCode": 1033  
    }  
   ],  
   "UserLocalizedLabel": {  
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
    "Label": "Account Owner",  
    "LanguageCode": 1033  
   }  
  },  
  "RequiredLevel": {  
   "Value": "ApplicationRequired",  
   "CanBeChanged": true,  
   "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"  
  },  
  "SchemaName": "new_AccountOwner",  
  "@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata"  
 }  
}

Response:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
OData-EntityId: [Organization URI]/api/data/v9.2/RelationshipDefinitions(d475020f-5d7c-e511-80d2-00155d2a68d2)

Create a many-to-many relationship

If you want to apply a custom navigation property name for a many-to-many relationship, you can set values for the Entity1NavigationPropertyName and Entity2NavigationPropertyName properties.

Once you have generated the necessary JSON to define the relationship, POST the JSON to the RelationshipDefinitions entity set. You must include the @odata.type property value of Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata to clarify the type of relationship you're creating because this same entity set is used to create one-to-many relationships. The URI for the resulting relationship is returned in the response.

Request:

POST [Organization URI]/api/data/v9.2/RelationshipDefinitions HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{  
 "SchemaName": "new_accounts_campaigns",  
 "@odata.type": "Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata",  
 "Entity1AssociatedMenuConfiguration": {  
  "Behavior": "UseLabel",  
  "Group": "Details",  
  "Label": {  
   "@odata.type": "Microsoft.Dynamics.CRM.Label",  
   "LocalizedLabels": [  
    {  
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
     "Label": "Account",  
     "LanguageCode": 1033  
    }  
   ],  
   "UserLocalizedLabel": {  
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
    "Label": "Account",  
    "LanguageCode": 1033  
   }  
  },  
  "Order": 10000  
 },  
 "Entity1LogicalName": "account",  
 "Entity2AssociatedMenuConfiguration": {  
  "Behavior": "UseLabel",  
  "Group": "Details",  
  "Label": {  
   "@odata.type": "Microsoft.Dynamics.CRM.Label",  
   "LocalizedLabels": [  
    {  
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
     "Label": "Campaign",  
     "LanguageCode": 1033  
    }  
   ],  
   "UserLocalizedLabel": {  
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",  
    "Label": "Campaign",  
    "LanguageCode": 1033  
   }  
  },  
  "Order": 10000  
 },  
 "Entity2LogicalName": "campaign",  
 "IntersectEntityName": "new_accounts_campaigns"  
}

Response:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
OData-EntityId: [Organization URI]/api/data/v9.2/RelationshipDefinitions(420245fa-c77c-e511-80d2-00155d2a68d2)

Create relationships to support a multi-table lookup

Multi-table lookup type columns allow a user to use a specific table that has multiple one-to-many (1:M) relationships to other tables in the environment. A single lookup type column can refer to multiple other tables. A lookup value submitted to the multi-table type column will be matched to a record in any of the related tables.

More information: Use multi-table lookup columns

Update relationships

As discussed in Update table definitions, you update relationships using the HTTP PUT method to replace the existing definition with changes you want to apply. You can't edit individual properties using the HTTP PATCH method as you can with business data tables. Just like with entities and attributes, you should include a MSCRM.MergeLabels header with the value set to true to avoid overwriting localized labels not included in your update and you must publish customizations before they are active in the system.

Delete relationships

To delete a relationship using the Web API, use the HTTP DELETE method with the URI for the relationship.

Share via