Table of Contents

Key/Value Configuration Settings

The key/value configuration settings system provides a general-purpose way to configure certain settings for Acuit Pinpoint and for plug-ins.

Key/value configuration settings can be defined in various ways and at different levels and are combined to produce a single effective set of key/value configuration settings for a particular context. Settings defined at lower, more specific levels override settings with the same key name defined at higher, less specific levels.

Settings Hierarchy

A set of configuration settings consists of a list of key/value pairs, where both keys and values are strings. While it is a flat list, it represents a hierarchical list of key/value pairs with the nodes separated by a colon in the keys. Thus, any particular configuration setting in the hierarchy can be accessed via a single, unique key.

For example, consider the following conceptual configuration setting hierarchy:

  • "NotificationEmail" = "admin1@email.com"
  • "WarehouseIntegration"
    • "ServerName" = "WHPROD"
    • "WarehouseId" = "A13"
    • "NotificationEmail" = "admin2@email.com"

The above would result in this list of configuration setting key/value pairs:

  • "NotificationEmail" = "admin1@email.com"
  • "WarehouseIntegration:ServerName" = "WHPROD"
  • "WarehouseIntegration:WarehouseId" = "A13"
  • "WarehouseIntegration:NotificationEmail" = "admin2@email.com"

Collections of settings are specified by including a key value node above each item with the collection array index. For example, the following list of configuration setting key/value pairs could be used to represent two sets of "TestParams" settings groups:

  • "TestParams:0:Model" = "M1"
  • "TestParams:0:Amps" = "1"
  • "TestParams:1:Model" = "M2"
  • "TestParams:1:Amps" = "2"

Settings Sources

Key/value configuration settings can be defined via the following sources:

Database Configuration XML

The following elements within the Database Configuration XML allow a set of key/value configuration settings to be specified via a child settings element:

  • <database> Element: settings that apply to the database and/or all lines belonging to the database.

Line Configuration XML

The following elements within the Line Configuration XML allow a set of key/value configuration settings to be specified via a child settings element:

For example, the following settings element XML would configure the settings mentioned in the Settings Hierarchy section above:

<settings>
  <setting name="NotificationEmail" value="admin1@email.com" />
  <setting name="WarehouseIntegration">
    <setting name="ServerName" value="WHPROD" />
    <setting name="WarehouseId" value="A13" />
    <setting name="NotificationEmail" value="admin2@email.com" />
  </setting>
  <setting name="TestParams">
    <setting name="0">
      <setting name="Model" value="M1" />
      <setting name="Amps" value="1" />
    </setting>
    <setting name="1">
      <setting name="Model" value="M2" />
      <setting name="Amps" value="2" />
    </setting>
  </setting>
</settings>

settings.json Files

On both Acuit Pinpoint Server and Acuit Pinpoint Workstation computers, optional local settings.json files can be used to configure settings. This file can either be placed in the application installation folder or the application data folder1. If settings.json files exist in both the application installation folder and the application data folder, then the key/value settings values from both files will be combined, with settings from the application data folder file taking precedence for any settings with the same key.

The setting hierarchy can be represented directly within a settings.json file. For example, the following JSON would configure the settings mentioned in the Settings Hierarchy section above:

{
  "NotificationEmail": "admin1@email.com",
  "WarehouseIntegration": {
    "ServerName": "WHPROD",
    "WarehouseId": "A13",
    "NotificationEmail": "admin2@email.com"
  },
  "TestParams": [
    {
      "Model": "M1",
      "Amps": 1
    },
    {
      "Model": "M2",
      "Amps": 2
    }
  ]
}

Settings Contexts and Precedence

Separate sets of key/value configuration settings exist within Acuit Pinpoint, depending on the context from which they are referenced. The settings defined by the various sources listed in the Settings Sources section above are combined in various ways to produce a particular set of settings for use within a particular context.

When settings with the same key exist in multiple sources that contribute to the set of settings for a particular context, then the value from the source with the highest precedence for that context will be used.

The various settings contexts are listed below, along with the settings sources that contribute to each, in order of precedence from lowest to highest (i.e., settings from sources later in each list will override those from sources earlier in the list):

Acuit Pinpoint Server

  1. settings.json in the Acuit Pinpoint Server application installation folder.
  2. settings.json in the Acuit Pinpoint Server application data folder.

A Database

  1. Settings from Acuit Pinpoint Server.
  2. Settings configured in the database configuration XML via the database element's settings child element.

A Line

  1. Settings from the parent database.
  2. Settings configured in the line configuration XML via the line element's settings child element.

A Server Line Plug-in Instance

  1. Settings from the parent line.
  2. Settings configured in the line configuration XML via the plugIn element's settings child element.

Acuit Pinpoint Server Plug-ins can access their set of key-value configuration settings via the injectable IConfigurationRoot interface.

A Station Type

  1. Settings from the parent line.
  2. Settings configured in the line configuration XML via the stationType element's settings child element. Station type settings are inherited by derived station types.

A Station

  1. Settings from the station's station type.
  2. Settings configured in the line configuration XML via the station element's settings child element.

Acuit Pinpoint Workstation

  1. The Workstation Section reference settings, which are automatically provided by Acuit Pinpoint Workstation.
  2. Settings received from Acuit Pinpoint Server for the station.
  3. settings.json in the Acuit Pinpoint Workstation application installation folder.
  4. settings.json in the Acuit Pinpoint Workstation application data folder.

Note that there is special support for retrieving files for use at the workstation but that are configured via configuration settings on the server. See File References for more information.

A Workstation Plug-in

  1. Settings from Acuit Pinpoint Workstation.

Acuit Pinpoint Workstation Plug-ins can access their set of key-value configuration settings via the injectable IWorkstationService interface's Configuration property.

File References

There is special support for retrieving files for use at the workstation but that are configured via configuration settings on the server. A setting can be configured via one of the sources available on the server that contains as its value the full path name to a file accessible from the Acuit Pinpoint Server service running on the server. Then a workstation plug-in can request a local copy of that file, and the configuration system will automatically retrieve it from the server. Note that the Acuit Pinpoint Workstation computer does not require access to the original file path as configured on the server.

Paths can include environment variables quoted with the percent sign character (%) (e.g., %PLUGINSROOT%\PluginName.zip). The environment variable will be expanded at the context within which the setting is defined. For example, if it is defined within line configuration XML, then it will use the environment variable on the Acuit Pinpoint Server computer. However, if it is specified in a settings.json file on a workstation computer, it will use the environment variable on that computer.

The PlugIns setting in Workstation Section works like this, allowing workstation plug-ins to be configured completely by line configuration, with no special configuration necessary at the workstation.

Workstation plug-ins can also use this functionality to allow configuration files (e.g., custom images) to be completely configured via line configuration on the server.

  1. See Application Log Files for information on finding the application data folders for Acuit Pinpoint Server and Acuit Pinpoint Workstation. ↩