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.

📘

Deployment Feature Availability

This feature is not available in CoLo deployment.

❗️

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

• Dynamics Create Entity Action
• Dynamics Update Entity Action
• Dynamics Create Relationship Action
• Dynamics Create Connection Action
• Dynamics Create Email Activity Action
• Dynamics Execute Transaction Action

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.

📘

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

👍

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.

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

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

5. 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.

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

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

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

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

📘

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

📘

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

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.