Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Microsoft Dynamics 365 for Operations Connector

Select

Version: 1.0.0

The Microsoft Dynamics 365 for Operations Connector for Anypoint platform enables integration with Microsoft Dynamics 365 for Operations Web API.

This connector lets you perform these operations:

  • Authorize or unauthorize access to a Microsoft Dynamics 365 for Operations server.

  • Create a recurring job on Microsoft Dynamics 365 for Operations server.

  • Retrieve multiple entities.

  • Retrieve multiple entities using the DataSense Query Language.

  • Execute operations.

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and the Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing one or more Anypoint Studio Tutorials. Further, this page assumes that you have a basic understanding of Mule flows and Mule Global Elements.

Before starting, you need access to a Microsoft Dynamics 365 instance (online or on-premise) managed by Azure Active Directory.

About Connector Terminology

  • Actions - Operations that allow side effects, such as data modification, and cannot be further composed to avoid non-deterministic behavior.

  • Complex types - Keyless named structured types consisting of a set of properties. Complex types are commonly used as property values in model entities, or as parameters or return values for operations.

  • Entities - Instances of entity types, for example, an account or an opportunity.

  • Entity sets - Named collections of entities, for example, an account is an entity set containing account entities. An entity’s key uniquely identifies the entity within an entity set.

  • Entity types - Named structured types with a key. Entity types define the named properties and relationships of an entity, and may derive by single inheritance from other entity types.

  • Enumeration types or Enum types - Named primitive types whose values are named constants with underlying integer values.

  • Functions - Operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action.

To Install and Configure the Connector

  1. Download and install Java 8 (latest version) or Java 7 (deprecated by Oracle).

  2. Click the exchange-icon, search for 365, and follow the prompts to install the connector.

Note: JCE is not required for this connector.

To Create a New Mule Project Using Anypoint Studio Visual Editor

  1. In Anypoint Studio, click File > New > Mule Project.

  2. Specify a Project Name and click Finish.

  3. Search for "http" and drag the HTTP connector to the canvas. Click the green plus sign next to Connector Configuration, and click OK in the menu to accept the default values.

  4. Search for "365" and drag the Microsoft Dynamics 365 Operations connector to the canvas. Click the green plus next to Connector Configuration, and specify your access credentials.

  5. Click a connection strategy for authentication:

    • Microsoft Dynamics 365 for Operations OAuth 2.0

    • Microsoft Dynamics 365 for Operations OAuth 2.0 Username-Password

To Configure for OAuth 2.0

  1. Click the green plus sign to the right of Connector Configuration.

  2. Provide the Client ID and Secret values.

  3. Choose an action if a token is not provided:

    1. EXCEPTION (Default) - Causes an exception if there is no token.

    2. STOP_FLOW - Stops running the Mule project if there is no token.

To implement OAuth 2.0 in the Connection configuration you will need Mule Runtime version greater or equal to 3.8.5, if you are using a previous version you need to obtain a patch for the Mule Runtime from MuleSoft Customer Support. Reference the Mule DevKit Support module issue.

To Configure for OAuth 2.0 Username-Password

  1. Click the green plus sign to the right of Connector Configuration.

  2. Provide the following credentials to enable access to your Microsoft Dynamics 365 server:

    • Username - Username used to initialize the session.

    • Password - Password used to authenticate the user.

    • Resource - The application ID URI of the web API (secured resource). This must be the root URI, without specifing the CRM version. Example: https://YOUR_ORG.operations.dynamics.com/

    • Client ID - The application ID assigned to your app when you registered it with Azure Active Directory. You can find this in the Azure Portal (portal.azure.com). Click Active Directory, click the directory, choose the application, and click Configure.

    • Client Secret - The application secret that you created in the app registration portal for your app. This should not be used in a native app, because client secrets cannot be reliably stored on devices. This is required for web apps and web APIs, which have the ability to store the client secret securely on the server side. You can find this in the Azure Portal (portal.azure.com).

    • Token Request Endpoint - The token endpoint that is called to get the access token. Example: https://login.windows.net/TENANT_ID/oauth2/token where TENANT_ID is the Azure Active Directory ID.

    • Read Timeout - The duration in milliseconds that the consumer waits for a response before timing out. Zero (0) means wait forever.

    • Connection Timeout - Specifies the duration in milliseconds that the consumer tries to establish a connection before timing out. Zero (0) means wait forever.

  3. Click Test Connection to ensure that your credentials are accepted at the server endpoint.

  4. If present, click Enable DataSense to let your application acquire metadata from the server.

For information on setting the Pooling Profile tab, see About Pooling Profiles.

For information on setting the Reconnection tab, see Configuring Reconnection Strategies.

To Run a Flow

  1. In Package Explorer, right click your project’s name, and click Run As > Mule Application.

  2. Check the console to see when the application starts. You should see messages such as these if no errors occur:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
************************************************************
INFO  2017-05-14 22:12:42,003 [main] org.mule.module.launcher.DeploymentDirectoryWatcher:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Mule is up and kicking (every 5000ms)                    +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INFO  2017-05-14 22:12:42,006 [main] org.mule.module.launcher.StartupSummaryDeploymentListener:
**********************************************************
*  - - + DOMAIN + - -               * - - + STATUS + - - *
**********************************************************
* default                           * DEPLOYED           *
**********************************************************

************************************************************************
* - - + APPLICATION + - -   * - - + DOMAIN + - -  * - - + STATUS + - - *
************************************************************************
* myapp                     * default             * DEPLOYED           *
************************************************************************

To Configure Connector Operations

To Authorize Access to the CRM Server

  1. Set Operation to Authorize.

  2. Specify a string to be sent with the callback from the authentication server.

  3. Provide the Access Token URL given to you by the service provider.

  4. Provide the Authorization URL given to you by the service provider. This URL indicates where the resource owner redirects to grant authorization to the connector.

  5. Provide the access token ID for authenticating the authorize call.

  6. Specify the Scope.

  7. Specify the Response_mode, which is the method that sends the token back to your app. Possible values are query or form_post.

  8. Specify the Resource (required).

To Unauthorize Access from the CRM Server

  1. Set Operation to Unauthorize.

  2. Provide the Access Token URL that you used to authorize access to the CRM server.

To Execute an Operation

This operation lets you consume an AOTService group node action or a custom deployed action using the 300+ operations provided by Microsoft Dynamics 365.

  1. Set Operation to Execute Operation.

  2. Specify a Service Group (required) - A service group that groups multiple services.

  3. Specify a Service (required) - A service that groups multiple operations.

  4. Specify an Operation (required) - The operation to execute.

  5. To provide parameters (optional), specify a MEL expression or create the object manually as one or more key and value pairs.

Example:

You can use Execute Operation to change a time zone as an HTTP POST request as follows (substitute HOST_URI for the URI of the Microsoft Dynamics 365 server:

https://HOST_URI/api/services/UserSessionService/AifUserSessionService/ApplyTimeZone

Use the following parameters:

  • dateTime - String type in the YYYY-MM-DD format.

  • timeZoneOffset - Integer type.

To Import Data Recurring Job

This operation lets you automate the process of importing data for an entity, for example, to create a flow that reads data files from a specific folder or imports files with information on an entity. The source data type format can be CSV, XLS, or XML.

  1. Set Operation to Import Data Recurring Job.

  2. Specify the URI Path - The path to the resource.

  3. Specify the Activity ID (required) - The ID of the recurring job created by the user.

  4. Specify the Entity Name (required) - The entity for which you push or import data.

  5. Specify a MEL expression for the File Input - The file that contains data to be submitted for a specific entity.

To Retrieve Multiple Entities

Retrieve multiple entities based on a URL request.

  1. Set Operation to Retrieve Multiple.

  2. Specify the Data Query URL or MEL expression for what to retrieve - The URL to retrieve the entities substitute BASE_URI for the URI of the entity.

    Format: https://BASE_URI/data/DataEntity

  3. Specify the Paging Fetch Size in pages to retrieve. The default is 100 pages.

To Retrieve Multiple Entities by Query

Use the DataSense Query Language to query and retrieve complex data stored in a remote application.

  1. Set Operation to Retrieve Multiple By Query.

  2. Specify the query language.

  3. Configure the Query for what you want to retrieve. For more information on DataSense queuries, see DataSense Query Language.

  4. Specify the Paging Fetch Size in pages to retrieve. The default is 100 pages.

Example:

Retrieve multiple customer entities using DSQL:

SELECT AddressCity,AddressCounty,SiteId,WarehouseId FROM Customers

Example: Microsoft Dynamics 365 Operations

This example demonstrates the use of Microsoft Dynamics 365 for Operations Connector.

To build and run this demo project you need:

  • Anypoint Studio with at least Mule 3.5 Runtime.

  • Microsoft Dynamics 365 for Operations Connector v1.0.0 or higher.

Components:

  • IMPORT_DATA_RECURRING_JOB_DEMO: This flow imports data for a recurring job. An entity name, activity ID, and a file containg data must be provided.

    POST - The HTTP endpoint listens to the following URL:

    http://0.0.0.0:8081/import

  • RETRIEVE_MULTIPLE_BY_URL: This flow retrieves multiple entities based on a URL request.

    GET - The HTTP endpoint listens to the following URL:

    http://0.0.0.0:8081/retrieveCustomers

  • RETRIEVE_MULTIPLE_BY_DSQL: This flow retrieves multiple entities based on DataSense Query Language.

    GET - The HTTP endpoint listens to the following URL:

    http://0.0.0.0:8081/retrieveCustomersByQuery

  • APPLY_TIMEZONE: This flow applies the timezone based on provided the dateTime and timezoneOffset.

    POST - The HTTP endpoint listens to the following URL:

    http://0.0.0.0:8081/applyTimezone

You can use the selection menu from http://0.0.0.0:8081 to test the flows or you can POST JSONs using a tool like curl, or any other tool (Chrome/Mozilla Firefox extensions) that lets you POST a body when calling the URL.

To Test the Flow

  1. Import the demo project into your workspace using Anypoint Exchange or Import from File menu.

  2. Specify your OAuth2 credentials for OAuth2 Username Password Config in the /src/main/app/mule-app.properties file:

    • dynamics365.username - Username used to initialize the session.

    • dynamics365.password - Password used to authenticate the user.

    • dynamics365.resource - The App ID URI of the web API (secured resource). This must be root URI, without specifing the Operations version. Example: https://YOUR_ORG.operations.dynamics.com/

    • dynamics365.clientId - The Application ID assigned to your app when you registered it with Azure AD. You can find this in the Azure Portal. Click Active Directory, click the directory, choose the application, and click Configure.

    • dynamics365.clientSecret - The Application Secret that you created in the app registration portal for your app. This should not be used in a native app, because client_secrets cannot be reliably stored on devices. This is required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.

    • dynamics365.tokenRequestEndpoint - The token endpoint that is called to get the access token. Example: `+https://login.windows.net/TENANT_ID/oauth2/token where TENANT_ID is the Azure AD ID.

  3. Specify DataSense Connection Timeout with more than 200 seconds because the connector makes several requests to provide DataSense information.

  4. Run the project in Studio.

  5. Type 0.0.0.0:8081 in your browser to access the selection menu of the demo.

  6. Optionally you can configure the Connection Timeout and Read Timeout. The Connection Timeout is the timeout in making the initial connection with the server. The Read Timeout is the timeout on waiting to read data from the server.

Visual Editor Flow

365-operations-flow

XML Flow


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:dynamics365foroperations="http://www.mulesoft.org/schema/mule/dynamics365foroperations" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/dynamics365foroperations http://www.mulesoft.org/schema/mule/dynamics365foroperations/current/mule-dynamics365foroperations.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <dynamics365foroperations:config-oauth-user-pass name="Microsoft_Dynamics_365_for_Operations__OAuth_2_0_Username_Password" clientId="${dynamics365.clientId}" username="${dynamics365.username}" password="${dynamics365.password}" resource="${dynamics365.resource}" clientSecret="${dynamics365.clientSecret}" tokenRequestEndpoint="${dynamics365.tokenRequestEndpoint}" doc:name="Microsoft Dynamics 365 for Operations: OAuth 2.0 Username-Password"/>
    <flow name="PARSE_DEMO_TEMPLATE">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <parse-template location="form.html" doc:name="Parse Template"/>
        <set-property propertyName="content-type" value="text/html" encoding="US-ASCII" mimeType="text/html" doc:name="Property"/>
    </flow>
    <flow name="IMPORT_DATA_RECURRING_JOB_DEMO">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/import" doc:name="HTTP"/>
        <logger message="Requested 'Import Data Recurring Job' Operation" level="INFO" doc:name="Logger"/>
        <dynamics365foroperations:import-data-recurring-job config-ref="Microsoft_Dynamics_365_for_Operations__OAuth_2_0_Username_Password" doc:name="Microsoft Dynamics 365 for Operations" activityId="#[message.inboundAttachments.get('activityId')]" entityName="#[message.inboundAttachments.get('entity')]" in-ref="#[message.inboundAttachments.get('file')]"/>
        <logger message="#[message.inboundAttachments.get('activityId')]+ #[message.inboundAttachments.get('entity')]+ #[message.inboundAttachments.get('file')]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="RETRIEVE_MULTIPLE_BY_URL">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/retrieveCustomers" doc:name="HTTP"/>
        <logger message="Calling ${dynamics365.resource}/data/Customers" level="INFO" doc:name="Logger"/>
        <dynamics365foroperations:retrieve-multiple config-ref="Microsoft_Dynamics_365_for_Operations__OAuth_2_0_Username_Password" doc:name="Microsoft Dynamics 365 for Operations" dataQueryURL="${dynamics365.resource}/data/Customers"/>
        <logger message="Received Response from 'Retrieve Multiple' Operation" level="INFO" doc:name="Logger"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="RETRIEVE_MULTIPLE_BY_DSQL">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/retrieveCustomersByQuery" doc:name="HTTP"/>
        <logger message="Requested 'Retrieve Multiple By DataSense Query Language' Operation" level="INFO" doc:name="Logger"/>
        <dynamics365foroperations:retrieve-multiple-by-query config-ref="Microsoft_Dynamics_365_for_Operations__OAuth_2_0_Username_Password" query="dsql:SELECT AddressCity,AddressCounty,SiteId,WarehouseId FROM Customers" doc:name="Microsoft Dynamics 365 for Operations"/>
        <logger message="Received Response from 'Retrieve Multiple By DataSense Query Language' Operation" level="INFO" doc:name="Logger"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="APPLY_TIMEZONE">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/applyTimezone" doc:name="HTTP"/>
        <logger message="Requested 'Apply Timezone' Operation" level="INFO" doc:name="Logger"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
    dateTime: payload.dateTime,
    timeZoneOffset: payload.timeZoneOffset
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamics365foroperations:execute-operation config-ref="Microsoft_Dynamics_365_for_Operations__OAuth_2_0_Username_Password" operation="UserSessionService||AifUserSessionService||ApplyTimeZone" doc:name="Microsoft Dynamics 365 for Operations">
            <dynamics365foroperations:parameters ref="#[payload]"/>
        </dynamics365foroperations:execute-operation>
        <logger message="Received Response from 'Apply Timezone' Operation" level="INFO" doc:name="Logger"/>
    </flow>
</mule>