Skip to content

Commit 9f6f855

Browse files
AleksandrRogovAleksandrRogov
committed
add functions to work with relationship definitions
1 parent f83adf9 commit 9f6f855

6 files changed

+1539
-177
lines changed

‎README.md

+158-1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@ Any suggestions are welcome!
4949
* [Update Attribute](#update-attribute)
5050
* [Retrieve Multiple Attributes](#retrieve-multiple-attributes)
5151
* [Use requests to query Entity and Attribute metadata](#use-requests-to-query-entity-and-attribute-metadata)
52+
* [Create Relationship](#create-relationship)
53+
* [Update Relationship](#update-relationship)
54+
* [Delete Relationship](#delete-relationship)
55+
* [Retrieve Relationship](#retrieve-relationship)
56+
* [Retrieve Multiple Relationships](#retrieve-multiple-relationships)
5257
* [Formatted Values and Lookup Properties](#formatted-values-and-lookup-properties)
5358
* [Using Alternate Keys](#using-alternate-keys)
5459
* [Making requests using Entity Logical Names](#making-requests-using-entity-logical-names)
@@ -253,7 +258,7 @@ As well as multi-level expands are not implemented yet. This situation may be ch
253258
For complex requests to Web API with multi-level expands use `executeFetchXml` function.
254259

255260
Starting from version 1.2.8, all requests to Web API that have long URLs (more than 2000 characters) are automatically converted to a Batch Request.
256-
This feature is very convenient if you are trying to make a call using big Fetch XMLs. No special parameters needed to do a convertation.
261+
This feature is very convenient when you make a call with big Fetch XMLs. No special parameters needed to do a convertation.
257262

258263
### Create a record
259264

@@ -1202,6 +1207,158 @@ You can also use common request functions to create, retrieve and update entity
12021207
5. During entity or attribute metadata update you can use `mergeLabels` property to set **MSCRM.MergeLabels** attribute. By default `mergeLabels: false`.
12031208
6. To send entity or attribute definition use `entity` property.
12041209

1210+
### Create Relationship
1211+
1212+
```js
1213+
var newRelationship = {
1214+
"SchemaName": "dwa_contact_dwa_dynamicswebapitest",
1215+
"@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",
1216+
"AssociatedMenuConfiguration": {
1217+
"Behavior": "UseCollectionName",
1218+
"Group": "Details",
1219+
"Label": {
1220+
"@odata.type": "Microsoft.Dynamics.CRM.Label",
1221+
"LocalizedLabels": [
1222+
{
1223+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1224+
"Label": "DWA Test",
1225+
"LanguageCode": 1033
1226+
}
1227+
],
1228+
"UserLocalizedLabel": {
1229+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1230+
"Label": "DWA Test",
1231+
"LanguageCode": 1033
1232+
}
1233+
},
1234+
"Order": 10000
1235+
},
1236+
"CascadeConfiguration": {
1237+
"Assign": "Cascade",
1238+
"Delete": "Cascade",
1239+
"Merge": "Cascade",
1240+
"Reparent": "Cascade",
1241+
"Share": "Cascade",
1242+
"Unshare": "Cascade"
1243+
},
1244+
"ReferencedAttribute": "contactid",
1245+
"ReferencedEntity": "contact",
1246+
"ReferencingEntity": "dwa_dynamicswebapitest",
1247+
"Lookup": {
1248+
"AttributeType": "Lookup",
1249+
"AttributeTypeName": {
1250+
"Value": "LookupType"
1251+
},
1252+
"Description": {
1253+
"@odata.type": "Microsoft.Dynamics.CRM.Label",
1254+
"LocalizedLabels": [
1255+
{
1256+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1257+
"Label": "The owner of the test",
1258+
"LanguageCode": 1033
1259+
}
1260+
],
1261+
"UserLocalizedLabel": {
1262+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1263+
"Label": "The owner of the test",
1264+
"LanguageCode": 1033
1265+
}
1266+
},
1267+
"DisplayName": {
1268+
"@odata.type": "Microsoft.Dynamics.CRM.Label",
1269+
"LocalizedLabels": [
1270+
{
1271+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1272+
"Label": "DWA Test Owner",
1273+
"LanguageCode": 1033
1274+
}
1275+
],
1276+
"UserLocalizedLabel": {
1277+
"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
1278+
"Label": "DWA Test Owner",
1279+
"LanguageCode": 1033
1280+
}
1281+
},
1282+
"RequiredLevel": {
1283+
"Value": "ApplicationRequired",
1284+
"CanBeChanged": true,
1285+
"ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
1286+
},
1287+
"SchemaName": "dwa_TestOwner",
1288+
"@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata"
1289+
}
1290+
};
1291+
1292+
dynamicsWebApi.createRelationship(newRelationship).then(function (relationshipId) {
1293+
//relationshipId is a PrimaryKey (MetadataId) for a newly created relationship
1294+
}).catch(function (error) {
1295+
//catch errors
1296+
});
1297+
```
1298+
### Update Relationship
1299+
1300+
**Important!** Make sure you set **`MetadataId`** property when you update the metadata, DynamicsWebApi use it as a primary key for the EntityDefinition record.
1301+
1302+
```js
1303+
var metadataId = '10cb680e-b6a7-e811-816a-480fcfe97e21';
1304+
1305+
dynamicsWebApi.retrieveRelationship(metadataId).then(function (relationship) {
1306+
relationship.AssociatedMenuConfiguration.Label.LocalizedLabels[0].Label = "New Label";
1307+
return dynamicsWebApi.updateRelationship(relationship);
1308+
}).then(function (updateResponse) {
1309+
//check update response
1310+
}).catch(function (error) {
1311+
//catch errors
1312+
});
1313+
```
1314+
1315+
### Delete Relationship
1316+
1317+
```js
1318+
var metadataId = '10cb680e-b6a7-e811-816a-480fcfe97e21';
1319+
1320+
dynamicsWebApi.deleteRelationship(metadataId).then(function (isDeleted) {
1321+
//isDeleted should be true
1322+
}).catch(function (error) {
1323+
//catch errors
1324+
});
1325+
```
1326+
1327+
### Retrieve Relationship
1328+
1329+
```js
1330+
var metadataId = '10cb680e-b6a7-e811-816a-480fcfe97e21';
1331+
1332+
dynamicsWebApi.retrieveRelationship(metadataId).then(function (relationship) {
1333+
//work with a retrieved relationship
1334+
}).catch(function (error) {
1335+
//catch errors
1336+
});
1337+
```
1338+
1339+
You can also cast a relationship into a specific type:
1340+
1341+
```js
1342+
var metadataId = '10cb680e-b6a7-e811-816a-480fcfe97e21';
1343+
var relationshipType = 'Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata';
1344+
dynamicsWebApi.retrieveRelationship(metadataId, relationshipType).then(function (relationship) {
1345+
//work with a retrieved relationship
1346+
}).catch(function (error) {
1347+
//catch errors
1348+
});
1349+
```
1350+
1351+
### Retrieve Multiple Relationships
1352+
1353+
```js
1354+
dynamicsWebApi.retrieveRelationships(['SchemaName', 'MetadataId'], "ReferencedEntity eq 'account'")
1355+
.then(function (relationship) {
1356+
//work with a retrieved relationship
1357+
}).catch(function (error) {
1358+
//catch errors
1359+
});
1360+
```
1361+
12051362
#### Examples
12061363

12071364
Retrieve entity metadata with attributes (with common properties):

‎lib/dynamics-web-api-callbacks.js

+113-1
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,9 @@ function DynamicsWebApi(config) {
302302
};
303303

304304
//EntityDefinitions cannot be updated using "PATCH" method
305-
var method = request.collection.indexOf('EntityDefinitions') > -1 ? 'PUT' : 'PATCH';
305+
var method = request.collection.indexOf('EntityDefinitions') > -1 ||
306+
request.collection.indexOf('RelationshipDefinitions') > -1
307+
? 'PUT' : 'PATCH';
306308

307309
_makeRequest(method, request, 'update', onSuccess, onError);
308310
}
@@ -1332,6 +1334,116 @@ function DynamicsWebApi(config) {
13321334
this.retrieveRequest(request, successCallback, errorCallback);
13331335
};
13341336

1337+
/**
1338+
* Sends an asynchronous request to create a relationship definition.
1339+
*
1340+
* @param {string} relationshipDefinition - Relationship Definition.
1341+
* @param {Function} successCallback - The function that will be passed through and be called by a successful response.
1342+
* @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
1343+
* @returns {Promise}
1344+
*/
1345+
this.createRelationship = function (relationshipDefinition, successCallback, errorCallback) {
1346+
1347+
ErrorHelper.parameterCheck(relationshipDefinition, 'DynamicsWebApi.createRelationship', 'relationshipDefinition');
1348+
1349+
var request = {
1350+
collection: 'RelationshipDefinitions',
1351+
entity: relationshipDefinition
1352+
};
1353+
1354+
this.createRequest(request, successCallback, errorCallback);
1355+
};
1356+
1357+
/**
1358+
* Sends an asynchronous request to update a relationship definition.
1359+
*
1360+
* @param {string} relationshipDefinition - Relationship Definition.
1361+
* @param {Function} successCallback - The function that will be passed through and be called by a successful response.
1362+
* @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
1363+
* @param {boolean} [mergeLabels] - Sets MSCRM.MergeLabels header that controls whether to overwrite the existing labels or merge your new label with any existing language labels. Default value is false.
1364+
* @returns {Promise}
1365+
*/
1366+
this.updateRelationship = function (relationshipDefinition, successCallback, errorCallback, relationshipType, mergeLabels) {
1367+
1368+
ErrorHelper.parameterCheck(relationshipDefinition, 'DynamicsWebApi.updateRelationship', 'relationshipDefinition');
1369+
ErrorHelper.guidParameterCheck(relationshipDefinition.MetadataId, 'DynamicsWebApi.updateRelationship', 'relationshipDefinition.MetadataId');
1370+
1371+
var request = {
1372+
collection: 'RelationshipDefinitions',
1373+
mergeLabels: mergeLabels,
1374+
key: relationshipDefinition.MetadataId,
1375+
entity: relationshipDefinition,
1376+
navigationProperty: relationshipType
1377+
};
1378+
1379+
this.updateRequest(request, successCallback, errorCallback);
1380+
};
1381+
1382+
/**
1383+
* Sends an asynchronous request to delete a relationship definition.
1384+
*
1385+
* @param {string} metadataId - A String representing the GUID value.
1386+
* @param {Function} successCallback - The function that will be passed through and be called by a successful response.
1387+
* @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
1388+
* @returns {Promise}
1389+
*/
1390+
this.deleteRelationship = function (metadataId, successCallback, errorCallback) {
1391+
ErrorHelper.keyParameterCheck(metadataId, 'DynamicsWebApi.deleteRelationship', 'metadataId');
1392+
1393+
var request = {
1394+
collection: 'RelationshipDefinitions',
1395+
key: metadataId
1396+
};
1397+
1398+
this.deleteRequest(request, successCallback, errorCallback);
1399+
};
1400+
1401+
/**
1402+
* Sends an asynchronous request to retrieve relationship definitions.
1403+
*
1404+
* @param {Function} successCallback - The function that will be passed through and be called by a successful response.
1405+
* @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
1406+
* @param {string} [relationshipType] - Use this parameter to cast a Relationship to a specific type: 1:M or M:M.
1407+
* @param {Array} [select] - Use the $select system query option to limit the properties returned.
1408+
* @param {string} [filter] - Use the $filter system query option to set criteria for which relationships will be returned.
1409+
* @returns {Promise}
1410+
*/
1411+
this.retrieveRelationships = function (successCallback, errorCallback, relationshipType, select, filter) {
1412+
1413+
var request = {
1414+
collection: 'RelationshipDefinitions',
1415+
navigationProperty: relationshipType,
1416+
select: select,
1417+
filter: filter
1418+
};
1419+
1420+
this.retrieveMultipleRequest(request, successCallback, errorCallback);
1421+
};
1422+
1423+
/**
1424+
* Sends an asynchronous request to retrieve a specific relationship definition.
1425+
*
1426+
* @param {string} metadataId - String representing the Metadata Id GUID.
1427+
* @param {Function} successCallback - The function that will be passed through and be called by a successful response.
1428+
* @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
1429+
* @param {string} [relationshipType] - Use this parameter to cast a Relationship to a specific type: 1:M or M:M.
1430+
* @param {Array} [select] - Use the $select system query option to limit the properties returned.
1431+
* @returns {Promise}
1432+
*/
1433+
this.retrieveRelationship = function (metadataId, successCallback, errorCallback, relationshipType, select) {
1434+
1435+
ErrorHelper.keyParameterCheck(metadataId, 'DynamicsWebApi.retrieveRelationship', 'metadataId');
1436+
1437+
var request = {
1438+
collection: 'RelationshipDefinitions',
1439+
navigationProperty: relationshipType,
1440+
key: metadataId,
1441+
select: select
1442+
};
1443+
1444+
this.retrieveRequest(request, successCallback, errorCallback);
1445+
};
1446+
13351447
/**
13361448
* Creates a new instance of DynamicsWebApi
13371449
*

0 commit comments

Comments
 (0)