Install Retail Server [AX 2012]

Updated: December 17, 2014

Applies To: Microsoft Dynamics AX 2012 R3

Retail Server provides services and business logic for Retail Modern POS (point of sale) clients. To deploy Retail Server on multiple computers in a cluster, you can run Setup on each computer or you can manually copy the web application to each computer. Alternatively, you can use Retail mass deployment toolkit with System Center Configuration Manager to deploy Retail Server from a central location. For more information, see Mass deploy Retail components by using System Center Configuration Manager.

This topic includes the following sections.

NoteNote

Retail Server is available only with Microsoft Dynamics AX 2012 R3.

  • Be aware that you do not have to install Retail Server in a domain. You can install it as part of a work group on a single computer.

  • Create a service account. This service account is used for the identity of the application pool for Retail Server. This account does not have to be a domain account. It can be a work group account. For more information, see Create service accounts.

  • On the computer where you plan to install this component, run the prerequisite validation utility to verify that system requirements have been met. For information about how to run the prerequisite validation utility, see Check prerequisites.

    For more information about the hardware and software requirements for Microsoft Dynamics AX, see the system requirements.

  • Because this component uses Secure Sockets Layer (SSL) encryption, you must install a server certificate that was issued by a trusted certification authority. (For test environments, you can create a self-signed certificate in IIS.) When you run Setup, you will need to enter the thumbprint for the certificate. To view the thumbprint in IIS Manager, double-click the certificate and click the Details tab.

Use this procedure to install Retail Server. If you install other Microsoft Dynamics AX components at the same time, the installation pages vary, depending on the components that you are installing.

  1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.

  2. Advance through the first wizard pages.

  3. If the Setup Support files have not yet been installed on this computer, the Select a file location page is displayed. The Setup Support files are required for installation. Provide a file location or accept the default location, and then click Next. On the Ready to install page, click Install.

  4. On the Select installation type page, click Custom installation, and then click Next.

  5. On the Select components page, select Retail Server, and then click Next.

  6. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

  7. On the Configure Retail Server page, enter the following information about the web site where Retail Server will run.

    • Configure Retail Server – On the Configure Retail Server page, select the check box to configure Retail Server by using Setup. If you clear this option, the application files are installed, but Retail Server is not configured. If you’re configuring Retail Server, enter the following information:

    • Application name – The name of an existing web application in your server environment or the name of an application that you want Setup to create.

    • Website name – The name of an existing web site in your server environment or the name of a site that you want Setup to create.

    • App pool name – The name of an existing web application pool in your server environment or the name of an application pool that you want Setup to create.

    • User name and Password – The credentials for the application pool identity. The user does not have to be a domain account. It can be a member of a work group on the local computer.

    • HTTP port and HTTPS port – You can specify any available ports. Verify that these ports are open in Windows firewall. Also, make a note of these port numbers. The port is used to create the URL for Retail Server in the format: https://<ServerName>:Port/<WebApplicationName>. This URL is required to activate Retail Modern POS devices that connect to Retail Server.

      ImportantImportant

      We strongly recommend that you use an HTTPS port for Retail Server.

      Caution noteCaution

      To avoid conflicts with the Default Web Site on the computer, we recommend that you do not use the default HTTPS port (443). A nonstandard port number also helps make the website more secure.

    • SSL certificate thumbprint – The thumbprint for your Secure Sockets Layer (SSL) encryption certificate.

  8. On the Select a database to use with Retail Server page, select an existing database. To create a new channel database you must install the Retail channel database component.

  9. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

  10. On the Ready to install page, click Install.

  11. After the installation is completed, click Finish to close the wizard.

Use this procedure to install Retail Server manually by using Windows PowerShell. Manual installations are often performed by businesses and organizations that automate deployments by using scripts.

Dn741428.collapse_all(en-us,AX.60).gifExtract installation files

Use Microsoft Dynamics AX Setup to extract the files that are needed for manual installation.

  1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.

  2. On the Select installation type page, click Custom installation, and then click Next.

  3. On the Select components page, select Retail Server, and then click Next.

  4. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

  5. On the Configure Retail Server page, clear the Configure Retail Server option.

  6. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

  7. On the Ready to install page, click Install.

  8. After the installation is completed, click Finish to close the wizard.

Dn741428.collapse_all(en-us,AX.60).gifConfigure settings in the rs-settings.xml file

After you extract the installation files by using Setup, you must configure settings in the rs-settings.xml file.

  1. Open the folder where the installation files are installed. By default, the files are located at C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Server\Tools.

  2. Create a copy of the rs-settings.xml file. We recommend that you do not change the original file.

  3. Open the rs-settings.xml file in Microsoft Visual Studio or a text editor, such as Notepad.

  4. Enter a value for the following parameters:

    Parameter

    What to enter

    Default value

    ChannelDatabaseServerName

    The name of the server that hosts the channel database. The script is case-sensitive. For example, value="DatabaseServer" />

    None

    ChannelDatabaseServerNamedInstanceName

    The name of the SQL Server instance that hosts the channel database. The format for a SQL Server instance name is either the server name or the full instance name. For example, valid names are "localhost", "localhost\instance2", "server1", and "server1\instance2”.

    None

    ChannelDatabaseName

    The name of the channel database.

    None

    RetailServerWebAppPoolName

    The name of an existing web application or the name of an application that you want Setup to create.

    RetailServerAppPool

    RetailServerWebSiteName

    The name of an existing web site or the name of a site that you want Setup to create.

    RetailServerWebsite

    RetailServerWebSiteHttpPort

    You can specify any available port. Verify that the port is open in Windows firewall. Also, note the port number. The port is used to create the URL for Retail Server in the format: https://<server name>:port/<web application name>. This URL is required to activate Retail Modern POS devices that connect to Retail Server.

    None

    RetailServerWebSiteHttpsPort

    You can specify any available port. Verify that the port is open in Windows firewall. Also, note the port number. The port is used to create the URL for Retail Server in the format: https://<server name>:port/<web application name>. This URL is required to activate Retail Modern POS devices that connect to Retail Server.

    None

    RetailServerWebApplicationName

    The name of an existing web application or the name of an application that you want Setup to create.

    RetailServer

    RetailServerWebSiteSSLCertificateStore

    The Certificates store specified when the certificate was created or imported.

    My

    RetailServerWebSiteSSLCertificateRootStore

    The server where the certificate is stored.

    LocalMachine

    RetailServerWebSiteWorkingFolder

    The folder where you want PowerShell to create a new IIS virtual directory.

    %SystemDrive%\inetpub\wwwroot

    RetailServerWebAppPoolUser

    Enter a domain account for the application pool. Enter the account in the form value="Domain\User".

    None

    RetailServerWebSiteSSLCertificateThumbprint

    The thumbprint for your Secure Sockets Layer (SSL) encryption certificate. You must obtain a valid, registered certificate from a provider.

    Because this component uses Secure Sockets Layer (SSL) encryption, you must install a server certificate that was issued by a trusted certification authority. (For test environments, you can create a self-signed certificate in IIS.) You will need to paste the thumbprint for the certificate into the settings file. To view the thumbprint in IIS Manager, double-click the certificate and click the Details tab. We recommend that you paste the thumbprint into a text file and remove all spaces before you paste it into the settings file.

    Caution noteCaution
    A thumbprint can contain hidden characters at the beginning of the thumbprint value. You must delete these extra characters before you paste the thumbprint into the settings file.

    None

    RetailServerWebApplicationServiceBinarySourceFolder

    This folder contains required files for deploying Retail ServerBy default this folder is:

    C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Server\Package folder

    None

    RetailServerWebApplicationWorkingFolder

    The folder from where the web service will run. You can specify the RetailServerWebApplicationServiceBinarySourceFolder or any available folder.

    [RetailServerWebSiteWorkingFolder]\[RetailServerWebApplicationName]

    RetailServerAllownAnonymousMetadata

    This setting controls OData $metadata accessibility for anonymous users.

    In a developer environment, we recommend setting this parameter to true. Setting this to true enables the system to reference the OData $metadata service to generate client proxy code.

    In a production environment, this setting should be false.

    False

    RetailServerRequireSSL

    This option can be used to bypass the SSL requirement in a demonstration environment. In a production environment, you must set the option to true and specify values for the other SSL properties in the configuration file.

    True

  5. Save your changes.

ImportantImportant

If you deployed Retail Server in a web farm with a load balancer, you must specify a machine key to ensure that client connections retain session. For more information, see WIF and Web Farms.

Dn741428.collapse_all(en-us,AX.60).gifRun PowerShell scripts to deploy and configure Retail Server

After you configure the parameters in the rs-settings.xml file, you can run the Windows PowerShell scripts that deploy and configure Retail Server.

  1. On the server where you want to run the script, open the folder where the PowerShell scripts are installed. By default, the files are located at C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Server\Tools

  2. If you’re using Windows Server 2012 or a later operating system, use Windows Explorer to open the folder where the scripts are installed. Then click File > Open Windows PowerShell > Open Windows PowerShell as administrator.

    If you’re using Windows Server 2008 R2 or an earlier operating system, start Windows PowerShell as the administrator. Then, change the directory by using the following command: CD “<Path to directory>”.

  3. In the Windows PowerShell console, run the following command to create a credential object in Active Directory for the service account. Replace ‘domain\useraccount’ and ‘password’ with credentials that have permission to create sites in IIS:

    $Cred = @((New-Object System.Management.Automation.PSCredential(‘domain\useraccount',(ConvertTo-SecureString 'password' -AsPlainText -Force))))
    
    
  4. Run the following command to deploy and configure Retail Server:

    .\DeployRetailServer.ps1 -SettingsXmlFilePath .\rs-settings.xml -TopologyXmlFilePath .\rs-topology.xml -Credentials $Cred –Verbose $true
    

    For example:

    .\DeployRetailServer.ps1 -SettingsXmlFilePath "C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Server\Tools\rs-settings.xml" -TopologyXmlFilePath "C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Server\Tools\rs-topology.xml" -Credentials $Cred –Verbose $true

You must create a channel profile and a channel database profile for Retail Server in the Microsoft Dynamics AX client. For more information, see Set up a channel profile and Set up a channel database profile.

After you create the channel and channel database profiles, you can verify Retail Server configurations by opening a store in the Retail channels > Retail stores form. In the Profiles section, verify that the Channel profile and the Live channel database fields display the correct channel profile values.

After Retail Server is deployed and configured, you can deploy Microsoft Dynamics AX Retail Modern POS on supported clients. For more information, see Install Retail Modern POS.


Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).

Community Additions

ADD
Show: