HomeGuidesRecipesAPI
HomeGuidesAPILog In

Microsoft Dynamics 365

The MS Dynamics 365 Connector has been developed to provide an integrated experience for customers by integrating SmartIQ with MS Dynamics 365. The SmartIQ Connectors for Dynamics 365 include several integration components which support Data Connections. This enables pulling data from Dynamics to consume in SmartIQ forms and Actions which provide the functionality to push data from SmartIQ forms to MS Dynamics 365.

❗️

Licence key required

To enable the MS Dynamics 365 module, you will require a license. If you don't have one, please contact SmartIQ Support.

Components

Actions

Data Connections

  • Dynamics 365

👍

Understanding the Dynamics Data model

A useful resource for information about your MS Dynamics 365 environment can be found in the Customizations area of Dynamics, accessed from Settings > Customizations > Customize the System. This displays all components in your MS Dynamics 365 environment, including Entities, Relationships, Fields and Option Sets that can be extremely useful in configuring both the Data Source and Actions for MS Dynamics 365 within the SmartIQ system.

Configuring the Connector Settings

The Connector exposes a number of settings which provide tenant-wide values to control behavior or context. In many cases, these settings can be overridden when the action is used in a project.

Viewing or Changing Connector Settings

  1. In a web browser, navigate to the SmartIQ Manage application and log in.

  2. Navigate to Settings > Dynamics 365 Connector.

  3. Review and update the settings as described in the action attributes for the selected action.

  4. Click the Save button at the top of the page.

Setting

Description

Dynamics Connection String

URL to the Dynamics followed by authentication type.
For example:
Url=https://o365account.crm6.dynamics.com;authtype=OAuth

See Dynamics Connection String section for more details.

Force Impersonate [true|false]

By default, this option is set to false. If you set this option to true, then a username can be passed in the connector actions with which a new record would be created or an existing record would be updated in Dynamics.

Suppress duplicate detection [true|false]

By default, this option is set to false. If this is set to false then duplicate detection will be activated during Dynamics Create Entity action.

Update duplicate on create [true|false]

By default, this option is set to false. If this option is set to true then SmartIQ will look for any record in Dynamics with the same values that are being passed in Dynamics Create Entity action. If such a record exists, the existing record would be updated instead of creating a new record in Dynamics.

Transaction Mode [true|false]

By default, this option is set to false. If this option is set to true, submit the action as part of a batched transaction along with other Dynamics actions for the same submission. If false, the action runs individually.

Debug Mode [true|false]

By default, this option is set to false. If the debug mode is set to true, the detailed logs will be shown in the Management tab in Manage.

📘

Note

Connector Settings are applied tenant-wide. For specific scenarios where it is required to use different credentials, please specify them in Dynamics action in Design or directly in the Data Connection configuration.

Dynamics Connection String

SmartIQ enables you to connect to your MS Dynamics 365 instance by using connection strings. This is similar to the concept of connection strings used with Microsoft SQL Server. You supply this connection string in the Connection String section when you set up your Dynamics 365 Data Connection, as shown in the following example.

Example of the Connection String attribute configured in the data connection where the username and password is set in the credentials section.

AuthType=OAuth; Url=https://{users_dynamics_url}/; AppId={appId}; RedirectUri=app://{appId}; LoginPrompt=Never

Connection String can also be supplied at Action level. All the MS Dynamics 365 Actions have an attribute CRM Connection String. If you provide the value of your connection string in the action for this attribute, the action will use the connection string configured in the actions or it will use the connection string configured above in the Manage > Settings tab.

Connection String Parameters

Parameter Name

Description

Url
(mandatory)

Specifies the URL to the MS Dynamics 365 Server. The URL can use http or https protocol, and the port is optional.

AuthType
(mandatory)

Specifies the authentication type to connect to Dynamics 365 instance. Recommended value is OAuth.

Note: There have been changes to the Microsoft Dynamics online service as well as which methods are supported. Refer to OAuth and Dynamics for more information.

UserName
(mandatory)

Specifies the user's identification name associated with the credentials.

Password
(mandatory)

Specifies the password for the user name associated with the credentials.

Domain

Specifies the domain that will verify user credentials.

RequireNewInstance

The default value of this parameter is set to false. If you have multiple connections to multiple MS Dynamics 365 instances, set this to true to force the system to create a unique connection instance.

👍

Best Practice

You can specify the username and password in the Connection String but it is best practice to specify the username and password in the credentials section so that no one can access them. This will provide additional security as the password is masked.

Dynamics Data Connection

The MS Dynamics 365 Data Source for SmartIQ is used to read data from the MS Dynamics365 environment. This is useful for bringing back entity records, such as contacts, to populate drop-down lists in an SmartIQ web form, or to populate a web form with the specific entity information from MS Dynamics 365. It can also be used to make decisions dynamically based on data in MS Dynamics 365. For example, based on the contact type in MS Dynamics365, you may wish to ask additional questions in the web form.

The data source can also be used to automatically fill entity data in generated document outputs from SmartIQ such as Word or PDF documents, emails and other communications. You can easily read data from multiple related entity records and can add as many data questions to a SmartIQ project as needed. You can also read data from custom entity types you may have added to your MS Dynamics 365 environment. The MS Dynamics 365 Data Source also allows you to read data from Option Sets in your MS Dynamics 365 environment. This is often useful for automatically populating drop-down lists in the SmartIQ form for user selection.

Configuring Dynamics Data Connections

  1. In a web browser, go to Manage > Data Connections.

  2. Click the New Data Connection button, and complete the connection information.

Attribute

Description

Data Connection Name

Type a name for the data source.

Connection Type

Select Dynamics 365 from the drop-down list.

  1. Click Save to save the details provided and Test Connection to confirm it can connect successfully to your MS Dynamics 365 environment.

  2. Click Data Objects to add a new data object.

  3. Enter the entity name in the Data Object Name/Definition field. The matching entities will get populated in a drop-down list and select a particular entity.

  4. Enter a name in the Display Name field for this data object.

  5. Select the required Available Fields and click Add. The Dynamics data source can now be used in the project by adding a Data Source - Question Type to the page as a data source.

👍

Best Practice

To enhance performance, it is best practice to specify the fields of an entity which are to be pulled from Dynamics.

For example, you can specify the contact [contactid|firstname|lastname|telephone1|emailaddress1|address1_line1|address1_line2|address1_line3] in the Data Object Name / Definition and this data source will only pull the data from specified fields from Dynamics.

Configuring Custom Display Fields for Dynamics Data Connections

A custom display field for Dynamics Data Connections can be defined in the Data Object Definition using the following syntax:entityname [fieldname|ConcatField:static text {fieldname} {fieldname}]

Example 1: Suppose we want to create a custom display field of Contact entity called FullNameFormatted, which is a combination of firstname and lastname under this format: firstname, lastname. Along with FullNameFormatted, we also want to display contactid in our Data Connection.

The Data Object Definition should look like this:

contact [contactid|FullNameFormatted:{lastname}, {firstname}]

Notice in the result we now have contactid, firstname, lastname and FullNameFormatted displayed:

Example 2: Suppose we want to create a custom display field of Account entity called AccountNameFormatted, which is a concatenation of name value and the word "Account". Along with AccountNameFormatted, we also want to display accountid in our Data Source.

The Data Object Definition should look like this:

account [accountid|AccountNameFormatted:{name} Account]

Notice in the result we now have accountid, AccountNameFormatted, and namedisplayed:

MS Dynamics 365 Actions

While the action providers are included, they will not be called until a project is set up in SmartIQ with one or more of the MS Dynamics 365 actions, with action attributes that instruct the action providers on how to behave. These action attributes can be set up with fixed values within Design, or they can be set up to refer to values collected via the question set during the generation process.

Adding a MS Dynamics 365 Action

  1. Open an existing project in Design.

  2. Drag a new action onto the Finish Page. The action can be either ‘Dynamics Create Connection’, ‘Dynamics Create Email Activity’, ‘Dynamics Create Entity’, ‘Dynamics Create Relationship’, ‘Dynamics Execute Transaction’, or 'Dynamics Update Entity'.

  3. Set the action attributes as described in the below action section, depending on the specific action selected.

  4. Save your project, and test in Produce.

👍

Best Practice

While the name of the action defaults to the action name, i.e. ‘Dynamics Create Entity’ for Create Entity action, the name should be modified as per the functionality of that particular action. For example, in the below screenshot, the 'Create Entity' action is renamed to 'Create Application Contact'.

Dynamics Create Entity Action

SmartIQ Actions are executed when a SmartIQ form is submitted, either when transitioning from one workflow step to the next, or submission of a completed form.

The Dynamics Create Entity action is used to create a new record of data in MS Dynamics 365 based on data submitted by the user.

For example, after collecting the user’s information, you may add them to MS Dynamics 365 using the contact entity type. This will create a record in contact entity with the provided data. You can also add multiple Create Entity actions in your project to create multiple records in the different entities in Dynamics.

In Design, once you’ve added the Dynamics Create Entity action to your project, either on the Finish page or a workflow transition, use the Dynamics Create Entity Action Attributes table to configure any action attributes that you require.

Dynamics Create Entity Action Attributes

Name

Description

Annotation properties [1 per line]

Attachment metadata for documents.

Attach Documents [true|false]

Set to ‘true’ if you wish to attach documents to the entity, usually within an annotation. If you leave this attribute out, the default is ‘false’.

Note that only the documents passed to the action are used for attachments. This can be configured on the Documents tab when the action is selected.

Attachment Relationship Name

Specify the name of the relationship to create an annotation for the chosen entity. This is typically in the form of entitytype_Annotation.

For example, for accounts, this would be ‘Account_Annotation’. To find the relationship name in the customization area of Dynamics, look in the 1:N Relationships node under the required entity node.

Entity Properties [1 per line]
(Mandatory)

Add each field you wish to set in the new entity record on a separate line within this attribute value, in the form of field name=value. Note that you may include question references or fixed values after the equals (=) sign.

If the attribute value is of type MultiSelect Option Set, enclose the list of integer values in square brackets eg: fieldname=[1,2,3,5.9]

Most attribute values cannot be set to an empty value. Any attempt to set a value to a blank value such as fieldname= will be ignored by the connector.
To set entity properties of type string to an empty string value, you must use the special value {null} eg: fieldname={null}

Entity
(Mandatory)

Enter the type of entity where the record is to be created, e.g. ‘contact’.

CRM Connection String

If the connection string is not provided in the action, SmartIQ will use the connection string configured in Settings > Dynamics 365 Connector for this connector.

You can also use the data connection name within the curly braces as the connection string value. In this case, when the action is executed the data connection name will be replaced by the actual connection string configured for this data connection in Manage during runtime.

For example, we have configured the data connection 'DynamicsConnector' so we can use the {DynamicsConnector} as the value for this attribute.

Impersonate Username

The username which will be used to create a record in the Dynamics entity.

Dynamics should support impersonation in order to use this functionality.

Suppress duplicate detection [True|False]

If this parameter is not passed in the action, then the value configured for this attribute in Settings > Dynamics 365 Connector will be used.

By default, this option is set to false. If this is set to false. the duplicate detection will be activated during the Create Entity action.

Transaction Mode

If true, submit the action as part of a batched transaction along with other Dynamics actions for the same submission. If false, the action runs individually.

Update duplicate on create [True|False]

If this parameter is not passed in the action, then the value configured for this attribute in Settings > Dynamics 365 Connector will be used.

By default, this option is set to false. If this option is set to true then SmartIQ will look for any record in Dynamics with the same values that are being passed in the Create Entity action. If such record exists, the existing record would be updated instead of creating a new record in Dynamics.

This screenshot shows the action where only three action attributes (Entity, CRM Connection String, and Entity Properties [1 per line] are configured.This screenshot shows the action where only three action attributes (Entity, CRM Connection String, and Entity Properties [1 per line] are configured.

This screenshot shows the action where only three action attributes (Entity, CRM Connection String, and Entity Properties [1 per line] are configured.

Action Outputs

Dynamics Create Entity Action has the following outputs:

  • Entity Id - This is the GUID of the newly created record in the specified entity.
    You can reference this returned Entity Id in the subsequent actions. For example, you can use this ID in the Display Message action to inform the user that a record with the returned GUID is created in Dynamics.
  • Is Duplicate - Returns a true or false if it is a duplicate.

To reference the ID in the action attribute of the subsequent action, use the reference notation of [action name.Entity Id]. For example, in the screenshot below, we are referencing the output Entity ID of Create Application Contact in the Display Message Action.

Dynamics Update Entity Action

Similar to the Create Entity Action, the Update Entity Action is run when an SmartIQ form is submitted, either during workflow transitions or at the end of the completed form, and updates an existing MS Dynamics 365 entity record. This can be used in conjunction with the other Actions for more complex interactions with MS Dynamics 365.

For example, you may wish to update a contact entity record prior to relating that contact as a primary contact on a new entity record.

In Design, once you’ve added the Dynamics Update Entity action to your project, either on the Finish page or a workflow transition, use the Dynamics Update Entity Action Attributes table to configure any action attributes that you require.

Dynamics Update Entity Action Attributes

Name

Description

Attach Documents [true|false]

Set to ‘true’ if you wish to attach documents to the entity, usually within an annotation. If you leave this attribute out, the default is ‘false’.

Note that only the documents passed to the action are used for attachments. This can be configured on the Documents tab when the action is selected.

Attachment Relationship Name

Specify the name of the relationship to create an annotation for the chosen entity. This is typically in the form of entitytype_Annotation.

Entity ID
(Mandatory)

Enter the unique ID of the entity record to be updated. For example, for accounts, this would be the ‘accountid’ field.

Refer to Action Outputs for information about referencing the entity ID created by the Create Entity Action.

Entity Properties [1 per line]
(Mandatory)

Add each field you wish to update in the entity record on a separate line within this attribute value, in the form of field name=value. Note that you may include question references or fixed values after the equals (=) sign.

If the attribute value is of type MultiSelect Option Set enclose the list of integer values in square brackets eg: fieldname=[1,2,3,5.9]

Most attribute values cannot be set to an empty value. Any attempt to set a value to a blank value such as fieldname= will be ignored by the connector.
To set entity properties of type string to an empty string value you must use the special value {null} eg: fieldname={null}

Entity
(Mandatory)

Enter the type of entity to be updated, e.g. ‘account’.

CRM Connection String

If the connection string is not provided in the action, SmartIQ will use the connection string configured in Settings > Dynamics 365 Connector for this connector.

You can also use the data connection name within the curly braces as the connection string value. In this case, when the action is executed the data connection name will be replaced by the actual connection string configured for this data connection in Manage during runtime.

For example, we have configured the data connection 'DynamicsConnector' so we can use the {DynamicsConnector} as the value for this attribute.

Attachment properties [1 per line]

Attachment metadata for documents.

Impersonate Username

The username which will be used to create a record in the Dynamics entity.

Dynamics should support impersonation in order to use this functionality.

Transaction Mode

If true, submit the action as part of a batched transaction along with other Dynamics actions for the same submission. If false, the action runs individually.

In this example, we are updating a record in the entity 'contact'. The ID of the record that is to be updated is retrieved from the data source 'Contact Entity' in the 'contactid' answer field. The answer field is referenced in the Entity ID attribute of the Update Entity action.

📘

Action Output

This action has no output.

Dynamics Create Relationship Action

The Create Relationship action is used to relate two entities in MS Dynamics 365 and can be used in conjunction with the Create Entity action to create a relationship with a newly created entity.

For example, your form may collect information to create a new contact entity and you may wish to add the contact to an existing account entity. Just remember that any actions you add to the SmartIQ project run in the order placed, so when creating relationships and new entities, you must always create the new entities first.

In Design, once you’ve added the Create Relationship action to your project, use the Dynamics Create Relationship Action Attributes table either on the Finish page or a workflow transition to configure any action attributes that you require.

Dynamics Create Relationship Action Attributes

Name

Description

Child Entity Id

Enter the unique ID of the entity record to be the child in this relationship. For example, for accounts this would be the ‘accountid’ field.

Refer to Action Outputs for information about referencing the entity ID created by the Create Entity Action.

Child Entity Type

Enter the type of entity to be the parent record in the relationship, e.g. ‘account’.

Parent Entity Id

Enter the unique ID of the entity record to be the parent in this relationship. For example, for contacts this would be the ‘contactid’ field.

Refer to Action Outputs for information about referencing the entity ID created by the Create Entity Action.

Parent Entity Type

Enter the type of entity to be the parent record.

Relationship Type Name

Specify the name of the relationship type used to relate the child entity to the parent entity.

To find the relationship name in the customization area of Dynamics, look under the required entity at one of the following sub-nodes:

  • 1:N Relationships
  • N:1 Relationships
  • N:N Relationships

CRM Connection String

If the connection string is not provided in the action, SmartIQ will use the connection string configured in Settings > Dynamics 365 Connector for this connector.

You can also use the data connection name within the curly braces as the connection string value. In this case, when the action is executed the data connection name will be replaced by the actual connection string configured for this data connection in Manage during runtime.

For example, we have configured the data connection 'DynamicsConnector' so we can use the {DynamicsConnector} as the value for this attribute.

📘

Action Output

This action has no output.

Dynamics Create Connection Action

The Create Connection action can be used to create an association between two records present in MS Dynamics 365 entities. You have to specify the entities name and GUID of the records which are to be associated.

In Design, once you’ve added the Create Connection action to your project, either on the Finish page or a workflow transition, use the Dynamics Create Connection Action Attributes table to configure any action attributes that you require.

Dynamics Create Connection Action Attributes

Name

Description

Entity1Name

Enter the name of the first entity, e.g. Contact

Entity2Name

Enter the name of the second entity.

Entity1Id

Enter the unique ID of the entity record of the first entity.

Entity2Id

Enter the unique ID of the second entity.

Entity1RoleId

Enter the unique ID of the connection role for the first entity.

Entity2RoleId

Enter the unique ID of the connection role for the second entity.

CRM Connection String

If the connection string is not provided in the action, SmartIQ will use the connection string configured in Settings > Dynamics 365 Connector for this connector.

You can also use the data connection name within the curly braces as the connection string value. In this case, when the action is executed the data connection name will be replaced by the actual connection string configured for this data connection in Manage during runtime.

For example, we have configured the data connection 'DynamicsConnector' so we can use the {DynamicsConnector} as the value for this attribute.

📘

Action Output

This action has no output.

Dynamics Create Email Activity Action

The Dynamics Create Email Activity Action is used to create the email activity against a record in MS Dynamics 365 and include SmartIQ generated documents as attachments.

In Design, once you’ve added the Dynamics Create Email Activity action to your project, either on the Finish page or a workflow transition, use the Dynamics Create Email Activity Action Attributes table to configure any action attributes that you require.

Dynamics Create Email Activity Action Attributes

Name

Description

Related to Entity Id

Enter the unique ID of the entity record the email activity should be created against.

For example, for accounts, this would be the ‘accountid’ field.

Refer to Action Outputs for information about referencing the entity ID created by the Dynamics Create Entity Action.

Related to Entity Name

Enter the type of entity the email activity should be created against, e.g. ‘account’.

Entity State Code [statecode property]

Enter the State Code of the generated Email activity.

Entity Status Code [statuscode property]

Enter the Status Code of the generated Email activity.

From - one id or email address per line

Emails will appear to have originated from this address.

To - one id or email address per line

Emails will be sent to this email address.

Subject

This will be the subject of the email.

CC - one id or email address per line

Emails can be carbon copied to this email address.

BCC - one id or email address per line

Emails can be blind carbon copied to this email address.

Body

This will populate the body of the email.

Direction of Email [inward|outward]

Select the direction of the email as incoming or outbound.

Include Attachments [true|false]

By default, this option is set to false. If this is set to true then SmartIQ generated documents will be sent as attachments.

CRM Connection String

If the connection string is not provided in the action, SmartIQ will use the connection string configured in Settings > Dynamics 365 Connector for this connector.

You can also use the data connection name within the curly braces as the connection string value. In this case, when the action is executed the data connection name will be replaced by the actual connection string configured for this data connection in Manage during runtime.

For example, we have configured the data connection 'DynamicsConnector' so we can use the {DynamicsConnector} as the value for this attribute.

New email entities will be created in Dynamics in a Draft state. To send the email, configure Dynamics as follows:

  1. Create a boolean field with a suitable name like "Email Trigger Send".

  2. Create a workflow which is triggered by the update of the "Email Trigger Send" field to change the status of the email activity to "Pending Send" and the number of send attempts to 0 (which will trigger Dynamics to do the send).

  3. In SmartIQ, after the Create Email Activity action, add an Update Entity Action to change the "Email Trigger Send" to yes/true.

Action Output

Dynamics Create Email Activity Action has one output, Entity Id, which is the GUID of the newly created email activity.

Dynamics Execute Transaction Action

The Execute Transaction action is used in conjunction with the Transaction Mode input on the other Dynamics actions. When the other actions have that flag set, instead of sending to Dynamics directly their actions are instead cached in memory by JobGuid. The Execute Transaction action then sends the cached actions for processing by Dynamics.

📘

Action Outputs

This action has no output.

Troubleshooting

MS Dynamics 365 connections can fail due to a number of reasons. Some of the common issues for failure include:

  • Invalid connection strings.
  • Data integrity issues in passed data in actions. For example, not passing mandatory fields when creating an entity.
  • Network issues between SmartIQ server and the Dynamics instance.

👍

Best Practice

Whenever you are debugging, make sure that you have set the Debug Mode [true|false] to true in the connector settings in Manage. This will result in detailed logging of the action execution.

The first place to investigate is the Management tab of SmartIQ Manage if you encounter issues when using the Dynamics connector. You will see the record for your execution.

For example, in the below screenshot you can see a project 'Testing Dynamics Connection' is executed by user 'admin' and the status is 'Completed'.

To see the logs for this execution, click View, where you will see the logs for this execution as shown in the below screenshot. You will see the Level as 'Warning' for error. Read the Description to know the reason for this error.