Dynamics GP Icon

Introduction

The Microsoft Dynamics GP connector enables Mule applications to interact with the Microsoft Dynamics Great Plains (GP) Web Services.

Read through this user guide to understand how to set up and configure a basic flow using the connector. Track feature additions, compatibility, limitations and API version updates with each release of the connector using the Connector Release Notes. Review the connector operations and functionality using the Technical Reference alongside the demo applications.

MuleSoft maintains this connector under the Select support policy.

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing a Anypoint Studio Tutorial. This page requires some basic knowledge of Mule Concepts, Elements in a Mule Flow, and Global Elements.

Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.
The connector interacts with Dynamics GP web service. In order to make the integration with Mule Platform the Dynamics GP instance must be exposed through the Dynamics GP web service. Information about web service configuration can be found in Web Services Installation and Administration Guide.

Java Cryptography Extension (JCE) is required for the authentication process. JCE-7 can be downloaded from Java Cryptography Extension (JCE).

Compatibility

The Microsoft Dynamics GP connector is compatible with:

Application/Service Version

Mule Runtime EE

3.7.x and higher

Java

7 and higher

MS Dynamics GP

  • 2010 R2

  • 2013 (Version 12)

  • 2013 R2

  • 2015 (Version 14)

  • 2015 R2

Installing the Connector

You can install the connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Configuring the Connector Global Element

To use the Dynamics GP connector in your Mule application, you must configure a global Dynamics GP element that can be used by all the Dynamics GP connectors in the applications. Global elements can be of two types:

  1. Kerberos Authentication: establishes a connection with Microsoft Dynamics GP on-premises using the native Kerberos authentication.

    The Kerberos protocol defines how clients interact with a network authentication service. Clients obtain tickets from the Kerberos Key Distribution Center (KDC), and they present these tickets to servers when connections are established. Kerberos tickets represent the client’s network credentials.

  2. NTLM Authentication: establishes a connection with Microsoft Dynamics GP on-premises using the legacy NTLM authentication.

    Windows Challenge/Response (NTLM) is the authentication protocol used on networks that include systems running the Windows operating system and on stand-alone systems. NTLM credentials are based on data obtained during the interactive logon process and consist of a domain name, a user name, and a one-way hash of the user’s password.

Kerberos Authentication

For Kerberos configuration make sure that the server is configured to use Kerberos authentication. More information can be found in Web Services Installation and Administration Guide chapter 8.

  1. Click the Global Elements tab.

  2. Click Create to bring up Global Type dialog box.

  3. In the Search text box, enter GP and fill in the required parameters.

    Kerberos Config

  4. Click Test Connection to make sure the connection works correctly.

  5. Once the connection is successful, click OK.

Parameter Description

Username

User Principal Name of the Dynamics GP user to authenticate.

Password

The password for the user to connect to Dynamics GP.

Endpoint URL

Base URL where the SOAP services are exposed in the form http://<Server>:<WebServicePort>/Dynamics/GPService/GPService.

Example: http://hostname:7047/Dynamics/GPService/GPService

SPN

The service principal name that identifies the service instance

Login Conf. Location

Path to the Kerberos login module. Example: C:\kerberos\login.conf

Krb5 Conf. Location

Path to the Kerberos configuration file.

Example: C\kerberos\krb5.conf

Following is a sample of the Kerberos configuration file:

[libdefaults]
default_realm = MYREALM.COM

[realms]
MYREALM.COM = {
 kdc = mydomaincontroller.myrealm.com
 default_domain = MYREALM.COM
}

[domain_realm]
.myrealm.com = MYREALM.COM
myrealm.com = MYREALM.COM
The realm / default_domain are case-sensitive and must be specified exactly as defined in Active Directory. Receiving an error during Test Connection stating “Message stream modified (41)” then this is an indication that the domain name is not correctly formed.

More information on how to create the Kerberos configuration file can be found at http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html.

The Kerberos login module (Krb5LoginModule) can be tuned with scenario-specific configurations by defining a JAAS login configuration file. Following is a sample of the JAAS login configuration file for the Kerberos login module:

Kerberos {
    com.sun.security.auth.module.Krb5LoginModule required
    debug=true
    refreshKrb5Config=true;
};

More information on how to create the JAAS login configuration file for the Kerberos login module can be found at http://docs.oracle.com/javase/7/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html.

NTLM Authentication

  1. Click the Global Elements tab.

  2. Click Create to bring up Global Type dialog box.

  3. In the Search text box, enter GP and fill in the required parameters.

    NTLM Config

  4. Click Test Connection to make sure the connection works correctly.

  5. Once the connection is successful, click OK.

Parameter Description

Username

User account of the Dynamics GP user to authenticate.

Password

Password for the user to connect to Dynamics GP.

Endpoint

Base URL where the SOAP services are exposed in the form http://<Server>:<WebServicePort>/DynamicsGPWebServices/DynamicsGPService.asmx.

Example: http://hostname:7047/DynamicsGPWebServices/DynamicsGPService.asmx

Domain

Domain of the Dynamics GP instance
Make sure to set the 'user account' at the 'Username' field as it’s defined here.
That means that you don’t have to include the domain name in the Username.

Using the Connector

See a full list of operations for any version of the connector here.

Connector Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

If you are manually coding the Mule application in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag. 

  
1
2
3
4
5
6
7
8
9
10
11
12


  
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:dynamicsgp="http://www.mulesoft.org/schema/mule/dynamicsgp"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/dynamicsgp
               http://www.mulesoft.org/schema/mule/dynamicsgp/current/mule-dynamicsgp.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.


  
1
2
3
4
5


  
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>ms-dynamics-gp-connector</artifactId>
  <version>1.0.0</version>
</dependency>

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version.

Demo Mule Applications Using Connector

You can download fully functional demo applications using the Dynamics GP connector from this link.

Example Use Case

This set of use cases describe how to create a Mule application to use Microsoft Dynamics GP CRUD operations using either Kerberos or NTLM authentication.

Create Customer

  1. Drag from the Mule Palette a HTTP Listener element to the canvas and use the default configuration but with the path set to /createCustomer.

  2. Drag a Transform Message element next to the HTTP Listener an write:

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    		
  
    %dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                }  as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        customer: {
                key: {
                        id: inboundProperties."http.query.params".customerKeyID
                },
                name: inboundProperties."http.query.params".customerName
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.CreateCustomerParams"
}

  3. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Set it’s configuration to NTLM or Kerberos Connection and fill the required fields, this will apply to all the other Dynamics GP connectors that are dragged into the flows.

    2. Select the operation Create Customer. Leave the Entity Reference as it is.

  4. Drag a Set Payload element next to the Connector and set it’s value as "Success"

Get Customer

  1. Drag from the Mule Palette a HTTP Listener element to the canvas and use the default configuration but with the path set to /getCustomer.

  2. Drag a Transform Message element next to the HTTP Listener and write:

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    		
  
    %dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                }  as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },

        key: {
                id: inboundProperties."http.query.params".customerKeyID
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerByKeyParams"
}

  3. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Select the operation Get Customer By Key. Leave the Entity Reference as it is.

  4. Drag an Object to JSON element next to the connector and leave it as it is.

Update Customer

  1. Drag from the Mule Palette a HTTP Listener element to the canvas and use the default configuration but with the path set to /updateCustomer

  2. Drag a Transform Message element next to the HTTP Listener and write:

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

    		
  
    %dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
    class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
    }
        },
        key: {
                id: inboundProperties."http.query.params".keyId
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerByKeyParams"
}

  3. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Select the Get Customer By Key operation. Leave the Entity Reference as it is.

  4. Drag a Transform Message element next to the Connector and write:


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21


  
%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
    class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
    }
        },
        customer: {
                comment1: flowVars.UpdatedComment,
                key: {
                        id: payload.key.id
                },
                name: payload.name
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.UpdateCustomerParams"
}

  1. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Select the Update Customer operation. Leave the Entity Reference as it is.

  2. Drag a Set Payload element next to the Connector and set it’s value as "Success".

Delete Customer

  1. Drag from the Mule Palette a HTTP Listener element to the canvas and use the default configuration but with the path set to /deleteCustomer.

  2. Drag a Transform Message element next to the HTTP Listener and write:

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

    		
  
    %dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        key: {
                id: inboundProperties."http.query.params".customerKeyID
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.DeleteCustomerParams"
}

  3. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Select the Delete Customer operation. Leave the Entity Reference as it is.

  4. Drag a Set Payload element next to the Connector and set it’s value as "Success".

Get Customer List

  1. Drag from the Mule Palette a HTTP Listener element to the canvas and use the default configuration but with the path set to /getCustomerList.

  2. Drag a Transform Message element next to the HTTP Listener and write:

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    		
  
    %dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        criteria: {
                name: {
                        like: inboundProperties."http.query.params".like
                }
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerListParams"
}

  3. Drag a Microsoft Dynamics GP connector next to the Transform Message.

    1. Select the Get Customer List operation. Leave the Entity Reference as it is.

  4. Drag an Object to JSON element next to the connector and leave it as it is.

Example Use Case - XML

Paste this into Anypoint Studio to interact with the example use case application discussed in this guide.


  
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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182


  
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:json="http://www.mulesoft.org/schema/mule/json"
      xmlns:metadata="http://www.mulesoft.org/schema/mule/metadata"
      xmlns:dynamicsgp="http://www.mulesoft.org/schema/mule/dynamicsgp"
      xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:http="http://www.mulesoft.org/schema/mule/http"
      xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml"
      xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" 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/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/dynamicsgp http://www.mulesoft.org/schema/mule/dynamicsgp/current/mule-dynamicsgp.xsd
http://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.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/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8082"
                          doc:name="HTTP Listener Configuration"/>
    <dynamicsgp:config-kerberos name="Dynamics_GP__Kerberos_Connection" username="${gp-kerberos.username}" password="${gp-kerberos.password}" endpoint="${gp-kerberos.endpoint}" spn="${gp-kerberos.spn}" loginConfLocation="${gp-kerberos.loginConfLocation}" krb5ConfLocation="${gp-kerberos.krb5ConfLocation}" doc:name="Microsoft Dynamics GP: Kerberos Connection"/>
    <flow name="CreateCustomer">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/createCustomer"
                       doc:name="/createCustomer"/>
        <dw:transform-message doc:name="Set Create Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                }  as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        customer: {
                key: {
                        id: inboundProperties."http.query.params".customerKeyID
                },
                name: inboundProperties."http.query.params".customerName
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.CreateCustomerParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:create-customer config-ref="Dynamics_GP__Kerberos_Connection"
                                    doc:name="Create Customer" params-ref="#[payload]"/>
        <set-payload value="&quot;Success&quot;" doc:name="Set Payload"/>
    </flow>
    <flow name="GetCustomer">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/getCustomer"
                       doc:name="/getCustomer"/>
        <dw:transform-message doc:name="Set Get Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                }  as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },

        key: {
                id: inboundProperties."http.query.params".customerKeyID
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerByKeyParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:get-customer-by-key config-ref="Dynamics_GP__Kerberos_Connection" params-ref="#[payload]" doc:name="Get Customer By Key"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="UpdateCustomer">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/updateCustomer"
                       doc:name="/updateCustomer"/>
        <set-variable variableName="UpdatedComment" value="#[message.inboundProperties.'http.query.params'.updatedComment]" doc:name="UpdatedComment"/>
        <dw:transform-message doc:name="Set GetByKey Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
    class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
    }
        },
        key: {
                id: inboundProperties."http.query.params".keyId
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerByKeyParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:get-customer-by-key config-ref="Dynamics_GP__Kerberos_Connection" doc:name="Get Customer by Key"
                                        params-ref="#[payload]"/>
        <dw:transform-message doc:name="Set Update Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
    class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
    }
        },
        customer: {
                comment1: flowVars.UpdatedComment,
                key: {
                        id: payload.key.id
                },
                name: payload.name
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.UpdateCustomerParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:update-customer config-ref="Dynamics_GP__Kerberos_Connection" params-ref="#[payload]" doc:name="Update Customer"/>
        <set-payload value="&quot;Success&quot;" doc:name="Set Payload"/>
    </flow>
    <flow name="DeleteCustomer">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/deleteCustomer"
                       doc:name="/deleteCustomer"/>
        <dw:transform-message doc:name="Set Delete Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        key: {
                id: inboundProperties."http.query.params".customerKeyID
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.DeleteCustomerParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:delete-customer config-ref="Dynamics_GP__Kerberos_Connection" params-ref="#[payload]" doc:name="Delete Customer"/>
        <set-payload value="&quot;Success&quot;" doc:name="Set Payload"/>
    </flow>
    <flow name="GetCustomerList">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/getCustomerList" doc:name="/getCustomerList"/>
        <dw:transform-message doc:name="Set GetList Request">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        context: {
                organizationKey: {
                        id: inboundProperties."http.query.params".companyKeyID
                } as :object {
        class : "org.mule.modules.dynamics.gp.api.entity.CompanyKey"
        }
        },
        criteria: {
                name: {
                        like: inboundProperties."http.query.params".like
                }
        }
} as :object {
        class : "org.mule.modules.dynamics.gp.api.param.GetCustomerListParams"
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamicsgp:get-customer-list config-ref="Dynamics_GP__Kerberos_Connection" doc:name="Get Customer List"
                                      params-ref="#[payload]"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>

</mule>

Resources