How to Capture and Substitute Manifests and Settings

Various components of an Analytics Plugin (reference-countable objects implementing interfaces) — such as Plugin, Engine, and DeviceAgent — must provide their Manifests to Nx Witness Server. Manifests are JSON documents, passed from a Plugin to the Server as strings.

Some parts of a Manifest can be static (hard-coded in the Plugin source); some other parts can be dynamic — generated by the Plugin in runtime depending on its current state and setting values.

Typically, a Plugin contains a hard-coded Manifest template in the form of a JSON string literal or a resource string and extends this template with runtime information to form the actual Manifest to be sent to Nx Witness Server.

Capturing Manifests

There is an easy way to ask Nx Witness Server to save each Manifest it receives to a file: in vms_server_plugins.ini, specify the path to some directory as the value of the following option:

analyticsManifestOutputPath=captured/manifests

Here, captured/manifests is a path relative to the .ini files directory; an absolute path can be specified as well. The directory must exist. Restart Nx Witness Server, and watch the files being created in the specified directory.

The file names contain all the details about the component which produced the Manifest, such as the Plugin name and device (camera) id. If a file already exists, it will be overwritten. For example, for Stub Analytics Plugin, the generated files may look like this:

• Manifest of a Plugin:
  • stub_analytics_plugin_manifest.json
• Manifest of the Plugin’s Engine:
  • stub_analytics_plugin_engine_a6f9ed2c-261f-be90-5627-5bac6d0e7110_manifest.json
• Manifest of the Engine’s DeviceAgent for a certain camera:
  • Stub_analytics_plugin_device_e3e9a385-7fe0-3ba5-5482-a86cde7faf48_manifest.json

For details about the file naming scheme, see the description of the mentioned .ini file option in the generated .ini file.

Substituting Manifests

You may want to occasionally test how the Plugin or Nx Witness Server will behave if something is changed in a Manifest. There is a convenient way to instruct the Server to ignore a Manifest coming out of a plugin and, instead, use a supplied file — without the need to change the Plugin code and re-build it. 

To perform this substitution: in vms_server_plugins.ini, specify the path to the existing directory which contains the Manifest files to be used by Nx Witness Server, as the value of the following option:

analyticsManifestSubstitutePath=substitute/manifests

Here, substitute/manifests is a path relative to the .ini files directory; an absolute path can be specified as well. Put the Manifests that you want to substitute, into this directory.

The files must have names that follow the same scheme as the ones generated by the process of capturing Manifests (described in the previous section). The most convenient method is as follows:

1. Capture the Manifests.
2. Copy the ones that need to be modified, to another directory.
3. Edit the files.
4. Restart Nx Witness Server and observe it using the substituted Manifests.

For details about the file naming scheme, see the description of the mentioned .ini file option in the generated .ini file.

Note: If both Capturing and Substituting is activated, the captured Manifest file will contain the original Manifest produced by the Plugin, before it is substituted.

Capturing Settings

Similar to the Manifests, the Settings that are passed to a Plugin from Nx Witness Server can also be captured. To capture the Settings, in vms_server_plugins.ini, specify the path to some directory as the value of the following option:

analyticsSettingsOutputPath=captured/settings

Here, captured/settings is a path relative to the .ini files directory; an absolute path can be specified as well. The directory must exist. Restart Nx Witness Server, and watch the files being created in the specified directory.

The file names contain all the details about the component which received the Settings, such as the Plugin name and device (camera) id. If a file already exists, it will be overwritten. For example, for Stub Analytics Plugin, the generated files may look like this:

stub_analytics_plugin_engine_687611a2-fd30-94e7-7f4c-8705642b0bcc_effective_settings.json
stub_analytics_plugin_device_ed93120e-0f50-3cdf-39c8-dd52a640688c_effective_settings.json

For details about the file naming scheme, see the description of the mentioned .ini file option in the generated .ini file.

Substituting Settings

You may want to occasionally perform a test and force the Plugin to be sent the particular values of Settings instead of those which Nx Witness Server normally sends. There is a convenient way to instruct the Server to feed the Plugin the Settings values written in a file.

To perform this substitution, in vms_server_plugins.ini, specify the path to the existing directory which contains the Settings files to be used by Nx Witness Server, as the value of the following option:

analyticsSettingsSubstitutePath=substitute/settings

Here, substitute/settings is a path relative to the .ini files directory; an absolute path can be specified as well. Put the Settings files that you want to substitute into this directory.

The files must have names that follow the same scheme as the ones generated by the process of capturing Settings (described in the previous section) but without _effective. Also, you may omit _<engine-id> if you want the Settings file to be used for any Engine of the particular Plugin.

The Settings files are in JSON format, and contain a JSON array of objects, each having name and value fields. Here is an example of such file:

[
    { "name": "testCheckBox", "value": "true" },
    { "name": "testComboBox", "value": "value2" },
    { "name": "testDoubleSpinBox", "value": "3.1415" },
    { "name": "testSpinBox", "value": "42" },
    { "name": "text", "value": "a text" }
]

For details about the file naming scheme, see the description of the mentioned .ini file option in the generated .ini file.

Notes on Capturing and Substituting

• It’s convenient to have the same directory for both captured and substituted settings, because the file names differ by the _effective part. To alter some set of Settings, just copy the generated file removing the _effective part, and edit this copy.
• If both Capturing and Substituting is activated, the captured Settings (with _effective in file names) will be the same as the substituted ones, because they must always reflect what is fed to the Plugin by the Server.
• We plan for future versions of the Server to capture two types of Settings: those that the Server would feed to the Plugin if there were no substitutions; and those that are supplied by the Plugin to the Server via the pluginSideSettings() methods.