Edit

Share via

Installation steps for Retail channel components in an on-premises environment

Note

Community interest groups have now moved from Yammer to Microsoft Viva Engage. To join a Viva Engage community and take part in the latest discussions, fill out the Request access to Finance and Operations Viva Engage Community form and choose the community you want to join.

This article covers the installation steps for Commerce channel components in an on-premises environment.

Important

A known issue currently prevents self-service packages from being correctly applied to on-premises environments. To work around this issue, pull the installers directly from Microsoft Dynamics Lifecycle Services and use them as needed. In this case, you don't use Commerce headquarters to download the installers but use it to download only the configuration files as needed.

In an on-premises environment, you enable channel functionality exclusively by using Commerce Scale Unit (self-hosted). For an overview, see Commerce Scale Unit (self-hosted).

Unlike a cloud deployment, an on-premises environment doesn't enable seamless, high-availability deployment of channel components through Lifecycle Services. The only way to use channel components is by installing Commerce Scale Unit (self-hosted).

Prerequisites

Before you start the installation of channel components, complete all prior installation steps for an on-premises environment. These steps are listed in Set up and deploy on-premises environments (Platform update 41 and later). You must install at least version 8.1.1 for Commerce to have full functionality. We recommend that you update to the latest application version that's available.

Note

It's critical to ensure that a secure network that isn't publicly accessible is used to connect Commerce Scale Unit to Headquarters. You must also restrict network access to Headquarters, so access is only allowed to known Commerce Scale Unit devices through network filtering or other means. This requirement means that a firewall must exist and using an allowlist is highly recommended.

Installation steps

  1. On the previously created Application share (not the LocalAgent share folder), in the root directory of the share location, create a folder that is named selfservicepackages.

  2. On each AOS node, create an easily accessible directory, such as C:\RetailSelfService.

  3. On one AOS node (it doesn't matter which node), run the RetailUpdateDatabase.ps1 script. If you used the remoting scripts, this script is available at the path C:\D365FFO-LBD on each AOS node.

    If your Commerce headquarters is on version 10.0.0 or later, run the following PowerShell script.

    .\RetailUpdateDatabase.ps1 -envName '<Environment name>' -AosUrl 'https://ax.d365ffo.onprem.contoso.com/namespaces/AXSF/' -SendProductSupportTelemetryToMicrosoft

    If your Commerce headquarters is on a version that is earlier than 10.0.0, run the following PowerShell script.

    .\RetailUpdateDatabase.ps1 -DatabaseServer '<Database server name for AOS database>' -DatabaseName '<Database name for AOS database>' -envName '<Environment name>' -RetailSelfServicePackages '<Local path of Retail self-service packages, such as C:\RetailSelfService>' -SendProductSupportTelemetryToMicrosoft
    • The -envName parameter is the name that was assigned to the environment in Microsoft Dynamics Lifecycle Services when it was originally deployed.
    • The -SendProductSupportTelemetryToMicrosoft parameter is required to enable telemetry to Microsoft. Telemetry is critical to maximize support from Microsoft.
    • The script performs various actions, including updating the Service user and role, and updating registry keys.

    Important

    There's currently a known issue where self-service packages aren't correctly applied to on-premises environments. Therefore, we recommend that you pull the installers directly from Lifecycle Services and use them as needed. In this case, Commerce headquarters is no longer used to download the installers but is used to download only the configuration files as needed.

  4. On each AOS node, run the following PowerShell script.

    .\RetailUpdateDatabase.ps1 -RetailSelfServicePackages 'C:\RetailSelfService\Packages'

    Note

    The -RetailSelfServicePackages parameter is the full path location that you created in the beginning of this procedure (C:\RetailSelfService).

  5. Download the appropriate binary update from Lifecycle Services to get the Commerce installers. For instructions, see Download updates from Lifecycle Services (LCS).

  6. Extract the zip file, and copy all self-service installers into the C:\RetailSelfService folder that you defined and created on each AOS machine in step 2. The six self-service installers are as follows:

    • AsyncServerConnectorServiceSetup.exe
    • RealtimeServiceAX63Setup.exe
    • HardwareStationSetup.exe
    • ModernPosSetup.exe
    • ModernPosSetupOffline.exe
    • StoreSystemSetup.exe

    Note

    Cloud environments can synchronize self-service installers through Headquarters from what is available in Lifecycle Services (Synchronize self-service installers in Dynamics 365 Commerce). On-premises environments can't utilize this functionality. However, these environments can still download from Lifecycle Services. The SDK is available in the deployable package zip file. The self-service installers are available from the Lifecycle Services Asset library. You can utilize the upload and download mechanism from within Lifecycle Services, but the Headquarters synchronization functionality won't work.

  7. Navigate to the AD FS machine, open a PowerShell window with administrator privileges, navigate to the file share that contains your infrastructure scripts folder, and run the following command.

    # Host URL is your DNS record\host name for accessing the AOS
.\Create-ADFSServerApplicationForRetail -HostUrl 'https://ax.d365ffo.onprem.contoso.com'

    Note

    As a security best practice, you should run this script for each Commerce Scale Unit. In this way, you help maximize security and minimize the workload if there's a security breach.

  8. In AD FS Management, access the newly generated Server application from Application Groups.

  9. Edit the newly generated Server application, and select Reset the Secret.

    Note

    It's critical that you keep this secret safe. It should be copied only once and never stored on the system. The client ID and secret that are generated are used in the Commerce Scale Unit installer. Therefore, you need them later. Although you can always reset the secret, it must then be updated on any Commerce Scale Unit that used the previous secret.

  10. In Commerce headquarters, go to Retail and Commerce > Headquarters setup > Parameters > Commerce shared parameters.

  11. On the Security tab, under Transaction service legacy properties, select the Real-time Service profile field, and then select the newly created Default value.

  12. On the Identity providers tab, on the Identity providers FastTab, select Add.

  13. In the new Issuer row, enter the new identity provider value https://sts.windows.net/ in the field.

  14. On the Action Pane, select Save.

  15. Go to Retail and Commerce > Headquarters setup > Parameters > Commerce parameters.

  16. On the General tab, select the Initialize link to configure seed data for Commerce functionality.

    Note

    • Read the important message at the beginning of this article regarding a known issue with installers no longer functioning through headquarters for download.

    • The installers won't download from the relevant pages the first time that a download is attempted. This behavior occurs because the installers have been placed in the download location, and the associated database values don't yet exist. When the Download functionality is attempted in Commerce headquarters (for example, for Commerce Scale Unit or Modern POS), an error is shown. Automated upload functionality is then initiated to enable the installers to be downloaded the second time that the download is attempted. (Wait one minute before you try to download the installer again.)

    • The Peripheral Simulator (downloaded on the Hardware profile page in headquarters) won't be available until at least one Hardware profile is created and functional. After that point is achieved, the following script can be run.

      .\RetailUpdateDatabase.ps1 -envName '<Environment name>' -UpdateRetailHardwareProfileSelfServicePackage

  17. Follow the installation steps for installing the Commerce Scale Unit. For instructions, see Configure and install Commerce Scale Unit (self-hosted). At multiple locations in that article, notes reference changes to the instructions for an on-premises deployment. It's important that you note each of these changes.

  • Last updated on