0
# Entity Associations
1

2
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.
3

4
## Capabilities
5

6
### Associate Operation
7

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

10
```typescript { .api }
11
/**
12
 * Create an association between two entity records
13
 * @param parameters - Association operation parameters
14
 * @returns Promise resolving to association confirmation
15
 */
16
function Associate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;
17

18
interface AssociationParameters extends BaseParameters {
19
    /** Relationship schema name (e.g., "account_primary_contact", "systemuserroles_association") */
20
    relationShip: string;
21
    /** Source entity reference */
22
    source: EntityReference;
23
    /** Target entity reference */
24
    target: EntityReference;
25
}
26

27
interface EntityReference {
28
    /** Entity logical name */
29
    entityName: string;
30
    /** Entity record GUID */
31
    entityId: string;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
// Associate a contact as primary contact for an account
39
await WebApiClient.Associate({
40
    relationShip: "account_primary_contact",
41
    source: {
42
        entityName: "account",
43
        entityId: "12345678-1234-1234-1234-123456789abc"
44
    },
45
    target: {
46
        entityName: "contact",
47
        entityId: "87654321-4321-4321-4321-cba987654321"
48
    }
49
});
50

51
// Associate an opportunity with an account (many-to-one)
52
await WebApiClient.Associate({
53
    relationShip: "opportunity_customer_accounts",
54
    source: {
55
        entityName: "opportunity",
56
        entityId: "11111111-2222-3333-4444-555555555555"
57
    },
58
    target: {
59
        entityName: "account",
60
        entityId: "66666666-7777-8888-9999-aaaaaaaaaaaa"
61
    }
62
});
63

64
// Associate users with security roles (many-to-many)
65
await WebApiClient.Associate({
66
    relationShip: "systemuserroles_association",
67
    source: {
68
        entityName: "systemuser",
69
        entityId: "user-guid-here"
70
    },
71
    target: {
72
        entityName: "role",
73
        entityId: "role-guid-here"
74
    }
75
});
76

77
// Associate a team with a security role
78
await WebApiClient.Associate({
79
    relationShip: "teamroles_association",
80
    source: {
81
        entityName: "team",
82
        entityId: "team-guid-here"
83
    },
84
    target: {
85
        entityName: "role",
86
        entityId: "role-guid-here"
87
    }
88
});
89

90
// Associate queue items with queues
91
await WebApiClient.Associate({
92
    relationShip: "queue_entries",
93
    source: {
94
        entityName: "queue",
95
        entityId: "queue-guid-here"
96
    },
97
    target: {
98
        entityName: "queueitem",
99
        entityId: "queueitem-guid-here"
100
    }
101
});
102
```
103

104
### Disassociate Operation
105

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

108
```typescript { .api }
109
/**
110
 * Remove an association between two entity records
111
 * @param parameters - Disassociation operation parameters
112
 * @returns Promise resolving to disassociation confirmation
113
 */
114
function Disassociate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
// Remove primary contact association from account
121
await WebApiClient.Disassociate({
122
    relationShip: "account_primary_contact",
123
    source: {
124
        entityName: "account",
125
        entityId: "12345678-1234-1234-1234-123456789abc"
126
    },
127
    target: {
128
        entityName: "contact",
129
        entityId: "87654321-4321-4321-4321-cba987654321"
130
    }
131
});
132

133
// Remove opportunity-account relationship
134
await WebApiClient.Disassociate({
135
    relationShip: "opportunity_customer_accounts",
136
    source: {
137
        entityName: "opportunity",
138
        entityId: "11111111-2222-3333-4444-555555555555"
139
    },
140
    target: {
141
        entityName: "account",
142
        entityId: "66666666-7777-8888-9999-aaaaaaaaaaaa"
143
    }
144
});
145

146
// Remove user from security role
147
await WebApiClient.Disassociate({
148
    relationShip: "systemuserroles_association",
149
    source: {
150
        entityName: "systemuser",
151
        entityId: "user-guid-here"
152
    },
153
    target: {
154
        entityName: "role",
155
        entityId: "role-guid-here"
156
    }
157
});
158

159
// Remove team from security role
160
await WebApiClient.Disassociate({
161
    relationShip: "teamroles_association",
162
    source: {
163
        entityName: "team",
164
        entityId: "team-guid-here"
165
    },
166
    target: {
167
        entityName: "role",
168
        entityId: "role-guid-here"
169
    }
170
});
171
```
172

173
## Common Relationship Names
174

175
Here are some frequently used relationship schema names:
176

177
### Account Relationships
178
- `account_primary_contact` - Account to primary contact
179
- `account_parent_account` - Parent account relationship
180
- `opportunity_customer_accounts` - Opportunity to account
181

182
### Contact Relationships
183
- `contact_customer_accounts` - Contact to account (customer)
184
- `opportunity_customer_contacts` - Opportunity to contact
185

186
### User and Team Relationships
187
- `systemuserroles_association` - User to security role
188
- `teamroles_association` - Team to security role
189
- `teammembership_association` - User to team membership
190

191
### Lead and Opportunity Relationships
192
- `lead_customer_accounts` - Lead to account
193
- `lead_customer_contacts` - Lead to contact
194
- `opportunity_customer_accounts` - Opportunity to account
195
- `opportunity_customer_contacts` - Opportunity to contact
196

197
### Case and Knowledge Relationships
198
- `incident_customer_accounts` - Case to account
199
- `incident_customer_contacts` - Case to contact
200
- `knowledgearticle_category` - Knowledge article to category
201

202
## Batch Operations
203

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

206
```typescript
207
// Create batch with association operations
208
const batch = new WebApiClient.Batch({
209
    changeSets: [
210
        new WebApiClient.ChangeSet({
211
            requests: [
212
                WebApiClient.Associate({
213
                    relationShip: "account_primary_contact",
214
                    source: { entityName: "account", entityId: accountId },
215
                    target: { entityName: "contact", entityId: contactId },
216
                    asBatch: true
217
                }),
218
                WebApiClient.Associate({
219
                    relationShip: "opportunity_customer_accounts",
220
                    source: { entityName: "opportunity", entityId: opportunityId },
221
                    target: { entityName: "account", entityId: accountId },
222
                    asBatch: true
223
                })
224
            ]
225
        })
226
    ]
227
});
228

229
const batchResponse = await WebApiClient.SendBatch(batch);
230
```
231

232
## Error Handling
233

234
Association operations may fail if:
235

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

242
```typescript
243
try {
244
    await WebApiClient.Associate({
245
        relationShip: "account_primary_contact",
246
        source: { entityName: "account", entityId: accountId },
247
        target: { entityName: "contact", entityId: contactId }
248
    });
249
} catch (error) {
250
    console.error("Association failed:", error);
251
    // Handle specific error conditions
252
}
253
```
254

255
## Finding Relationship Names
256

257
To find the correct relationship schema names:
258

259
1. Navigate to **Settings > Customizations > Developer Resources** in CRM
260
2. Click **Download OData Metadata**
261
3. Search the XML file for relationship definitions
262
4. Look for `NavigationProperty` elements and their `Relationship` attributes
263
5. The relationship name is typically in format: `entity1_entity2` or `entity1_relationshipname_entity2`