Microsoft Dynamics CRM connection¶
Introduction¶
A Microsoft Dynamics CRM connection, created using the Microsoft Dynamics CRM connector, establishes access to Microsoft Dynamics CRM. Once a connection is configured, you can create instances of Microsoft Dynamics CRM activities associated with that connection to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).
Note
A Microsoft Dynamics CRM connection requires the use of a Harmony Windows private agent with a Jitterbit Microsoft Dynamics CRM REST Connector. These two pieces of software must be downloaded, installed, and configured prior to the use and configuration of this Integration Studio Microsoft Dynamics CRM Connector. For more information, see Microsoft Dynamics CRM agent configuration.
Note
This connector supports the Enable Re-authentication on Change organization policy. If enabled, a change to the Organizations Service URL or Login in this connection requires users to re-enter the Password for the connection.
Create or edit a Microsoft Dynamics CRM connection¶
A new Microsoft Dynamics CRM connection is created using the Microsoft Dynamics CRM connector from one of these locations:
- The design component palette's Project endpoints and connectors tab (see Design component palette).
- The Global Connections page (see Create a global endpoint in Global Connections).
An existing Microsoft Dynamics CRM connection can be edited from these locations:
- The design component palette's Project endpoints and connectors tab (see Design component palette).
- The project pane's Components tab (see Component actions menu in Project pane Components tab).
- The Global Connections page (see Edit a global endpoint in Global Connections).
Configure a Microsoft Dynamics CRM connection¶
Each user interface element of the Microsoft Dynamics CRM connection configuration screen is described below.
Tip
Fields with a variable icon support using global variables, project variables, and Jitterbit variables. Begin either by typing an open square bracket [
into the field or by clicking the variable icon to display a list of the existing variables to choose from.
-
Connection Name: Enter a name to use to identify the connection. The name must be unique for each Microsoft Dynamics CRM connection and must not contain forward slashes (
/
) or colons (:
). This name is also used to identify the Microsoft Dynamics CRM endpoint, which refers to both a specific connection and its activities. -
Organization Service URL: To locate the organization service URL in a Dynamics CRM cloud instance, log in to the instance and click the Dynamics 365 — custom card. Use the full domain (excluding the path) that is present in your web browser's address bar as input for this field.
Caution
Do not use the organization service URL that is present in a Dynamics CRM cloud instance's Developers Resources page or the deprecated Regional Discovery URL.
-
Login: Enter the user ID registered with the Microsoft Dynamics CRM instance.
-
Password: Enter the password for the user ID registered with the Microsoft Dynamics CRM instance.
-
Connectivity Type: Select the connectivity type that is required to resolve the user ID registered with the Microsoft Dynamics CRM instance. Select one of Active Directory, Federation, Live ID, Online Federation, or None.
-
Application ID: Enter the application ID, visible only when Online Federation is selected as the Connectivity Type. For more information on obtaining the application ID, see Obtain a Microsoft Dynamics CRM application ID.
-
Organization Unique Name: Enter the organization unique name. The organization unique name can be any string without spaces.
-
Domain Name: Enter the domain to which the user ID belongs. Enter the complete domain name, as determined by the selected Connectivity Type.
-
Test: Click to verify the connection using the provided configuration. When the connection is tested, the latest version of the connector is downloaded by the agent(s) in the agent group associated with the current environment. This connector supports suspending the download of the latest connector version by using the Disable Auto Connector Update organization policy.
-
Save Changes: Click to save and close the connection configuration.
-
Discard Changes: After making changes to a new or existing configuration, click to close the configuration without saving. A message asks you to confirm that you want to discard changes.
-
Delete: After opening an existing connection configuration, click to permanently delete the connection from the project and close the configuration (see Component dependencies, deletion, and removal). A message asks you to confirm that you want to delete the connection.
Common connection errors¶
These are common connection errors and their solutions:
Error | Cause | Solution |
---|---|---|
Error: AUTHORIZATION ERROR: Test connection failed., reason:CData elements not valid at top level of an XML document. | The private agent version is too old or the incorrect Jitterbit CRM REST Connector is installed. | Ensure the installed private agent is version 10.42 or later and the correct Jitterbit CRM REST Connector is installed. See Microsoft Dynamics CRM agent configuration for more information. |
Error: Invalid Input: No input for organizationUniqueName | The Organization Unique Name field is empty. | Enter any string without spaces. |
Error: Connection Timeout | The network could be blocking outbound traffic. | Check with network admins to ensure outbound traffic to that URL is allowed. |
Connector Error: The fatal error : Not initialized. | This error can be returned from a Dynamics CRM 2011 server. This may be returned when the Organization Service URL is incorrect. | Verify the Organization Service URL is correct and is not using a Regional Discovery URL. |
Connector Error: The fatal error : Value cannot be null. | This error can be returned from a Dynamics CRM on-premises instance. This may be returned when the Organization Service URL is incorrect. | Verify the Organization Service URL is correct and is not using a Regional Discovery URL. |
Connector Error: The fatal error : AUTHORIZATION ERROR: Test connection failed., reason:One or more errors occurred. | This error can be returned from a Dynamics CRM cloud instance. This may be returned when the Organization Service URL is incorrect. | Verify the Organization Service URL is correct and is not using a Regional Discovery URL. |
Connector Error: The call to url http://127.0.0.1:8000/CRM/TestConnection failed. reason : Connect to 127.0.0.1:8000 [/127.0.0.1] failed: connection refused: connect | the Jitterbit CRM REST connector is not installed or the service is not running. | see Microsoft Dynamics CRM agent configuration for instructions on installing a Jitterbit CRM REST Connector. |
Fatal Error: Object reference not set to an instance of an object. | There is an incorrect application ID, incorrect username or password, or incorrect organization service URL. | Ensure that you are using the appropriate Microsoft Dynamics CRM credentials. For information on obtaining the application ID, see Obtain a Microsoft Dynamics CRM application ID. |
Next steps¶
After a Microsoft Dynamics CRM connection has been created, you place an activity type on the design canvas to create activity instances to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).
Menu actions for a connection and its activity types are accessible from the project pane and design component palette. For details, see Actions menus in Connector basics.
These activity types are available:
-
Upsert: Updates an existing object record or creates a new object record in Microsoft Dynamics CRM and is intended to be used as a target in an operation.
-
Create: Creates an object record in Microsoft Dynamics CRM and is intended to be used as a target in an operation.
-
Update: Updates an existing object record in Microsoft Dynamics CRM and is intended to be used as a target in an operation.
-
Delete: Deletes an object record from Microsoft Dynamics CRM and is intended to be used as a target in an operation.