If you’re not using our AX 2012 R3 demo image on Azure by now… well, you should be. There is an excellent guide on getting your Azure account linked with Lifcecycle Services so you can deploy the demo virtual machine: Deploy Microsoft Dynamics AX on Azure [AX 2012].
If you are using the Demo VM for the purpose of evaluating AX for Retail you may find yourself limited by having to do everything on a single machine via RDP client. Luckily it is very easy to open Azure virtual machines for external access. However, because two of the main Retail Components require secure socket layer (SSL) communications, there are a few not-so-pleasant steps you need to take in order to get things talking to each other. These instructions should get you through it.
Assuming you were able to get the Demo VM up and running, go to your Azure Management Portal and select your virtual machine. On the right-hand side of the dashboard, note the DNS name of your server. We will use this for most of the following steps, starting with generating a new self-signed certificate.
Inside the Demo VM, open an elevated Visual Studio command prompt and execute a makecert command to generate a new certificate:
makecert -sky exchange -r -n "cn=ax2012r3-demo-ax2012-r3demo-ffffffffff.cloudapp.net" -len 2048 -ss MY -sr LocalMachine
Note the long name for the server ("cn=…"). This is the publicly-facing DNS name noted above and will be what all external machines use to communicate with your specific instance of the Demo VM.
You can verify that the certificate was properly created by launching IIS Manager and opening Server Certificates. You should see a new certificate for your publicly-facing DNS name:
To test the certificate we will first just assign it to the default site. Open IIS Manager in the Demo VM and go to the Default Web Site. Right-click and select Edit Bindings. Select the https binding and click Edit. Select the new SSL Certificate that you created earlier. You will have to reset IIS for it to take effect.
Back in Azure Management Portal click on Endpoints. Endpoints are how you open your private virtual network to the world (see How to Set Up Endpoints to a Virtual Machine). If you’ve ever done NAT port forwarding on your home router it is pretty much the same concept. Create two new endpoints for the VM: HTTP, TCP, port 80 and HTTPS, TCP, port 443.
Install the Cert on the External Machine
On your external machine launch an elevated (I’ll explain why in a moment) instance of Internet Explorer and navigate to both the HTTP and HTTPS version of the default web site to make sure your endpoint is working:
The HTTP version of the site should get you to the IIS default page with no errors:
The HTTPS (port 443) version, however, should give you a certificate error, specifically a warning that the certificate presented did not come from a trusted authority:
Because we are in an elevated Internet Explorer we can install the certificate to our Trusted Authority store directly from IE. Go ahead and select Continue to this website (not recommended) which will get you to the IIS default page again, this time with a prominent warning about the certificate:
Click on Certificate error in the address window. On the Untrusted Certificate window select View Certificates. You should then have the option to install the certificate. If you don’t see the Install Certificate button it means you did not run Internet Explorer elevated (As Administrator).
On the first page of the Certificate Import Wizard make sure to select Local Machine and then on the second page browse to and place the certificate in the Trusted Root Certification Authorities store. Click the Finish button on the last page to import the certificate.
Open a new instance of IE and try the HTTPS version again. You should be able to get to the site without any certificate errors. Getting past these certificate errors at this point is absolutely critical for getting Async Client and Real-time Server to work properly; while you can fake your way through certificate errors in a Web browser, services running behind the scenes cannot handle the issues.
Update CDX Async Server
Now that we’ve proven that our certificate works for the default web site, we need to change the certificate on CDX Async Server so that it can be hit from external machines. These will be the same steps as above, just for a different web site. In the IIS Manger right-click on the AsyncServerSite and select Edit Bindings. Note that the https binding for the Async Server is using port 8303. Select the https binding and click Edit and then select the new certificate from the drop-down. Close all of the windows and then restart IIS for the updated binding to take effect.
Back in the Azure Management Portal go to Endpoints and create a new endpoint for the CDX Async Server Web service: port 8303.
We also need to create a firewall exception for port 8303. On the Demo VM, launch Windows Firewall with Advanced Security. Right-click on Inbound Rules and go through the wizard to create a new incoming rule of type Port. Leave the port type as TCP and enter a 8303 in the Specific local ports box. Allow the connection and apply the rule for Domain, Private, and Public. Use the name Async Server and click Finish to create the rule.
If everything is set up properly you should be able test the Async Server from your external machine using the standard test URL:
Again, if you still have certificate errors at this point, Async Client will not work properly, so double-check the above steps before you try to install Async Client.
Speaking of Async Client… you may have noticed that when we changed the certificate for Async Server that we broke all of the Async Client running on the demo VM. We will come back to those and fix them later.
Install CDX Async Client
Now that we have test access to Async Server from a Web browser on the external machine we can install Async Client. Before doing so we need to set up things in AX.
Go to Retail > Setup > Retail Scheduler > Channel Integration > Channel database and create a new Channel database. Give it the ID "External" and assign to the existing data group ("Data group"). Use "external" for both the User name and password. Assign an unused Retail channel to the new Database ID (I chose Atlanta):
After adding the new Channel database, make sure to synchronize your changes to the Message Database by going to Retail > Setup > Parameters > Retail scheduler parameters and running the Sync metadata process. This is a step that is easy to miss.
On your external machine launch the Dynamics AX R3 installer and select these components: Retail POS, Commerce Data Exchange Async Client and Retail Channel Configuration Utility.
On the Configure Async Client window use the URL you tested above, removing the "/UploadService.svc" portion: https://ax2012r3-demo-ax2012-r3demo-ffffffffff.cloudapp.net:8303/AsyncServer. Use the three pieces of information that you used when you created Channel Database in AX: "External", "external" and "external". When you click the Test Connection button, the installer will validate that you can connect to the Async Server with those credentials:
Finally, select a local user or domain user that the Windows Service will run under on the external machine. The credentials you enter for the Async Client service have nothing to do with the users from your Contoso domain in your Demo VM. This user must have access the local SQL Server that will be hosting the channel database and the local message database. Think of your external machine as the store server which will likely not be joined to your headquarters domain.
On the Select or specify a database to use with Async Client screen select the local SQL server that this Async Client will be using. The message database that you use will automatically be created by the Async Client installer. The channel database will not get created by the installer, but it should match the database name that we will create later. We will use "AtlantaPOS" for this database name.
Finish the installation process to install the three components.
Before the Async Client will actually work we need to create a valid channel database for it to write data to. To do this, launch the Retail Channel Configuration Utility on your external machine and select the Create channel database option. Enter your SQL server name and the database you want to create: AtlantaPOS. Click Apply to start the process:
Run Scheduler Jobs to Populate Channel Database
Before replicating data, there are a few changes to the demo data that need to be made for our Atlanta POS to work properly. We should take care of those before the initial data replication:
- Retail > Common > Retail Channels. Open the Atlanta channel and go to the Screen layout fast tab. Add FAB-CSH-ST to the list.
- Retail > Setup > Retail scheduler > Channel integration > Real-time Service profiles. Unmark the Commerce Data Exchange: Real-time Service staff checkbox for the JBB profile.
- Retail > Setup > POS > Profiles > Hardware Profiles. Select the HW001 profile and expand the EFT service fast tab. Change the EFT service to Payment Connector > Dynamics Payment Connector and close the window. You can ignore the errors about the Windows Live ID and the Service Account ID. Note: as an alternative you can copy the Connectors\Microsoft.Dynamics.Retail.TestConnector.dll file from the VM to your local POS installation.
Go to the Channel database window and run a full distribution schedule for the External database ID that we created. I usually like to test with just a small schedule first, so select the 1000 (Currency) schedule and then click OK to run it directly:
If the job ran successfully you can navigate to the CDX files directory (C:\DemoFiles\Retail\CDX\Download\5637144576) and verify that an RPF file was generated.
Now that our Async Client has a package to download, go to Windows Services on the external machine and start the Microsoft Dynamics AX for Retail Commerce Data Exchange Async Client service (look for the longest name in the list) to initiate the download process. If everything is working properly you can run a query in the AtlantaPOS database and verify that data was replicated:
If the 1000 (Currency) schedule ran properly, go back and do a Full data sync on the 9999 (All jobs) schedule. This will take a while for AX to generate all of the RPF files and for Async Client to download them all.
Configure POS and Log In
After all data has populated in the AtlantaPOS database you are ready configure POS and log in. Open the Retail Channel Configuration Utility again and this time enter information about the register for our Atlanta store:
Launch the POS application and log in as user 000137 with password of 123. Open a new shift using any cash drawer. Add item 0012 to the transaction and finalize the transaction with Exact tender:
Since the Async Client is set to process both upload jobs and download jobs every sixty seconds, it won’t take long for the transactions to start to be uploaded to the Async Server (remember that in R3 you do not have to wait for a P-job to be executed for data to be uploaded!).
On the Demo VM go to the c:\demofiles\Retail\CDX\Upload directory and verify that the subfolder “External” has been created. If you open the subfolder you should see some RPF files:
At this point you can run the P-job and pull the records into the Dynamics AX database.
Configure Real-time Service
Now that both Async Client and POS are working properly on the external machine, the next step is getting Real-time Service working. The problem here is similar: things won’t work properly until the certificate situation is resolved. The solution is also the same: update the certificate on the Web service and tell the POS to use the new URL matching that certificate (via the Real-time Service profile). Here are the steps (slightly abbreviated this time):
- On the VM go back to the IIS Manager and this time open the RealTimeServiceWebSite site. Right-click > Edit bindings and change the https binding to use the same certificate we created earlier.
- Find the thumbprint for the new certificate and then update Web.config file with the thumbprint of the ner certificate. The web.config is located at C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Real-time Services\6.3. Make sure to get rid of spaces and that pesky hidden character at the beginning of the thumbprint if you are copying and pasting.
- Add a firewall exception for port 84 on the Demo VM.
- Create an Azure Endpoint for port 84.
- Reset IIS and navigate to the Real-time Service URL both on the Demo VM and the external machine. Make sure you don’t get certificate errors: https://ax2012r3-demo-ax2012-r3demo-ffffffffff.cloudapp.net:84/RealtimeService/Service.svc
- Go to Retail > Setup > Retail scheduler > Channel integration > Real-time Service profile and make the following changes to the JBB profile: Protocol = "https", Server and Common name = "ax2012r3-demo-ax2012-r3demo-ffffffffff.cloudapp.net" (your public DNS for the Azure VM), Port = 84.
Push down your data changes (scheduler job 1070 will work) and restart the POS on your external machine. Test the Real-time Service by going to Tasks > Inventory > Inventory lookup and looking up item 0012. The first call to the Real-time Service might take a little while, but if things work you will eventually get inventory levels for the item at your locations:
If the call to the Real-time Service doesn’t succeed, check the RetailTransactionServiceProfile table in your AtlantaPOS database and make sure the changes you made to the JBB profile replicated. Also check the Event Log on both machines to see if there are any clues on the failure.
Fixing the Async Clients and Real-time Service on the Demo VM
Now things should be working smoothly communicating with your external machine. However, in the process we broke some things in the Demo VM. Luckily these things aren’t too difficult to fix.
To fix the Async Clients go to each Package folder under C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async and launch the AsyncClientConfigurationUtility. Change the Server address to the new externally-facing DNS name. For instance, under the Package-Houston folder my window would look like this:
Restart each Async Client service for the changes to take effect.
The Real-time Service is even easier to fix: the changes that were made to the JBB profile just need to be replicated to all of the channel databases. To do this, go to Retail > Setup > Retail scheduler > Channel integration > Channel data group and do a full data sync of schedule 1070 on the "Data group" group. If all of your Async Clients were updated in the step above the changes will roll down and all of the channels will begin using your Cloudapp.Net address for communication. You can test this by doing the same Inventory Lookup on a POS in the Demo VM.
This will take care of the two main components that are most affected by certificates. If you are using the online store you may have to make similar changes. Retail Server and MPOS (beta) should not be an issue as you should be able to just use non-secure HTTP for communication. You may have to open some firewall ports and create endpoints, but the steps for the other components should be similar.
Hopefully this will open up your demos to new possibilities and allow you to show off different form factors and peripherals in the Retail R3 environment. As always, feel free to give me a shout in the comments if you have any questions or corrections to make.
Also, don’t forget to turn off your Azure Demo VM if you’re not using it… if you only have a MSDN monthly allowance it will burn through that pretty quickly!
Many thanks to Brian Storie for assistance with the steps in this article.