Nav

Microsoft Dynamics NAV Connector

The Anypoint Connector for Microsoft Dynamics NAV enables Mule applications to interact with Microsoft Dynamics NAV Web Services. Microsoft Dynamics NAV is a global enterprise resource planning (ERP) solution to assist with finance, manufacturing, customer relationship management, supply chains, analytics and electronic commerce for small and medium-sized enterprise and local subsidiaries of large international groups. MuleSoft maintains this connector under the Select support policy.

The versions of Microsoft Dynamics NAV supported by this connector are:

  • 2013 R2

  • 2015

  • 2016

Operations Supported

The Microsoft Dynamics NAV Connector supports the following operations:

  • OData Query: Executes a Query against one of the NAV entities (a published Page services or Query services) using the OData endpoint. For Containments and Associations, a String (shown in Query Builder with type NavigationProperty) is returned, which contains the path to the related entity or collection.

    Some operation behaviors, like 'Order By' differ between the different NAV versions.
  • Page Operation: Executes an operation from one of the published Page SOAP services. See Publishing a Page service. The operation can be a basic Page Operation or a custom codeunit extension.

  • Codeunit Operation: Executes an operation from one of the published Codeunit SOAP services. See Publishing a Codeunit service.

Prerequisites

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

  • Anypoint Studio: if you don’t use Anypoint Studio for development, follow the instructions on specifying Maven dependencies in your pom.xml file.

Before creating a sample flow, a published Page Service is necessary. That can be achieved following the instructions here.

Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.

Compatibility

The Microsoft Dynamics NAV connector is compatible with:

Application/Service Version

Anypoint Studio

5.4.x or higher

Mule Runtime EE

3.8.x or higher

Java

1.7 or higher

MS Dynamics NAV

2013 R2, 2015 and 2016

To Install this Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

Create a New Mule Project

Open Anypoint Studio and create a new project:

  1. From the menu, select File > New > Mule Project.

  2. In the New Mule Project window, enter nav-demo as the Project Name.

  3. Click Finish.

Create the Global Element

  1. Click the Global Elements tab.

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

  3. In the Search text box, enter nav.

  4. Select Microsoft Dynamics NAV: OAuth2.0 Access Token Connection and click OK.

  5. Fill in the required parameters:

    Microsoft Dynamics NAV Connector Global Element

    OAuth2.0

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

  7. Once the connection is successful, click OK.

Authentication Methods

Supported authentication schemes for Microsoft Dynamics NAV on-premises are:

  • Windows NTLM

  • Access Token based

Windows Authentication - NTLM

Prerequisites:

NAV instance configured with Credential Type Windows or UserName.

Parameter Description

Domain

Domain of the Dynamics NAV instance

Username

The Windows username to connect to Dynamics NAV.

Password

The password for the user to connect to Dynamics NAV.

SOAP URL

Base URL where the SOAP services are exposed in the form https://<Server>:<WebServicePort>/<ServerInstance>/WS. Example: https://hostname:7047/DynamicsNAV90/WS

OData URL

Base URL where the OData services are exposed in the form https://<Server>:<WebServicePort>/<ServerInstance>/OData. Example: https://hostname:7048/DynamicsNAV90/OData.

Company Name (Optional)

Dynamics NAV Company to connect to. In case the field is left blank, the default configured one is used.

Disable Cn Check

Disables Common Name (CN) Checking on SSL certificates (optional). Note: this is not recommended for production environments.

Dynamics NAV Access Token

Prerequisites:

NAV instance configured with Credential Type NavUserPassword. A user with an access token for web services configured. (How to)

Parameter Description

Username

The Dynamics NAV username to connect to Dynamics NAV.

Access Token

The access token configured for the user to access web services.

SOAP URL

Base URL where the SOAP services are exposed in the form https://<Server>:<WebServicePort>/<ServerInstance>/WS. Example: https://hostname:7047/DynamicsNAV90/WS

OData URL

Base URL where the OData services are exposed in the form https://<Server>:<WebServicePort>/<ServerInstance>/OData. Example: https://hostname:7048/DynamicsNAV90/OData.

Company Name (Optional)

Dynamics NAV Company to connect to. In case the field is left blank, the default configured one is used.

Disable Cn Check

Disables Common Name (CN) Checking on SSL certificates (optional). Note: this is not recommended for production environments.

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

Namespace: http://www.mulesoft.org/schema/mule/dynamics-nav Schema Location: http://www.mulesoft.org/schema/mule/dynamics-nav/current/mule-dynamics-nav.xsd

If you are manually coding the Mule application in Studio’s XML editor or other text editor, paste these into the header of your Configuration XML, inside the <mule> tag.
<mule xmlns:dynamics-nav="http://www.mulesoft.org/schema/mule/dynamics-nav"
  ...
  xsi:schemaLocation="http://www.mulesoft.org/schema/mule/dynamics-nav http://www.mulesoft.org/schema/mule/dynamics-nav/current/mule-dynamics-nav.xsd">
  ...
  <flow name="yourFlow">
  ...
  </flow>
</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>mule-module-ms-dynamics-nav</artifactId>
  <version>1.0.0</version>
</dependency>

Demo Mule Applications Using Connector

You can download fully functional demo applications using the Microsoft Dynamics NAV connector from this page.

Example Use Case

This set of use cases describes how to create a Mule application to use Microsoft Dynamics NAV SOAP Countries' CRUD page operations using OAuth2.0 Access Token.

Create Country

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

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

    
                  
               
    1
    2
    3
    4
    5
    6
    7
    
    %dw 1.0
    %output application/java
    ---
    {
        Code : inboundProperties."http.query.params".code,
        Name : inboundProperties."http.query.params".name
    }
  3. Drag a Microsoft Dynamics NAV Connector next to the Transform Message.

    1. Set it’s configuration to OAuth2.0 Access Token or NTLM and fill the required values (Check the SSL checkbox).

    2. Select Page operation, Countries and Create on their respective fields. 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
    
    %dw 1.0
    %output application/java
    ---
    {
            Key : payload.Key
    }
  5. Drag a Microsoft Dynamics NAV Connector next to the Transform Message. Select the same configuration that was set before

    1. Select Countries and GetRecIdFromKey on their respective fields and leave Entity Reference as it is.

List Countries

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

  2. Drag a Variable from the Mule Palette next to the HTTP Listener.

    1. Fill the Name field with CountriesList and Value field with the MEL: #[[]] (this creates an array list)

  3. Drag a Microsoft Dynamics NAV Connector next to the Variable. Select the same configuration that was set before.

    1. Select OData Query on the Operation field and click on the Query Builder…​ button.

      1. On the Types section select Countries. Click on Code and Name on the Fields section.

      2. Select Code in the Order By field, DESCENDING on the Direction field.

      3. Write the max number of records that you wish to retrieve in the Limit field. Here we will set it to 100.

  4. Add a For Each Scope after the Connector. Within the Scope, add:

    1. An Expression Filter with the following MEL: #[!payload.Code.isEmpty()] in order to prevent the Mule app from breaking in case there is a Country with an empty Code.

    2. A Transform Message element next to the Filter and write:

      
                       
                    
      1
      2
      3
      4
      5
      6
      
      %dw 1.0
      %output application/java
      ---
      {
              Code : payload.Code
      }
    3. A Microsoft Dynamics NAV Connector with the same configuration that was set before.

      1. Select Page Operation, Countries and Read on their corresponding fields and leave Entity Reference as it is.

    4. An Expression Component with the following MEL: #[flowVars.CountriesList.add(payload)] in order to add the results of the Read operation to the Variable that was declared before.

  5. Drag a Set Payload element with the value: #[flowVars.CountriesList]

  6. Drag an Object to JSON Transformer to view the results as a JSON.

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
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:metadata="http://www.mulesoft.org/schema/mule/metadata" xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:dynamics-nav="http://www.mulesoft.org/schema/mule/dynamics-nav" xmlns:http="http://www.mulesoft.org/schema/mule/http" 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/dynamics-nav http://www.mulesoft.org/schema/mule/dynamics-nav/current/mule-dynamics-nav.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/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://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <dynamics-nav:config-oauth-token name="Microsoft_Dynamics_NAV_Connector__OAuth_2_0_Access_Token" username="${nav.username}" accessToken="${nav.accessToken}" soapUrl="${nav.soapUrl}" odataUrl="${nav.odataUrl}" companyName="${nav.companyName}" disableCnCheck="true" doc:name="Microsoft Dynamics NAV Connector: OAuth 2.0 Access Token"/>
    <flow name="CreateCountryAndGetRecID">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/create" doc:name="/create"/>
        <dw:transform-message doc:name="Send Input as an Object">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
    Code : inboundProperties."http.query.params".code,
    Name : inboundProperties."http.query.params".name
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamics-nav:page-operation config-ref="Microsoft_Dynamics_NAV_Connector__OAuth_2_0_Access_Token" serviceOperation="Countries||Create" doc:name="Create Country"/>
        <dw:transform-message doc:name="Extract the Key">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        Key : payload.Key
}]]></dw:set-payload>
        </dw:transform-message>
        <dynamics-nav:page-operation config-ref="Microsoft_Dynamics_NAV_Connector__OAuth_2_0_Access_Token" serviceOperation="Countries||GetRecIdFromKey" doc:name="Get Record ID"/>
    </flow>
    <flow name="ReadCountry_ODataAndSOAPInSameFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/read" doc:name="/read"/>
        <set-variable variableName="CountriesList" value="#[[]]" doc:name="Countries List"/>
        <dynamics-nav:odata-query config-ref="Microsoft_Dynamics_NAV_Connector__OAuth_2_0_Access_Token" query="dsql:SELECT Code,Name FROM Countries ORDER BY Code DESC LIMIT 5" doc:name="OData Query"/>
        <foreach doc:name="For Each">
                    <expression-filter expression="#[!payload.Code.isEmpty()]" doc:name="Filter Countries with empty Code value"/>
                    <dw:transform-message doc:name="Extract Code">
                        <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
        Code : payload.Code
}]]></dw:set-payload>
                    </dw:transform-message>
                    <dynamics-nav:page-operation config-ref="Microsoft_Dynamics_NAV_Connector__OAuth_2_0_Access_Token" serviceOperation="Countries||Read" doc:name="Read Country"/>
                    <expression-component doc:name="Add Country to Countries List"><![CDATA[#[flowVars.CountriesList.add(payload)]]]></expression-component>
        </foreach>
        <set-payload value="#[flowVars.CountriesList]" doc:name="Set the list as payload"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
</mule>