AX for Retail 2012 R2: Installing the Real-time Service
[Note: Please see the companion article for Troubleshooting Tips for the Real-time Service.]
Possibly the biggest change with AX for Retail 2012 R2 is the re-architecting of the Retail Transaction Service.
The first thing you will notice is that the name has been changed: Retail Transaction Service is now Commerce Data Exchange: Real-time Service. Store Connect was also renamed to Commerce Data Exchange: Synch Service. While it may take some getting used to, these new names are much better descriptors of their actual functionality.
Along with the name change, Real-time Service has fundamentally changed from a Windows Service to an IIS Web Service. As mentioned in a previous article, the service itself really doesn't do a whole lot functionally: it acts as a traffic handler between the POS and the Headquarters to share real-time information. All actual logic is written in X++ code hosted in the AOS via the .Net Business Connector. This part hasn’t changed.
This architecture change means that installation and configuration has changed quite a bit. This article will go through these steps to get you up and running with the new Real-time Service:
The Real-time Service itself is still a component of the Microsoft Dynamics AX installer and can be found under Retail Components > Commerce Data Exchange > Real-time Service:
The Real-time Service needs to reside on a Windows server that has Internet Information Services (IIS) installed and configured. It also needs to communicate to an AOS, so the .Net Business Connector component also needs to be installed. You will notice that the Retail Salt Utility also gets installed with the Real-time Service.
Even though the Real-time Service is a relatively light-weight component, in a production environment it is good idea to install it on a non-AOS server.
One thing that may be a bit confusing is the fact that while the Real-time Service is now a Web service, it has nothing to do with the existing Web services on IIS component also found in the AX installer. Those Web services are used for other purposes, most notably allowing other applications to integrate with Dynamics AX. You do not need to install that component as part of the Real-time Service installation.
Upon successful installation you should get three folders under the Real-time Services folder (C:\Program Files (x86)\Microsoft Dynamics AX\60\Commerce Data Exchange\Real-time Services):
5.1 and 6.1 are there because AX for Retail 2012 R2 now has "N-1" support for previous versions of the POS. These versions of the Real-time Service are still implemented as a Windows Service and are configured just like Retail Transaction Service was configured in previous versions.
Since we are focusing on AX for Retail R2, we'll leave that topic for another article.
Adding the SSL certificate to the Windows server
Because the Real-time Service is now a Web service, an SSL certificate is required for communication between the POS and the Real-time Service. Here are three options for installing the certificate:
Requesting and Installing a certificate from IIS Management Console
For a production environment you will purchase and install an official certificate. This is the same thing you would do for implementing SSL on any externally-facing web site. Instructions can be found here: http://technet.microsoft.com/en-us/library/cc731977(v=ws.10).aspx
Using Powershell to install a certificate
If you already have received a certificate from your provider or are migrating one from a different server, you may have the file in a PFX format. If this is the case, you can use the provided Powershell script to install it:
Creating a self-signed test certificate
If you want to get Real-time Service up and running in a test environment, you may wish to create your own self-signed test certificate. This is a good step-by-step walkthrough of how to do this: http://weblogs.asp.net/scottgu/archive/2007/04/06/tip-trick-enabling-ssl-on-iis7-using-self-signed-certificates.aspx
Finding the Certificate Thumbprint and Common Name
To verify that the certificate was installed correctly, we can navigate to it in the Internet Information Services (IIS) management console and grab its thumbprint. Open the IIS management console and select the local server in the navigation tree. Double-click on Server Certificates to open the list of certificates that are installed on the server:
You should see your certificate in the list:
Double-click your certificate to open it. navigate to the Details tab and then down to the Thumbprint property. Copy the 20-digit (40 characters) hex string to your clipboard - we will need it later.
Also, while on the Details tab, take note of the "Subject" property. This is the Common Name which will be used when creating the Real-time Service profile in Headquarters.
Creating the Real-time Service Web service
Creation of the Real-time Service itself is done with another Powershell script. In the same folder execute the InstallCommerceDataExchangeRealtimeService.ps1 script. The script will prompt for a number of parameters:
The script will do some pre-requisition checks and then if all goes well, it will create the site:
If something fails, you will need to perform an uninstall before attempting again. Run the UninstallCommerceDataExchangeRealtimeService.ps1 script to do this. This script takes only one parameter:
Testing the Real-time Service Web service
If the Powershell script successfully installed the Web service, you can open IIS Management Console to validate. First, navigate to Application Pools…
… and then to Sites:
After confirming that they were successfully created, you can test the Web service via a Web browser. Right-click on the CommerceDataExchangeRealtimeService application and select Switch to Content View:
You should see Service.svc in the list. Right-click on it and select Browse:
If everything is working correctly, your Web browser should launch and you will see a screen like the following:
Edit: The following step is not necessary. If the Real-time Services resides on a non-AOS machine, it will use the AOS that the .Net Business Connector is configured to use.
If you are running the Real-time Service on a non-AOS machine (and hopefully you are!) then you need to perform one additional step before the Web service will work. By default, the service attempts to use the default AOS on the local machine. Pointing it to an AOS is similar to the steps in previous versions of the Retail Transaction Service.
In a text editor, open the Web.config for the Web service. By default this is located at C:\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService.
Add the correct AOS information to the ObjectServer key:
Now that we have confirmed the Real-time Service Web service is working correctly, we need to configure it in Headquarters and push it down to the POS.
In Dynamics AX navigate to Retail > Setup > Retail scheduler > Channel integration > Real-time Service profiles. Create a new profile with the following information:
As in previous versions, the Real-time Service profile is assigned to a specific register. Navigate to Retail > Setup > POS > POS registers and open a register. The profile you created should be assigned under General > Profiles:
After assigning the Real-time Service profile to a register, the changes can be pushed to the POS database by running the N-1090 job.
Testing the Real-time Service from the POS
The easiest way to test that the Real-time Service is working correctly is to perform an Inventory Lookup from the POS. Launch the POS and navigate to the Inventory Lookup button (in the sample layout this is under Cashier Tasks). In the Inventory Lookup form, enter a valid Item ID and press enter. If the POS is able to read information from Headquarters via the Real-time Service, you will see the item information fill in:
Wrap-up
You can tell by the number screenshots alone that installing the Real-time Service is more complicated in AX for Retail 2012 R2. There are also lots of opportunities for things to not work correctly the first time around. I will address some of the more common ones in my next article. In the meantime, if you run into difficulties, please create a support incident and we can help get you past any obstacles.
Edits:
Possibly the biggest change with AX for Retail 2012 R2 is the re-architecting of the Retail Transaction Service.
The first thing you will notice is that the name has been changed: Retail Transaction Service is now Commerce Data Exchange: Real-time Service. Store Connect was also renamed to Commerce Data Exchange: Synch Service. While it may take some getting used to, these new names are much better descriptors of their actual functionality.
Along with the name change, Real-time Service has fundamentally changed from a Windows Service to an IIS Web Service. As mentioned in a previous article, the service itself really doesn't do a whole lot functionally: it acts as a traffic handler between the POS and the Headquarters to share real-time information. All actual logic is written in X++ code hosted in the AOS via the .Net Business Connector. This part hasn’t changed.
This architecture change means that installation and configuration has changed quite a bit. This article will go through these steps to get you up and running with the new Real-time Service:
- Installing the Real-time Service
- Adding the SSL certificate to the Windows server
- Finding the certificate thumbprint and common name
- Creating the Real-time Service Web site in IIS
- Configuring the Real-time Service in Retail Headquarters
- Testing the Real-time Service from the POS
The Real-time Service itself is still a component of the Microsoft Dynamics AX installer and can be found under Retail Components > Commerce Data Exchange > Real-time Service:
The Real-time Service needs to reside on a Windows server that has Internet Information Services (IIS) installed and configured. It also needs to communicate to an AOS, so the .Net Business Connector component also needs to be installed. You will notice that the Retail Salt Utility also gets installed with the Real-time Service.
Even though the Real-time Service is a relatively light-weight component, in a production environment it is good idea to install it on a non-AOS server.
One thing that may be a bit confusing is the fact that while the Real-time Service is now a Web service, it has nothing to do with the existing Web services on IIS component also found in the AX installer. Those Web services are used for other purposes, most notably allowing other applications to integrate with Dynamics AX. You do not need to install that component as part of the Real-time Service installation.
Upon successful installation you should get three folders under the Real-time Services folder (C:\Program Files (x86)\Microsoft Dynamics AX\60\Commerce Data Exchange\Real-time Services):
5.1 and 6.1 are there because AX for Retail 2012 R2 now has "N-1" support for previous versions of the POS. These versions of the Real-time Service are still implemented as a Windows Service and are configured just like Retail Transaction Service was configured in previous versions.
Since we are focusing on AX for Retail R2, we'll leave that topic for another article.
Adding the SSL certificate to the Windows server
Because the Real-time Service is now a Web service, an SSL certificate is required for communication between the POS and the Real-time Service. Here are three options for installing the certificate:
Requesting and Installing a certificate from IIS Management Console
For a production environment you will purchase and install an official certificate. This is the same thing you would do for implementing SSL on any externally-facing web site. Instructions can be found here: http://technet.microsoft.com/en-us/library/cc731977(v=ws.10).aspx
Using Powershell to install a certificate
If you already have received a certificate from your provider or are migrating one from a different server, you may have the file in a PFX format. If this is the case, you can use the provided Powershell script to install it:
- Open an elevated Powershell prompt:
- Navigate to the "Sample Deployment Scripts" folder in the Real-time Services directory and run the InstallServerCertificate.ps1 script.
- When prompted, enter the path to your PFX file and the private key password.
- If all is successful you will get a message that the certificate was successfully installed:
Creating a self-signed test certificate
If you want to get Real-time Service up and running in a test environment, you may wish to create your own self-signed test certificate. This is a good step-by-step walkthrough of how to do this: http://weblogs.asp.net/scottgu/archive/2007/04/06/tip-trick-enabling-ssl-on-iis7-using-self-signed-certificates.aspx
Finding the Certificate Thumbprint and Common Name
To verify that the certificate was installed correctly, we can navigate to it in the Internet Information Services (IIS) management console and grab its thumbprint. Open the IIS management console and select the local server in the navigation tree. Double-click on Server Certificates to open the list of certificates that are installed on the server:
You should see your certificate in the list:
Double-click your certificate to open it. navigate to the Details tab and then down to the Thumbprint property. Copy the 20-digit (40 characters) hex string to your clipboard - we will need it later.
Also, while on the Details tab, take note of the "Subject" property. This is the Common Name which will be used when creating the Real-time Service profile in Headquarters.
Creating the Real-time Service Web service
Creation of the Real-time Service itself is done with another Powershell script. In the same folder execute the InstallCommerceDataExchangeRealtimeService.ps1 script. The script will prompt for a number of parameters:
UserAccount: The user account to run the service as (domain\user). This is the account that will log in to Dynamics AX via the .Net Business Connector. This is the same user that you would have used for Windows service in previous versions of Retail Transaction Service.
Password: The password for the user account.
ServiceBinarySourceFolder: The service binary folder. This is the location of the DLLs that comprise the Real-time Service. By default this directory is C:\Program Files (x86)\Microsoft Dynamics AX\60\Commerce Data Exchange\Real-time Services\6.2\. These files will be copied to the Web site that is created. Tip: Do not add the 'bin' subfolder at the end of this string.
ServerCertificateThumbprint: The server certificate thumbprint noted above. You should remove the spaces from the 40-character string.
The script will do some pre-requisition checks and then if all goes well, it will create the site:
If something fails, you will need to perform an uninstall before attempting again. Run the UninstallCommerceDataExchangeRealtimeService.ps1 script to do this. This script takes only one parameter:
ServiceInstallFolder - This is the destination location that the source binary files were copied to. By default this is C:\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService.
Testing the Real-time Service Web service
If the Powershell script successfully installed the Web service, you can open IIS Management Console to validate. First, navigate to Application Pools…
… and then to Sites:
After confirming that they were successfully created, you can test the Web service via a Web browser. Right-click on the CommerceDataExchangeRealtimeService application and select Switch to Content View:
You should see Service.svc in the list. Right-click on it and select Browse:
If everything is working correctly, your Web browser should launch and you will see a screen like the following:
Edit: The following step is not necessary. If the Real-time Services resides on a non-AOS machine, it will use the AOS that the .Net Business Connector is configured to use.
If you are running the Real-time Service on a non-AOS machine (and hopefully you are!) then you need to perform one additional step before the Web service will work. By default, the service attempts to use the default AOS on the local machine. Pointing it to an AOS is similar to the steps in previous versions of the Retail Transaction Service.
In a text editor, open the Web.config for the Web service. By default this is located at C:\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService.
Add the correct AOS information to the ObjectServer key:
<add key="ObjectServer" value="MicrosoftDynamicsAX@DAX2012:2712" />Configuring the Real-time Service in Retail Headquarters
Now that we have confirmed the Real-time Service Web service is working correctly, we need to configure it in Headquarters and push it down to the POS.
In Dynamics AX navigate to Retail > Setup > Retail scheduler > Channel integration > Real-time Service profiles. Create a new profile with the following information:
Server: The name of the machine hosting the Web service. This must be a name that can be resolved to an IP address. Keep in mind that many POS machines will be connecting via the Internet, so it must be an externally-available server.
Port: The port of the Web service. By default, this value should be 808 for net.tcp binding. A firewall exception should be created to allow the POS machines to communicate via this port.
Protocol: While we tested the Web service using http binding, it is recommended that net.tcp binding be used here.
Web application name: This is the name of the web application that hosts Real-time Service. By default it is CommerceDataExchangeRealtimeService.
Common Name: This is used to identify the certificate that is being used for secure communications. It should match the "Subject" property of the certificate (see the "Finding the Thumbprint for the Certificate" section above).
Passphrase: This is the passphrase that the POS application will use to authenticate to the Real-time Service. Since this is encrypted and stored in a table that gets replicated to the POS database, you can enter any value here as long as it is non-blank.
Language: The language that will be used by the Real-time service.
Real-time Service version: If you will be using the Real-time Service with a previous version of AX for Retail POS (AX 2009 or AX 2012 Feature Pack) select the version from the drop-down.
As in previous versions, the Real-time Service profile is assigned to a specific register. Navigate to Retail > Setup > POS > POS registers and open a register. The profile you created should be assigned under General > Profiles:
After assigning the Real-time Service profile to a register, the changes can be pushed to the POS database by running the N-1090 job.
Testing the Real-time Service from the POS
The easiest way to test that the Real-time Service is working correctly is to perform an Inventory Lookup from the POS. Launch the POS and navigate to the Inventory Lookup button (in the sample layout this is under Cashier Tasks). In the Inventory Lookup form, enter a valid Item ID and press enter. If the POS is able to read information from Headquarters via the Real-time Service, you will see the item information fill in:
Wrap-up
You can tell by the number screenshots alone that installing the Real-time Service is more complicated in AX for Retail 2012 R2. There are also lots of opportunities for things to not work correctly the first time around. I will address some of the more common ones in my next article. In the meantime, if you run into difficulties, please create a support incident and we can help get you past any obstacles.
Edits:
- December 27, 2012: Easier steps for viewing server certificates and browsing to the Web Service. Removed section on configuring service to point to a different AOS.
Facebook
1 comments:
whoah this blog is fantastic i love reading your posts.
Keep up the good work! You realize, a lot of people are looking round for this information,
you can aid them greatly.
Post a Comment