Documentation forTask Factory

Task Factory Dynamics

 Task Factory users running version 2020.1.4 or older (released prior to May 27, 2020): There's an important Task Factory update. Please visit here for more details.

Dynamics CRM Connection Manager

Connection Settings

Task Factory Dynamics CRM Connection Manager

Option Description
Version

There are five versions of Dynamics CRM that can be utilized with the Dynamics CRM Connection Manager:

  • CRM 4.0
  • CRM 2011
  • CRM 2013
  • CRM 2015
  • CRM 2016
Server Type Based on the version selected, the server type changes to reflect the available server types supported.

Available CRM 4.0 Server Types :

  • Premise - This is a Dynamics server that is on site.
  • Live - An online account with Dynamics Live. When using this server type you should leave the default URL of crm.dynamics.com or CRM4.dynamics.com.
  • Hosted - A Server instance hosted off site with a third party.
Available CRM 2011 and 2013 - 2016 Server Types:

  • Premise - This is a Dynamics server that is on site.
  • Live - An online account with Dynamics Live. When using this server type you should leave the default URL of crm.dynamics.com or CRM4.dynamics.com.
  • Hosted - A Server instance hosted off site with a third party.
  • Office 365  - An online account with Dynamics Office 365. When using this server the URL should be left as disco.crm.dynamics.com.
Server URL URL or IP address used to connect to the Dynamics CRM server.
User Name Account used to sign into Dynamics.
Password Password for Dynamics account.
Organization The organization is a required field that must match the name of the organization setup in the dynamics crm server. If you do not know the name of the organization, you can select the Get Organizations to get a list of organizations from the server.
Organization URL The url for the selected organization.
Timeout The number of seconds before the connection manager times out trying to connect to the Dynamics CRM instance.
Test Connection Select the Test Connection button to verify your connection credentials.

Proxy Settings

Task Factory Dynamics CRM Connection Manager Proxy Settings

Option Description
Host Enter the Host's ip address.
Port Enter the Host's port.
User name Enter the Host's username.
Password Enter the Host's password.

Dynamics OAuth2 Connection Manager

Connection Settings

Task Factory Dynamics OAuth2 Connection Manager Connection Settings

Option Description
Client id The Client id for your Dynamics OAuth2 connection.
Client Secret The Client secret for your Dynamics OAuth2 connection.
Access Token Select Get Token to open the Token Getter window.
Is Bearer Token Select this option if the Access Token is a bearer token.
Access Token Expiration Date The expiration date of the access token.

Note:  This setting is optional.
Security Protocol The Security Protocol used by the API. The Default option uses the TLS version used by your .NET version by default. See the following chart for more information:

.NET VersionTLS Support Information
.NET 4.6 and aboveSupports TLS 1.2 by default.
 .NET 4.5

TLS 1.2 is supported, but you need to opt-in to use it. Execute the following code before making a connection to a secured resource to make TLS 1.2 the default :

  • ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
.NET 4.0TLS 1.2 is not supported. If you have .NET 4.5 (or above) installed on the system, you can opt in for TLS 1.2 even if your application framework doesn’t support it. SecurityProtocolType in .NET 4.0 doesn’t have an entry for TLS1.2, so you need to use a numerical representation of this enum value:
  • ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072;
.NET 3.5 or belowTLS 1.2 is not supported, and there is no workaround. Upgrade your application to a more recent version of the framework.
Web Api Url
The URL for the Web API connection.

Token Getter

Task Factory OAuth2 Token Getter

Option Description
Client Id This field should be auto-completed from the previous window with your Client Id.
Client Secret This field should be auto-completed from the previous window with your Client Secret.
Directory (tenant) ID The Directory (tenant) ID of the Azure app.
WebInstance Your web instance from the Web API found in Developer Resources in Power Apps Admin. 
ResourceUri Select this option to enable the resource uri option.
OfflineAccess Select this option to enable the offline access option
Port for response The port on your local machine where you want to send the token request response.
Set your Redirect Uri to: Use this as your Redirect Uri in your OAuth2 App settings.
Get Access Token Opens a browser window to login to your Microsoft account and grant access.

Headers

Task Factory Dynamics OAuth2 Connection Manager Headers

You can create header names and values by entering the information in their corresponding windows.

Refresh Token

Task Factory Dynamics OAuth2 Connection Manager Refresh Token

Option Description
Refresh Token Authentication information provided to you at the application's developer site.

Note:  This should match the API Key from the Connection Settings window.
Token Request Url The URL that returns a refresh token. Example: https://api.citrixonline.com/oauth/access_token
Headers Allows you to add headers within the refresh token. Select Add New Header to add a header. Select Remove header to remove a header.
Results Returned In Specifies how results are returned from the application (JSON, XML, or String.)
Access Token Path The token path for the access token. Example: access_token
Refresh Token Path The token path for the refresh token. Example: refresh_token
Group Index Identifies the index position to return (0 based).

Note:  This option is available when you select String for the Results Returned In option.
Use Token Store This option creates a file on your machine that saves the access token, and refresh token in an encrypted format.
Token Store Id Identifies the Token Store Id.
Token Store Path (Optional) Identifies the Token Store path.
Test Get Refresh Token Select this option to test the retrieval of the Refresh Token. 

Client Certificate

Task Factory Dynamics OAuth2 Connection Manager Client Certificate

Option Description
Use Client Certificate Select this option if you want to use the client certificate.
Certificate Store Location The client store location. 
Search For Certificate Enter a certificate that you want to search for and then select Find.

Note:  Leave this section blank and select Find to view all certificates.
Certificate Thumbprint The identifier thumbprint of the selected certificate.

Proxy

Task Factory Dynamics OAuth2 Connection Manager Proxy

Option Description
Proxy Host When connecting to an endpoint using a proxy, you should enter the proxy URL in this field.
Proxy Port The port number that corresponds to the URL proxy host.
User Name The username needed to authenticate to the proxy.
Password The password that allows you to authenticate to the proxy.

Advanced Options

Task Factory Dynamics OAuth2 Connection Manager Advanced Options

Option Description
Ignore Ssl Certificate Verification Selecting this option ignores the SSL Certificate notification from the API during the connection.

Note:  This option applies to APIs that require you to have an SSL Certificate. Select this option if the SSL Certificate is not needed.
Follow Redirects Selecting this option implements a 301 redirect on configured endpoints. For example, this option would automatically send your request to an HTTPS redirect once the request has reached the HTTP version of the site.  

Dynamics CRM OData Connection Manager

Note:  Azure Storage connection manager is available for SQL versions 2012 and higher. Currently, the OData can only target Dynamics CRM instances that use Office 365.

Connection Settings Tab

Task Factory Dynamics OData Connection Manager Connection Settings

Additional Information: The following configurable items are located within the user's Azure portal.
Note:  A Dynamics app registration needs to be completed to access these items.
Function Description
Application Id  Enter the application Id located in the user's Azure Active Directory > App Registrations >(NameOfApp).
Redirect URI Enter the application's redirect URI configured in the user's Azure Active Directory > App Registrations > (NameOfApp) > Redirect URI's.
Tenant Id Enter the application's tenant Id located at http://login.windows.net/YOUR_DOMAIN/.well-known/openid-configuration.

Alternatively, users can open https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectory
MenuBlade/Properties and navigate to Azure Active Directory > Properties.

Note:  The Directory Id is also the Tenant Id.
Organization name Enter your organization's name located at https://YOUR_ORGANIZATION.crm.dynamics.com.
Username Enter the username for the user logging into the Dynamics CRM instance.
Password Enter the password for the user logging into the Dynamics CRM instance.
 Api Version Enter the Api version.

The default value is v8.2.
Timeout (Seconds) The number of seconds before the connection manager times out trying to connect to the Dynamics CRM instance.

Note:  The default value is zero which is infinite.

Authorize User - Before using the connection manager, users must setup their app in the azure portal. After the connection manager details have been entered, users need to authorize their user account to interact with dynamics by selecting Authorize User. This opens a miniature browser window that automatically navigates to the webpage where the credentials must be entered.

Proxy Tab

Task Factory Dynamics OData Connection Manager Proxy

Note:  Proxy use is enabled when a value is added to any of the Proxy fields.
Function Description
Proxy Host Enter the proxy host's IP address.
Proxy Port Enter the proxy host's port number.
Proxy User Name Enter the proxy host's username credential if required. If it's not required, leave blank.
Proxy Password Enter the proxy host's password if required. If it's not required, leave blank.
Auth Scheme Select the authentication scheme used by the host proxy. Users can select from the following options:

  • Basic
  • Digest
  • Proprietary
  • None
  • Ntlm
  • Negotiate

Troubleshooting Tips

Users who are not authorized encounter the following:
Task Factory Unauthorized user example

Note:  Currently, the ODATA is missing the following functions and actions for some organization service messages: 

  • GrantAccessRequest
  • RemoveMemberListRequest 
  • ModifyAccessRequest 
  • RemoveItemCampaignRequest
  • ReactivateEntityKeyRequest 
  • RemoveItemCampaignActivityRequest 
Additional Information: For more information, see the Microsoft Dynamics 365 Web API Limitations MSDN article.

Dynamics CRM Destination

Note:  Task Factory currently supports the following versions of Dynamics CRM: 4.0, 2011, 2013, 2015, 2016.
Destination Icon Destination Description
Task Factory Dynamics CRM Destination Icon The Dynamics CRM Destination is used for writing data to a table in a Dynamics CRM server. See the Dynamics CRM Connection Manager or Dynamics OData Connection Manager to learn more about setting up the connection managers.

Task Factory Dynamics CRM Destination

Function Description
Connection  Using the drop down menu, create or select a connection manager for the Dynamics CRM server.
Action Choose the desired action :

  • Insert - Insert new rows into the Dynamics Entity.
  • Update - Update rows that already exist in the Dynamics Entity.
  • Delete - Delete existing rows from the Dynamics Entity.
  • Upsert - Upsert is used to insert new rows into the Dynamics Entity, or update rows that already exist.
Detect Duplicate Rows When this option is enabled, the destination checks for duplicate rows based on the data duplication rules on the CRM Server. The rows are handled according to the How to handle errors setting.  
 Dynamics Entity This field displays all of the available tables in the Dynamics server.
Map Dynamics Destination Columns Sets up desired mappings.

Upsert Modes

The Upsert mode of Dynamics has two modes, Primary Key Column Mapped, and Primary Key Column Unmapped.

Primary Key Column Mapped  

If the primary key from entity is mapped to a column from the source, the destination looks for NULL values in the source data. If the source data for the primary key is NULL, then an insert executes. If the primary key is NOT NULL then an update executes. For an Update to work the primary key column value from the source MUST be the primary key value from the Dynamics entity. For instance, the Account entity primary key column is AccountID. This column must be mapped to be in Primary Key Mapped mode.

If Detect Duplicate Rows is checked an insert is attempted. However, if a Duplicate Data rule on the dynamics server detects a duplicate row, the data in the current row that would have been inserted updates instead.

Example

To give you an example of this let's assume your Account entity on Dynamics has a Duplicate Data rule on the Name column. We have an account named Sentry One in the Dynamics Account entity. If a row with the account name of Sentry One from your source is sent to the server as an insert (because the primary key value is null) then the Dynamics Server rejects the insert but the Dynamics Destination component then takes the current row from the source and updates the row in the Dynamics Account entity. If this behavior is NOT DESIRED then Detect Duplicate Rows should be turned off.

If Detect Duplicate Rows is unchecked and duplicate data is detected on the server the row is rejected and an error is thrown.

Primary Key Column Not Mapped

In this mode, the primary key is not mapped and only the Duplicate Data rules on the Dynamic server are used. For each row from the source an insert is attempted on the server.

Due to the Duplicate Data rule, if Detect Duplicate Rows is checked and a duplicate row is detected on the Dynamics server, the detected duplicate row on the dynamics server updates.

Example

To give you an example of this let's assume your Account entity on Dynamics has a Duplicate Data rule on the Name column. We have an account named Sentry One in the Dynamics Account entity. If a row with the account name of Sentry One from your source is sent to the server and a duplicate row is detected on the Dynamics Server the row is rejected as an insert and treated as update.

If Detect Duplicate Rows is unchecked and a duplicate row is detected on the Dynamics server based on the Duplicate Data rule then an error is thrown.

Additional Information:  See the Task Factory Error Row Handling article for more information about this functionality.

Dynamics CRM Source

Source Icon Source Description
Task Factory Dynamics CRM Source Icon The Dynamics CRM Source reads data from the entities in a Microsoft Dynamics Server. See the Dynamics CRM Connection Manager or the Dynamics OData Connection Manager to learn more about setting up the connection manager.

Task Factory currently supports the following versions of Dynamics CRM:

•  4.0 •  2011 •  2013
•  2015 •  2016

Choose Columns Tab

Task Factory Dynamics CRM Source Choose Columns

Function Description
Connection Create or select a connection manage for the Dynamics CRM server.
Query Type Determines where to look for the Dynamics Entity:

  •  Entity - Selects the "standard" entities in Dynamics such as Accounts, Contacts, Opportunities, etc. Views are selected in the Dynamics Entity drop-down.
  • Personal View - Allows users to select custom views. Views are selected in the Dynamics Entity drop-down.
  • System View -  Allows users to select all non-custom views within the Dynamics CRM system.
Dynamics Entity Displays a list of entities form which the source can read.
Batch Size The Batch Size field determines the number of rows that are retrieved during a single round trip to the Dynamics server.

Note:  The default value is 500.
Get Changes Toggle for users to track changes/updates for synchronization. (Filters cannot be used when selecting this option.) For more information, see Change Tracking .

Note:  Get Changes can only be used when the Entity Query Type is selected.
Tracking Token Variable Identifies the variable that stores the (required) change.

Note:  If you're using Dynamics with change tracking, the Tracking Token Variable saves the Tracking token that returns from dynamics. If you don't have change tracking enabled, the subsequent calls to dynamics will return the same rows without the changes.
Choose Columns Once an entity is selected, the available columns display. Columns can be ignored by unchecking the corresponding box in the Include in Output column.

Filters Tab

Task Factory Dynamics CRM Source Filter

Function Description
Filter Filters can be set so that users can customize the data that is returned.
Preview Data Opens a new window that displays the data based on the entity and conditions (if configured.)
Refresh Metadata Updates the component with the most current metadata.

To add a filter, complete the following steps:

  1. Select the add icon (+).
  2. Choose the column to be filtered.
  3. Select the parameter (e.g. Begins with, Greater than, Less than, etc.).
  4. Define the value in the <enter a value> box. (Variable replacements can be used with the following syntax:<@Namespace::MyVariableName> .  For example: <@User::Variable>).
  5. Select the word And if Or filter needs to be added.

Dynamics CRM Source Change Tracking

The Dynamics CRM Source allows organizations to synchronize their data with external data sources. Users can track when a change occurs by selecting the Get Changes toggle. Before using this feature, users must first enable the feature.

To enable the feature, complete the following steps:

  1. Go to the entity to be tracked.
  2. Go to Customizations > Customize the System.
  3. Select an entity, and under Data Services, select the Change Tracking check box.

Task Factory Dynamics CRM Source Change Tracking

Note:  Before using this feature, please note the following:

  • Change Tracking is an entity-level setting that must be enabled before using. This must be enabled for each entity the users wish to track changes.
  • A change token is also required for each individual entity. (For example: the Accounts entity token is different than the Contacts token.)
  • Lookup field properties are not returned.
  • The data is returned in their current status. The pre-change status is not returned.
  • Users accounts must be granted the organization level read privileges for each tracked entity.
Additional Information: For more information on enabling your Dynamics CRM instance, please see the Use change tracking to synchronize data with external systems MSDN article.
Note:  The changetype and entityid columns are added to the end of the output when the Get Changes option is selected.

Task Factory Dynamics CRM Source changetype and entityid columns