Customizing the Dynamics 365 CRM Service
The following section provides detailed instructions on how to upload customization files for Dynamics 365 CRM.
Prerequisites
• Ensure that you have ThingWorx Flow tools installed on your system.
The ThingWorx Flow tools are installed automatically with your installation. For more information about the ThingWorx Flow tools, see Deploying Connectors.
• You need the ThingWorx Administrator login to be able to complete this action.
Steps
You can customize the Dynamics 365 CRM service in one of the following ways:
• Updating OData Metadata—The Dynamics 365 CRM service includes version 9.0 of the OData Metadata. You may need to work on a different version or could have added customizations to your version. In this case, you need to update the Dynamics 365 CRM metadata file. You can download the packaged version of the Dynamics 365 CRM metadata file for reference, and upload your version or an updated version to your ThingWorx Flow instance.
• ThingWorx Flow OOTB supports only a few entities from the Dynamics 365 CRM model. The OOTB settings.json only includes these supported entities. However, the OData Metadata packaged has all entities, associations and anything else that Microsoft supports. You may want to test Dynamics 365 CRM for additional entities and include them in the list of entities, properties and related items by updating the settings.json file. Then, upload it to your ThingWorx Flow instance. Be careful when editing this file as any syntactical mistake may render Dynamics 365 CRM in ThingWorx Flow unusable. For understanding how to update this file, download the packaged file and compare it with the OData Metadata file that is being used.
The following table provides information about the attributes that you can update in the Dynamics 365 CRM settings.json file to customize Dynamics 365 CRM:
|
Attribute
|
Description
|
||
|---|---|---|---|
|
DynamicsApiVersion
|
Specifies the Dynamics 365 CRM API version. By default, it is set to 9.0.
|
||
|
EntitySetDefinitions
propertyDefinitions
|
Defines the Dynamics 365 CRM entity sets that you want to display on the ThingWorx Flow UI.
For example: To include the accounts entity set on the UI, under the EntitySetDefinitions attribute, specify the following:
"name": "accounts",
"include": true, "label": "Account", where name specifies the Dynamics 365 CRM entity set name.
Set include to true to display the entity set on the UI.
The label attribute defines the entity set name that you want to display on the UI.
Every entity set has properties. Define the properties from an entity set that you want to display on the UI under the propertyDefinitions attribute. You can limit the number of properties from any entity set that you want to display on the UI by providing arrays of the name and label of the property.
For example: To display the accountid property, under the propertyDefinitions attribute of the accounts EntitySetDefinitions attribute, specify the following:
{
"name": "accountid", "label": "Account ID" } where name specifies the property name.
The label attribute defines the property name that you want to display on the UI.
If you want to include all properties of an entity set, then set the value of propertyDefinitions as an empty array, that is, "propertyDefinitions": [].
|
||
|
relatedItems
|
If you add a related item, then the entity set data that is returned includes the related items for that particular entity set.
For example: To display the attachments property, under the relatedItems attribute of the accounts EntitySetDefinitions attribute, specify the following:
{
"name": "attachments", "label": "Attachments" } where name specifies the related item name.
The label attribute defines the related item name that you want to display on the UI.
If you do not want to include any related items of an entity set, then set the value of relatedItems as an empty array, that is, relatedItems: [].
|
Uploading the OData metadata file
1. Download your version of the metadata file by accessing it from your Dynamics 365 CRM instance. For example: https://host.dynamics.com/api/data/v9.0/$metadata. Note that the version number must match your instance version.
Alternately, you can download the version packaged with ThingWorx Flow by running the following command:
flow-deploy settings file-download -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -f <Path_to_Metadata_XML_File> -s default -c dynamics365 --fileId DynamicsMetadata --contentType application/xml
 |
The value of the fileId parameter must be set to DynamicsMetadata.
|
2. Open the XML file and ensure that your required customization, if applicable, is present in the downloaded XML file. Edit the file to add your customization, if required.
3. Run the following command to upload the custom OData Metadata file to your ThingWorx Flow instance:
flow-deploy settings file-upload -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -f <Path_to_Metadata_XML_File> -s default -c dynamics365 --fileId DynamicsMetadata --contentType application/xml
|
|
The value of the fileId parameter must be set to DynamicsMetadata.
|
Uploading the settings.json file
1. Run the following command to download the settings.json file that is packaged with ThingWorx Flow:
flow-deploy settings download -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -f <Path_to_Dynamics365_Settings_File> -s default -c dynamics365
2. Edit the settings.json file and ensure that it is compatible with the OData Metadata file that you plan to use.
Ensure that the DynamicsApiVersion value in the settings.json file matches the version in the OData Metadata file that you uploaded earlier.
3. Run the following command to upload the Dynamics 365 CRM settings.json file:
flow-deploy settings upload -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -f <Path_to_Dynamics365_Settings_File> -s default -c dynamics365
After all uploads are successful, restart all ThingWorx Flow services. Your customization is now visible for all Dynamics 365 CRM actions.