tessl/npm-xrm-webapi-client

Comprehensive JavaScript framework for Microsoft Dynamics CRM/365 WebAPI integration with promise-based CRUD operations, batch processing, and 200+ pre-implemented actions

Overview

Eval results

Files

Entity Associations

Name: tessl/npm-xrm-webapi-client
Author: tessl

Associate and disassociate operations for managing many-to-many and one-to-many relationships between CRM entities. These operations manage the connection records that link entities together through relationship definitions.

Capabilities

Associate Operation

Creates a relationship between two entity records using the relationship schema name.

/**
 * Create an association between two entity records
 * @param parameters - Association operation parameters
 * @returns Promise resolving to association confirmation
 */
function Associate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;

interface AssociationParameters extends BaseParameters {
    /** Relationship schema name (e.g., "account_primary_contact", "systemuserroles_association") */
    relationShip: string;
    /** Source entity reference */
    source: EntityReference;
    /** Target entity reference */
    target: EntityReference;
}

interface EntityReference {
    /** Entity logical name */
    entityName: string;
    /** Entity record GUID */
    entityId: string;
}

Usage Examples:

// Associate a contact as primary contact for an account
await WebApiClient.Associate({
    relationShip: "account_primary_contact",
    source: {
        entityName: "account",
        entityId: "12345678-1234-1234-1234-123456789abc"
    },
    target: {
        entityName: "contact",
        entityId: "87654321-4321-4321-4321-cba987654321"
    }
});

// Associate an opportunity with an account (many-to-one)
await WebApiClient.Associate({
    relationShip: "opportunity_customer_accounts",
    source: {
        entityName: "opportunity",
        entityId: "11111111-2222-3333-4444-555555555555"
    },
    target: {
        entityName: "account",
        entityId: "66666666-7777-8888-9999-aaaaaaaaaaaa"
    }
});

// Associate users with security roles (many-to-many)
await WebApiClient.Associate({
    relationShip: "systemuserroles_association",
    source: {
        entityName: "systemuser",
        entityId: "user-guid-here"
    },
    target: {
        entityName: "role",
        entityId: "role-guid-here"
    }
});

// Associate a team with a security role
await WebApiClient.Associate({
    relationShip: "teamroles_association",
    source: {
        entityName: "team",
        entityId: "team-guid-here"
    },
    target: {
        entityName: "role",
        entityId: "role-guid-here"
    }
});

// Associate queue items with queues
await WebApiClient.Associate({
    relationShip: "queue_entries",
    source: {
        entityName: "queue",
        entityId: "queue-guid-here"
    },
    target: {
        entityName: "queueitem",
        entityId: "queueitem-guid-here"
    }
});

Disassociate Operation

Removes a relationship between two entity records using the relationship schema name.

/**
 * Remove an association between two entity records
 * @param parameters - Disassociation operation parameters
 * @returns Promise resolving to disassociation confirmation
 */
function Disassociate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;

Usage Examples:

// Remove primary contact association from account
await WebApiClient.Disassociate({
    relationShip: "account_primary_contact",
    source: {
        entityName: "account",
        entityId: "12345678-1234-1234-1234-123456789abc"
    },
    target: {
        entityName: "contact",
        entityId: "87654321-4321-4321-4321-cba987654321"
    }
});

// Remove opportunity-account relationship
await WebApiClient.Disassociate({
    relationShip: "opportunity_customer_accounts",
    source: {
        entityName: "opportunity",
        entityId: "11111111-2222-3333-4444-555555555555"
    },
    target: {
        entityName: "account",
        entityId: "66666666-7777-8888-9999-aaaaaaaaaaaa"
    }
});

// Remove user from security role
await WebApiClient.Disassociate({
    relationShip: "systemuserroles_association",
    source: {
        entityName: "systemuser",
        entityId: "user-guid-here"
    },
    target: {
        entityName: "role",
        entityId: "role-guid-here"
    }
});

// Remove team from security role
await WebApiClient.Disassociate({
    relationShip: "teamroles_association",
    source: {
        entityName: "team",
        entityId: "team-guid-here"
    },
    target: {
        entityName: "role",
        entityId: "role-guid-here"
    }
});

Common Relationship Names

Here are some frequently used relationship schema names:

Account Relationships

account_primary_contact - Account to primary contact
account_parent_account - Parent account relationship
opportunity_customer_accounts - Opportunity to account

Contact Relationships

contact_customer_accounts - Contact to account (customer)
opportunity_customer_contacts - Opportunity to contact

User and Team Relationships

systemuserroles_association - User to security role
teamroles_association - Team to security role
teammembership_association - User to team membership

Lead and Opportunity Relationships

lead_customer_accounts - Lead to account
lead_customer_contacts - Lead to contact
opportunity_customer_accounts - Opportunity to account
opportunity_customer_contacts - Opportunity to contact

Case and Knowledge Relationships

incident_customer_accounts - Case to account
incident_customer_contacts - Case to contact
knowledgearticle_category - Knowledge article to category

Batch Operations

Association and disassociation operations can be included in batch requests for transactional processing:

// Create batch with association operations
const batch = new WebApiClient.Batch({
    changeSets: [
        new WebApiClient.ChangeSet({
            requests: [
                WebApiClient.Associate({
                    relationShip: "account_primary_contact",
                    source: { entityName: "account", entityId: accountId },
                    target: { entityName: "contact", entityId: contactId },
                    asBatch: true
                }),
                WebApiClient.Associate({
                    relationShip: "opportunity_customer_accounts",
                    source: { entityName: "opportunity", entityId: opportunityId },
                    target: { entityName: "account", entityId: accountId },
                    asBatch: true
                })
            ]
        })
    ]
});

const batchResponse = await WebApiClient.SendBatch(batch);

Error Handling

Association operations may fail if:

The relationship name is incorrect
One or both entities don't exist
The relationship already exists (for one-to-many relationships)
Security permissions don't allow the association
Required fields are missing on the relationship entity

try {
    await WebApiClient.Associate({
        relationShip: "account_primary_contact",
        source: { entityName: "account", entityId: accountId },
        target: { entityName: "contact", entityId: contactId }
    });
} catch (error) {
    console.error("Association failed:", error);
    // Handle specific error conditions
}

Finding Relationship Names

To find the correct relationship schema names:

Navigate to Settings > Customizations > Developer Resources in CRM
Click Download OData Metadata
Search the XML file for relationship definitions
Look for NavigationProperty elements and their Relationship attributes
The relationship name is typically in format: entity1_entity2 or entity1_relationshipname_entity2