How to Setup and Configure Commerce Data Exchange: Real-time Service

1. Setup Commerce Data Exchange: Retail-time Service

1.1 Preparations Pre-requisites for installing Commerce Data Exchange: Real-time Service: Operating System: Windows Server OS, or Windows client OS with Internet Information Services (IIS), IIS PowerShell snap-in and Windows Process Activation Service installed. SSL Certificate: Obtain an SSL certificate with data encryption capability. You can get the certificate from a commercial certification authority (strongly recommended).

Obtaining an SSL Certificate

In a production environment, you should obtain an SSL certificate from a certification authority. Some large organizations may have their own certification authorities, and other organizations can request a certificate from a third-party organization. In a test or development environment, you can create your own self-signed certificate.
To create a self-signed SSL certificate

1. To open Internet Information Services (IIS) Manager and do one of the following:
o

In Windows 7, on the Start menu, in the Search Programs and Files box, type inetmgr, and then press Enter. In Windows Server 2008 R2, on the Start menu, choose Administrative Tools, and then choose Internet Information Service (IIS) Manager.

2. In the Connections pane, choose the top-level node for the server. 3. On the Home page, under IIS, choose Server Certificates, and then in the Actions pane, choose Open Feature. 4. On the Server Certificates page, choose Create Self-Signed Certificate. 5. In the Specify Friendly Name dialog box, type a brief name for the certificate, and then choose the OK button. The new certificate appears on the Server Certificate page.

Real-time service is a standard WCF service that still uses BC.net to connect to AX (no AIF involved). For deployment it is recommended to use a proper SSL certificate from a public certificate authority (such as VeriSign http://www.verisign.com/). This certificate is installed in IIS under server certificates. IIS allows you to create a self-

signed certificate for a test environment (http://weblogs.asp.net/scottgu/archive/2007/04/06/tip-trick-enabling-ssl-oniis7-using-self-signed-certificates.aspx).

Commerce Data Exchange: Retail-time Service MSI installed. You should see the binaries installed at %ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time Services\6.2 An AX user account setup for the real-time service to use. The user must have necessary privilege in AX to perform all the retail tasks.

1.2 Install server certificate Goal: Steps: Note: Depending on how you obtain the SSL certificate, you may install the certificate through: A) Complete certificate request in IIS B) Import certificate from pfx file If you are using option A), then the certificate has already been installed to the certificate store. You can skip step 1. 0. Open Certificate Manager with Administrator account. a. Open the Microsoft Management Console with Administrator privilege (Start -> mmc.exe, right click, and choose run as Administrator). b. Click File -> Add/Remove Snap-in, and choose Certificates. Choose Local Machine account. Install SSL certificate on the server machine, and make it available to the AX user. Obtain the server certificate thumbprint for transaction service install purpose.

c. You should see the certificate manager console.

1. Install the SSL certificate in the local machine personal certificate store. a. In the certificate manager console, right click on Personal, and choose All Tasks -> Import. The certificate import wizard will show up.

b. Follow the certificate import wizard to finish importing the certificate. Make sure you import the private key, which is needed for channel encryption. 2. Configure the private key to make it available to the AX user account. a. Browse and locate the server certificate under Personal -> Certificates. Right click on the certificate, and choose All Tasks -> Manage private keys. The certificate security window should show up.

b. In the certificate security window, add the AX user account to the list, and give read access to the user.

3. Obtain the certificates thumbprint.

a. Browse and locate the server certificate under Personal -> Certificates. Double click the certificate to open the certificate property window.

b. Switch to the details tab, and choose thumbprint.

c. The thumbprint is the 20 byte array displayed. Please copy the value out and remove the spaces in between. For example, the thumbprint for the certificate in the above image is: 6b3b49dfad6100a47ef623c8e471c567bf052530. We need the thumbprint for the service install. 1.3 Install Real-time Service Steps: 1. Open a PowerShell window with administrator privilege, and set execution policy to remote-signed. (or unrestricted if you are using an unsigned script)

2. Change directory to the sample deployment scripts folder.

It is the Sample Deployment Scripts folder under the real-time service binary folder, where you can see a few PowerShell scripts. For the default MSI install, it is %ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time Services\6.2\Sample Deployment Scripts. 3. Run PowerShell scripts to install the Real-time Service. >./InstallCommerceDataExchangeRealtimeService.ps1. The install scripts will prompt you for a few mandatory parameters. a. User account: The domain\user for the domain account for the Real-time Service. Note this account needs to be an AX account that has sufficient privilege to perform all the necessary retail tasks. b. Password: The password for the domain account. c. Service binary source folder path: The service binary folder, where the web.config and service file is. For the default MSI install, it should be something like %ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time Services\6.2. d. Server certificate thumbprint: The thumbprint for the server certificate. See Section 1.2 Step 3 on how to obtain the certificate thumbprint.

The install scripts will then install the Real-time Service with all the required dependency components. If the install completed successfully, you will see output like this:

4. Test the service install from browser. You can do a smoke test of the service install by opening the link to the service in the browser: http://localhost:9080/CommerceDataExchangeRealtimeService/service.svc. It should show the WCF medata exchange help page if the service has been configured correctly.

1.4 Uninstall Real-time Service In the rare case you need to uninstall Real-time service, please use the following steps: 1. Open a PowerShell window with administrator privilege, and set execution policy to remote-signed. (or unrestricted if you are using an unsigned script)

2. Change directory to the sample deployment scripts folder. It is the Sample Deployment Scripts folder under the real-time service binary folder, where you can see a few PowerShell scripts. For the default MSI install, it is %ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time Services\6.2\Sample Deployment Scripts. 5. Run PowerShell scripts to uninstall the Real-time Service. >./UninstallCommerceDataExchangeRealtimeService.ps1. The script will ask for the service install folder. Please provide the path to the folder where web.config is located. The default location is %SystemDrive%\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService.

2. Configure Commerce Data Exchange: Retail-time Service

2.1 Configure service profile The Real-time Service profile contains all the information for the clients to connect to the server. The service profile can be configured in AX. The AX control to configure the Real-time Service is located at <COMPANY>/Retail/Setup/Retail scheduler/Channel integration -> Real-time Service profiles.

The Real-time Service profile looks like this:

Server: the server host name Port: The port to use for the communication. For net.tcp, the default port is 808. For http, the default port is 9081. Protocol: The communication protocol. By default it is net.tcp, but we also support https. Note that in order to use Https, we need to change the server configuration (See next section for details). Web application name: The web application name for the real-time service. If you are using the default install script to install the service, the web app name should be CommerceDataExchangeRealTimeService. Common name: The server certificate common name (DNS). This is usually the domain name for the host (for example, contoso.com). The common name for this is TSServerCert Passphrase: The passphrase used to authenticate the client. Language: The language used to return error message from the Real-time service. Real-time Service version: The real-time service version to use. Please use the default (AX 2012 R2) unless you are working with N-1 support. 2.2 Change service settings The Real-time Service server settings can be tweaked by changing the web.config file. It is a standard WCF configuration file. You can find the file at %SYSTEMDRIVE%\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService\Web.config. Change logging level: The logging level is controlled at the system.diagnostics section. The default logging level is set to Warning for the trace log, and Error for the event log. Feel free to change them to Information if you need more extensive logging. The trace log is by default located in C:\Windows\Temp\RetailLogs\w3wp.exe.xml.
<system.diagnostics> <sources> <!-- this registers the listener with traces from a specific source --> <source name="RetailNetTracer" switchValue="Warning"> <listeners> <add name="RollingXmlWriterTraceListener" /> </listeners>

</source> <source name="RetailNetTracerEventLog" switchValue="Error"> <listeners> <add name="EventLogTraceListener" /> </listeners> </source> </sources> ... </system.diagnostics>

Change binding configuration: The default binding is netTcpBinding for the Real-time Service. WSHttp is also supported for https connections. Feel free to change the binding.
<services> <service behaviorConfiguration="ReleaseBehavior" name="Microsoft.Dynamics.Retail.TransactionServices.TransactionService"> <endpoint address="Common" binding="netTcpBinding" bindingConfiguration="StreamedTCPBinding" name="Common" contract="Microsoft.Dynamics.Retail.TransactionServices.Contracts.ITransactionService" /> ... </service> </services>

Note: If you need to change the binding configuration from Net.Tcp to WSHttp, please use the binding configuration provided in the config file, and update the Real-time service profile in AX. This ensures the client and server can work together.