0
# XRM WebAPI Client
1

2
XRM WebAPI Client is a comprehensive JavaScript framework for working with Microsoft Dynamics CRM/365 Web API. It provides both synchronous and asynchronous operations through promise-based architecture using Bluebird, supporting complete CRUD operations, advanced querying with FetchXML and OData, batch processing, and 200+ pre-implemented CRM actions.
3

4
## Package Information
5

6
- **Package Name**: xrm-webapi-client
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install xrm-webapi-client`
10

11
## Core Imports
12

13
```typescript
14
import * as WebApiClient from "xrm-webapi-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const WebApiClient = require("xrm-webapi-client");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import * as WebApiClient from "xrm-webapi-client";
27

28
// Configure the client
29
WebApiClient.ApiVersion = "9.0";
30
WebApiClient.ReturnAllPages = true;
31
WebApiClient.PrettifyErrors = false;
32

33
// Create a record
34
const accountId = await WebApiClient.Create({
35
    entityName: "account",
36
    entity: {
37
        name: "Contoso Corporation",
38
        telephone1: "555-0123",
39
        websiteurl: "https://contoso.com"
40
    }
41
});
42

43
// Retrieve a record
44
const account = await WebApiClient.Retrieve({
45
    entityName: "account",
46
    entityId: accountId,
47
    queryParams: "?$select=name,telephone1,websiteurl"
48
});
49

50
// Update a record
51
await WebApiClient.Update({
52
    entityName: "account",
53
    entityId: accountId,
54
    entity: { telephone1: "555-9999" }
55
});
56

57
// Delete a record
58
await WebApiClient.Delete({
59
    entityName: "account",
60
    entityId: accountId
61
});
62
```
63

64
## Architecture
65

66
XRM WebAPI Client is built around several key components:
67

68
- **Core Module**: Main CRUD operations and client configuration
69
- **Promise Integration**: Bluebird promises for cross-browser compatibility and advanced promise features
70
- **Batch Processing**: Transaction-based batch operations with change sets
71
- **Request Library**: 200+ pre-implemented CRM actions and functions
72
- **Type System**: Full TypeScript definitions with interfaces for all parameters and responses
73
- **Context Detection**: Automatic CRM context detection for forms, web resources, and external SPAs
74

75
## Capabilities
76

77
### CRUD Operations
78

79
Core create, retrieve, update, and delete operations for CRM entities with support for alternate keys, query parameters, and FetchXML.
80

81
```typescript { .api }
82
function Create(parameters: CreateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;
83
function Retrieve(parameters: RetrieveParameters): Promise<any> | any | BatchRequest;
84
function Update(parameters: UpdateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;
85
function Delete(parameters: DeleteParameters): Promise<string> | string | BatchRequest;
86

87
interface CreateParameters extends BaseParameters {
88
    entityName?: string;
89
    overriddenSetName?: string;
90
    entity: object;
91
}
92

93
interface RetrieveParameters extends BaseParameters {
94
    entityName?: string;
95
    overriddenSetName?: string;
96
    entityId?: string;
97
    alternateKey?: Array<Key>;
98
    queryParams?: string;
99
    fetchXml?: string;
100
    returnAllPages?: boolean;
101
}
102

103
interface UpdateParameters extends BaseParameters {
104
    entityName?: string;
105
    overriddenSetName?: string;
106
    entityId?: string;
107
    entity: object;
108
    alternateKey?: Array<Key>;
109
}
110

111
interface DeleteParameters extends BaseParameters {
112
    entityName?: string;
113
    overriddenSetName?: string;
114
    entityId?: string;
115
    alternateKey?: Array<Key>;
116
}
117
```
118

119
[CRUD Operations](./crud-operations.md)
120

121
### Entity Associations
122

123
Associate and disassociate operations for managing relationships between CRM entities.
124

125
```typescript { .api }
126
function Associate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;
127
function Disassociate(parameters: AssociationParameters): Promise<string> | string | BatchRequest;
128

129
interface AssociationParameters extends BaseParameters {
130
    relationShip: string;
131
    source: EntityReference;
132
    target: EntityReference;
133
}
134

135
interface EntityReference {
136
    entityName: string;
137
    entityId: string;
138
}
139
```
140

141
[Entity Associations](./entity-associations.md)
142

143
### Batch Processing
144

145
Transaction-based batch operations allowing multiple requests to be sent together with rollback capabilities.
146

147
```typescript { .api }
148
function SendBatch(batch: Batch): Promise<BatchResponse> | BatchResponse;
149

150
class Batch implements BatchParameters {
151
    name?: string;
152
    changeSets?: Array<ChangeSet>;
153
    requests?: Array<BatchRequest>;
154
    headers?: Array<Header>;
155
    async?: boolean;
156
    isOverLengthGet?: boolean;
157

158
    constructor(parameters: BatchParameters);
159
}
160

161
class BatchResponse implements BatchResponseParameters {
162
    name?: string;
163
    changeSetResponses?: Array<ChangeSetResponse>;
164
    batchResponses?: Array<Response>;
165
    isFaulted?: boolean;
166
    errors?: Array<string>;
167
    xhr?: XMLHttpRequest;
168

169
    constructor(parameters: BatchResponseParameters);
170
}
171
```
172

173
[Batch Processing](./batch-processing.md)
174

175
### CRM Actions and Functions
176

177
Execute pre-implemented CRM actions and functions, or create custom request objects.
178

179
```typescript { .api }
180
function Execute(request: object): Promise<any> | any | BatchRequest;
181

182
namespace Requests {
183
    class Request implements RequestParameters {
184
        method?: string;
185
        name?: string;
186
        bound?: boolean;
187
        entityName?: string;
188
        entityId?: string;
189
        payload?: object;
190
        headers?: Array<Header>;
191
        urlParams?: object;
192
        async?: boolean;
193

194
        with(param: RequestParameters): this;
195
    }
196
}
197
```
198

199
[CRM Actions and Functions](./crm-actions-functions.md)
200

201
### Configuration and Utilities
202

203
Client configuration, URL building, header management, and utility functions.
204

205
```typescript { .api }
206
import * as bluebird from "bluebird";
207

208
function GetApiUrl(): string;
209
function GetSetName(entity: string): string;
210
function SendRequest(method: string, url: string, payload: object, parameters?: BaseParameters): Promise<any> | any | BatchRequest;
211

212
// Configuration Properties
213
let ApiVersion: string;
214
let ReturnAllPages: boolean;
215
let PrettifyErrors: boolean;
216
let Async: boolean;
217
let ClientUrl: string;
218
let Token: string;
219
let Version: string;
220
let Promise: typeof bluebird;
221
```
222

223
[Configuration and Utilities](./configuration-utilities.md)
224

225
## Core Types
226

227
```typescript { .api }
228
interface BaseParameters {
229
    async?: boolean;
230
    headers?: Array<Header>;
231
    asBatch?: boolean;
232
    apiVersion?: string;
233
}
234

235
interface Header {
236
    key: string;
237
    value: string;
238
}
239

240
interface Key {
241
    property: string;
242
    value: string | number;
243
}
244
```