PHP integration with Microsoft Dynamics NAV

Here at Inviqa we're seeing growing demand for integrations with Microsoft Dynamics NAV as the ERP system for several of our clients. Here we explore how to build an Microsoft Dynamics NAV cloud instance using Microsoft Azure, look at the SOAP API structure, and show you how to access it from the PHP SoapClient.

Put more simply, Microsoft Dynamics NAV is a system that holds customer information, product and inventory information, and sales order information (among other things).

Integrating with Dynamics NAV from outside the Microsoft ecosystem can be done using a SOAP API, which provides access to customer, product, and order information using a consistent set of CRUD operations.

Authentication can at first seem daunting as there are a few options available. If Dynamics NAV is configured to defer authentication to the Windows domain then Kerberos is prefered, but NTLM is also supported.

Thankfully, there's a simpler option which can be achieved by configuring Dynamics NAV to use a user / password combination, which uses Basic Authentication that the PHP SoapClient supports natively. And, as long as this is configured in conjunction with a valid SSL certificate, the security level is acceptable.

Creating an Azure account

If you already have access to a Microsoft infrastructure then you may already have an instance of Dynamics NAV to test against. However, if your background is in open-source technologies, Microsoft Azure presents perhaps the best way to create an instance.

The only caveat to Azure is that you will need to enter your card details in order to create an account, however you will get £125 credit and can cancel at any time, so you don’t actually need to pay anything if you keep an eye on the credit level.

The £125 credit is more than sufficient to allow you to build a few cloud VMs to test your PHP scripts against. Make sure to use the free account option when signing up.

Creating a Dynamics NAV virtual machine

Once you have access to the Azure portal, the following steps need to be taken to build a VM.

Figure 1.1

Click 'Virtual Machines' from the left hand menu, then click the 'Add' tab.

Figure 1.2

Next, enter 'NAV' into the filter input and press return. This should display a list of Dynamics NAV VMs to choose from. Select the latest version – in this case 'Microsoft Dynamics NAV 2016'. On the next screen click the 'Create' button.

Figure 1.3

Next, fill in the basic settings screen. The user name and password will become the Windows user profile when the VM is built. Click 'OK' to proceed.

Figure 1.4

Next, select a VM size configuration. The A1 standard is sufficient for light testing. Click the 'Select' button to proceed. For more information on choosing a VM size, head here.

Figure 1.5

Next, accept the defaults on the optional settings screen and click 'OK' to proceed.

Figure 1.6

Finally, review the summary screen and click 'OK' to begin building the VM.

Figure 1.7

If you return to the dashboard you will see a blue tile indicating that the VM is being built and deployed. This process can take 20 minutes or longer.

Figure 1.8

When the VM is has finished deploying, it should automatically open the VM overview section.

There are a couple of further configuration changes that are needed in order to make the VM accessible to the internet.

Add a DNS name

The first configuration change is to add an entry to the Azure DNS servers.

Figure 2.1

Click 'All resources' from the left hand menu, which will display a list of all the components created when the VM was built. Click on the resource with type 'Public IP address'.

Figure 2.2

On the next screen select 'Configuration'. Then enter a value in the 'DNS name label' field and click 'Save'. This will create an A record on the Azure DNS servers.

Figure 2.3

Now click on 'Overview' and the DNS name should be visible. Here it is set to [inviqa-msnav.northeurope.cloudapp.azure.com]. This value is important and will be needed later.

Add firewall rules

The second configuration change is to open up the ports that are needed to connect.

Figure 3.1

Click 'All resources' from the left hand menu, which will display the list of components again. Click on the resource with type 'Network security group'.

Figure 3.2

On the next screen select 'Inbound security rules'. By default there is just one rule set up, which is to allow remote desktop access (more on remote access below). Click on the 'Add' tab to add a new rule.

Figure 3.3

Fill in the form fields to configure HTTP traffic on TCP port 80, then click 'OK'.

Figure 3.4

Returning to the 'Inbound security rules' screen, the new rule should appear after a few moments. The following additional rules then need adding in the same way:

Microsoft have made setting up Dynamics NAV relatively easy by providing a PowerShell script. This can be found in the C:\DEMO folder. Right click on 'Initialize Virtual Machine' and select 'Run with PowerShell' from the contextual menu.

This will launch a PowerShell terminal application, which will prompt you for information, for which the defaults are mostly acceptable for testing purposes. Below is a summary of the prompts and a response where it differed from the default. The DNS name needs to match the one configured on the Azure IP address component (as described above).

When the management console launches, select 'NAV' from the left hand menu to review the settings. In the 'General' tab the Credential Type should be set to 'NavUserPassword', which means that Basic Authentication is being used.

Web client

At this point you should have a working and accessible Dynamics NAV server. It is useful at this stage to login to the web client and familiarise yourself with the application. The URL is as per the Client Services tab, as described above.

Figure 4.1

The user name and password are the defaults from the PowerShell install script, unless specifically overridden. By default they are:

User name: admin

Password: P@ssword1

Figure 4.2

Once logged in, the summary screen should become visible. From here you can explore the various sections and get an idea of the kind of data stored in the ERP.

Overview

The information stored in Dynamics NAV is accessible via a SOAP service. The base URL is as per the SOAP Services tab, as described above. The entrypoint is the service discovery WSDL, which is found at '/Services'. So for the test instance created above, the full URL is:

The first service listed is the system service. This allows a SOAP consumer to get a list of companies in the database (NAV supports multiple companies). Each company name can then be used to adapt the SOAP URL to get access to the information about that specific company (described later). If no company is specified and the above URLs are used, the default company is used.

The remaining services listed represent 'pages', which is how NAV organises and displays data. As you can see, pages are used to represent such things as customers ('/Page/Customer'), products ('/Page/Item') and orders ('/Page/SalesOrder'). Each page has a consistent set of basic operations that allow you to interact with the data in a CRUD like fashion.

The main things to note here are that we are leveraging the inbuilt support for basic authentication provided by SoapClient. This is done by providing the login credentials to the constructor. Additionally, the script requires SOAP version 1.1 in order to work correctly.

In the test install there is in fact only one company, which is 'CRONUS UK Ltd.'. This also happens to be the default company. However, if it wasn’t the default, the specific discovery WSDL would be derived using the name as follows:

The main things to observe here are that the specific 'Cronus UK Ltd' company URL has been used, rather than the default URL and that the setSize option has been used to restrict the result to just one record. Additionally, the output has been significantly redacted for the sake of brevity as the result returns every field associated with the record, of which there are a lot.

However, this abundance of information is actually very useful as any of the fields can be used to apply a filter, meaning that once one record is exposed it is easy for a developer to craft the request they need without continually consulting API documentation. Filters are applied to a specified field using a specialised criteria syntax.

The following script adds a filter into the request to restrict the result to orders on or after a certain date. Note: the dates in the default instance seem to all be set in the future.

The criteria syntax in the filter is relatively self explanatory - it is looking for orders with an order date on or after 11/01/2018. One potential pitfall is the date format required, which needs to be mmddyyyy.

The following script uses a combined filter to find customers with a name beginning and ending in the letters 'S' and 's' respectively:

The criteria syntax in the filter combines two criteria using an ampersand:'S*' and '*s'. These in turn use the wildcard criteria syntax. This could also be written as '@s*&*s' using an asperand to denote case insensitivity.

Filters can also be combined by creating a multi dimensional array as follows:

However, this has the effect of looking for customers with a name beginning or ending with 'S' and 's' respectively, which can be achieved in a single expression – 'S*|*s', which uses the pipe as an or operator.

Creating records

Creating records is quite a straightforward process using the Create SOAP operation. There are no minimum data requirements, so a call to Create with no data supplied will just create a bare record in Dynamics NAV with a unique record Key and No field, as demonstrated by the following script:

Here we see the supplied company name and address information reflected in the customer record that is created.

Updating records

Updating records is also quite a straightforward process using the Update SOAP operation. In order to identify the correct record the Key field must be supplied, along with the field or fields that need updating. There's no need to re-upload the entire record; any fields not supplied will remain as they are, as demonstrated by the following script:

Here we use the customer record created above and can see that just the Address field of the record is updated. Notice also that the latter section of the Key has changed after the update from 4449110 to 4449540. This revision indicator is important as as any attempt to perform a record update or delete now requires the revised Key, or the action will be rejected.

Deleting records

Deleting records follows a similar pattern to above, using the Delete SOAP operation. However, as mentioned above, the latest Key revision is required to perform the action.

Hopefully this overview provides you with enough information to allow you to get started with an Dynamics NAV integration project.

The Azure platform makes it easy to create a application to investigate and test against, breaking down the barriers that proprietary platforms and software usually present to open source users.

The SOAP service provides a uniform way to interact with the 'pages' inside the NAV system, with filters allowing a SOAP client to query data in a flexible way and create / update / delete operations allowing the data to be easily manipulated.

Links

About us

Inviqa is a technology partner and consultant trusted by leading brands to meet strategic goals through digital solutions. A specialist in ecommerce, content solutions, and custom software development, we help pioneering businesses engage, convert, and retain their audiences.