Configuring the Enterprise Server Environment

After installing Advanced Store on an enterprise server, a post-installation configuration process is required to provide system credentials and environment-specific values to the enterprise applications. There are two methods for configuring the system: basic and advanced. The basic process is completed interactively using the Input File Builder utility, and the advanced process is completed step-by-step using individual scripts. The Input File Builder utility is recommended for a lab environment or for initial installations of Advanced Store. The step-by-step process is recommended for advanced users who want to further customize their environment settings. The configuration process, whether basic or advanced, consists of the following steps:

  1. Create a Configuration Input File.
  2. Optionally, encrypt the configuration file.
  3. Copy the configuration file to specific enterprise servers.
  4. Configure the system with the values provided.

The basic process uses the following tools to complete all steps:

  • Input File Builder
  • Enterprise Configuration Script

The advanced process uses the following code or scripts:

  • Sample or default Configuration Input File
  • Input Encryption Script
  • Enterprise Configuration Script

Advanced Store offers the flexibility of using both methods in combination at different stages and for differing environments, such as a Quality Assurance lab, pre-production setting, or production environment. Retailers can create several input definition files customized to each environment and run the Enterprise Configuration Script using each input file when needed, provided that the same input definition file is used on all the enterprise servers within the same environment. The following section describes concepts applicable to both methods of configuration.

Concepts

This section describes the files and utilities used during the enterprise configuration process.

Enterprise Configuration Script

The Enterprise Configuration Script, Config.ps1, configures the enterprise server environment. This script accepts an input file, either encrypted or unencrypted, and applies the configuration defined in the input file across the system that it is executed on. The script uses the factory default file(s) to apply settings and environment-specific values obtained from the Input Configuration File. The Enterprise Configuration Script is installed by default with the Advanced Store DSR Enterprise installation. This script will be run on the following enterprise servers:

  • Messaging Server
  • Web Server
  • Application Server
  • EOM Server
  • ETS Server

The configuration script supports creating or updating the runtime app.config and web.config files with environment-specific values, such as database connection strings and RabbitMQ endpoints, as well as any existing appSettings values within those configuration files. The script uses the default configuration files to merge the changes into the runtime path(s). The Enterprise Configuration script updates the following configuration files:

  • Web (API) Server
    • NCRRetailOne web.config
  • Application Server
    • dbConfig.config
    • ExportToAMS.exe.config
    • Ncr.Retail.BatchApply.exe.config
    • Ncr.Retail.DataPurge.exe.config
    • Ncr.Retail.EncryptionKeyUpdate.exe.config
    • Ncr.Retail.Services.EOMParameterStaging.exe.config
    • Ncr.Retail.Services.EOMSynchronization.exe.config
    • Ncr.Retail.Services.WindowsServiceHost.exe.config
  • Enterprise servers where Utilities are installed
    • Ncr.Retail.Setup.StoreDataPush.exe.config
    • Ncr.Retail.Platform.Setup.RabbitMQ.exe.config
Caution

If you manually update a runtime file after configuring the system, make sure to modify the Configuration Input File (configInput*.json) to match the desired settings. If not, the values in the Configuration Input File will overwrite the manual updates made to the runtime files the next time you run the Enterprise Configuration Script is run.

Input File Builder utility

The Input File Builder is a utility to help users build an input definition file specific to the environment values supplied. The utility prompts users to supply the required environment and credential details and then updates the input definition file. The Input File Builder guides users to encrypt this file and create a certificate, if required. After encryption, the utility provides users the option to automatically run the Enterprise Configuration Script using the configurations provided and an additional default set of application settings.

The Input File Builder can be run either as a command-line utility or as a PowerShell script. This tool is installed by default with the Advanced Store DSR Enterprise installation. After installation, the tool will be run on the Messaging Server.

Configuration Input File

The Configuration Input File is a JSON-formatted input definition file that provides required values to the Enterprise Configuration Script. Retailers can either manually modify the supplied Input Configuration File with the environment details, or interactively use the Input File Builder utility. The Input File Builder saves a copy of Configuration Input File to the Utilities folder after modifying it. If creating an input definition file manually, retailers can either copy the supplied Input Configuration File from the Default folder, or create a new file using the Sample Configuration Input File as a guideline. This file can be placed in any directory for use by the Enterprise Configuration Script.

The Configuration Input File contains the environment-specific configurations, such as connection strings, credentials, appSettings that point to the RabitMQ endpoints, and commonly-changed appSettings values. Users can further extend the capability of the input file to use all available appSettings. By adding a key-value pairs to the input file, the configuration script will use the value specified and set that in the runtime configuration file. If no additional appSetting keys and values are added to the file, then the default settings are assumed.

Input Encryption Script

Advanced Store provides a means to secure the input definition file with encryption, as sensitive environment credentials are defined within the file, which is used to configure the environment, and may exist on disk on the systems being configured. There are two ways to encrypt an input definition file—automatically using the Input File Builder utility, or manually by running the Input Encryption script, encryptInput.ps1. The Input Encryption Script is installed by default by the Advanced Store DSR Enterprise installation, and is located in the Utilities folder. The Input Encryption Script is run as part of the advanced configuration process after creating or modifying the Configuration Input File. Encrypting the configuration file is optional.

Deploying the Configuration Input File

After creating or modifying the Configuration Input File, users will manually copy this file to each server where the Enterprise Configuration Script is to be run. The file can be copied over encrypted or in clear text. If using an encrypted input file, the certificate must also be copied to the enterprise servers, along with the input file, and installed on each machine.