Associate and disassociate table rows using the SDK for .NET

Table rows are associated to each other using lookup columns on the related table row. The simplest way to associate two rows in a one-to-many relationship is to use an EntityReference to set the value of a lookup column on the related row.

The simplest way to disassociate two rows in a one-to-many relationship is to set the value of the lookup column to null.

Relationships using a many-to-many relationship also depend on lookup columns on the intersect entity that supports the many-to-many relationship. Relationship are defined by the existence of rows in that intersect entity. While you can interact with the intersect entity directly, it's much easier to use the API to do this task for you.

Use the Associate method or AssociateRequest

The main value in using the IOrganizationService.Associate method or the AssociateRequest with the IOrganizationService.Execute method is that you can:

• Associate multiple rows in one operation
• Easily associate rows using a many-to-many relationship without concerning yourself with the intersect entity.

To associate table rows with these APIs you need three things:

• An entity reference to the row you want to associate
• The name of the relationship
• One or more references that you want to associate the table row to

Whether the relationship is a one-to-many or many-to-many relationship doesn't matter. The parameters or properties are equivalent.

You can discover the names of the relationships by viewing the customization UI or in the metadata using the Metadata Browser.

More information:

• Create and edit 1:N (one-to-many) or N:1 (many-to-one) relationships
• Create and edit many-to-many (N:N) table row relationships
• Browse the metadata for your environment

The following example creates a relationship and associates a primary entity with a collection of related entities.

C#

/// <summary>
/// Associate a primary entity with one or more other entities,
/// then remove the association.
/// </summary>
/// <param name="service">Authenticated web service connection.</param>
/// <param name="primaryEntity">Primary entity for the association.</param>
/// <param name="relationship">Type of relationship between the entities.</param>
/// <param name="relatedEntities">Related entities to associate with the primary entity.</param>
/// <returns>True if successful; otherwise false.</returns>
static public bool AssociateDisassociate(IOrganizationService service,
    EntityReference primaryEntity, string relationship,
    EntityReferenceCollection relatedEntities
    )
{
    // Define the type of relationship between the entities.
    var relation = new Relationship(relationship);

    try
    {
        // Associate the primary entity with the related entities.
        service.Associate(primaryEntity.LogicalName, primaryEntity.Id,
                    relation, relatedEntities);

        Console.WriteLine(
            $"AssociateDisassociate(): The entities have been associated.");

        // Disassociate the primary entity with the related entities.
        service.Disassociate(primaryEntity.LogicalName, primaryEntity.Id,
            relation, relatedEntities);

        Console.WriteLine(
            $"AssociateDisassociate(): The entities have been disassociated.");
        return true;
    }
    catch (Exception ex)
    {
        Console.WriteLine(
            $"AssociateDisassociate(): {ex.Message}");
        return false;
    }
}

Complete code sample: AssociateDisassociate

If you wanted to use the AssociateRequest, you would use the following code. A benefit of using the request instead of the service client method is that the request supports the use of optional parameters.

C#

AssociateRequest request = new AssociateRequest()
{
RelatedEntities = relatedEntities,
Relationship = relation,
Target = primaryEntity
};

service.Execute(request);

Let's say we are associating a primary entity (a contact) with three related entities (accounts). This single association operation shown above is the same as three separate update operations where the Account.PrimaryContactId lookup column is set. Instead, the simpler service client method or request call is using the account_primary_contact relationship which establishes a many-to-one entity relationship on each related account and a one-to-many entity relationship on the contact.

If you examine the properties of the relationship columns, you can see that the ReferencingEntity value is account and the ReferencingAttribute value is primarycontactid.

Use the Disassociate method or DisassociateRequest

The IOrganizationService.Disassociate method or the DisassociateRequest with the IOrganizationService.Execute method are just the reverse of the way that you associate table rows.

You can view an example Disassociate method call in the previously shown code sample. If you wanted to use the DisassociateRequest, the code would look like this:

C#

DisassociateRequest request = new DisassociateRequest()
{
RelatedEntities = relatedEntities,
Relationship = relation,
Target = primaryEntity
};

service.Execute(request);

See also

Create table rows using the SDK for .NET
Retrieve a table row using the SDK for .NET
Update and delete table rows using the SDK for .NET