Data Format and Data Sources

The configuration files are provided in JSON format. They are provided either in file form or they are saved in an internal adminstrative database.

A file is always required to start the program (see Program Execution). This file must contain at least the configuration properties for the database connection from which the other data is loaded.

If the configuration data contains references to other configurations, these syntaxes (URI schemes) apply depending on their source. The URI scheme for files follows a general standard. The URI scheme for database-based configurations is a proprietary extension.

Syntax	Description
`file:///{file path}` or `file://{server}/{file path}`	The first variant (`file:///{file path}`) is used for local files. The syntax contains an absolute or relative file path or just the file name. Examples: `file:///c:/data/myConfig.json` `file:///data/myConfig.json` `file:///myConfig.json` The folder path of the higher-level configuration is used as the basis for resolving a relative path. At the top level, this is the folder path of the start configuration file. The second variant (`file://{server}/{file path}`) is intended for network access to another server and is comparable to a UNC path. The file path part is made up of `{share name}/{file path}`. Old configurations only support the file form and no URI syntax. For compatibility with these old configurations, the specification of the pure file path without URI prefix is permitted. Specifying the file extension `.json` is optional.
`db://{name}[/{stage}[/{version}]]`	Configurations stored in the database are subject to versioning. A distinction is made between the "development", "test" and "production" stages. Notice For more information on the versioning logic, see The Configurator. When specifying a reference, the unique technical name of the configuration is mandatory. The stage and the version are optional components. These two components are interdependent, i.e. specifying a stage without a version is possible, but specifying a version without a stage is not permitted. The technical identifiers for the stages are `Dev`, `Test` and `Prod`. A version number is made up of 3 counters separated by a dot. The counters start at zero and can be incremented independently of each other, e.g. `2.17.0`. If the version is not specified in the reference, the latest version of the relevant stage is implicitly loaded. If the stage is also not specified, the globally configured default value `Config.DefaultStage` applies. Example: Full reference: `db://myConfig/Prod/2.17.0` Minimal form of reference: `db://myConfig` Notice If possible, use the minimal form. This way, you do not have to manually adjust all references every time you change the stage and version.

Syntax

Description

file:///{file path}

file://{server}/{file path}

The first variant (file:///{file path}) is used for local files. The syntax contains an absolute or relative file path or just the file name.

Examples:

file:///c:/data/myConfig.json
file:///data/myConfig.json
file:///myConfig.json

The folder path of the higher-level configuration is used as the basis for resolving a relative path. At the top level, this is the folder path of the start configuration file.

The second variant (file://{server}/{file path}) is intended for network access to another server and is comparable to a UNC path.

The file path part is made up of {share name}/{file path}. Old configurations only support the file form and no URI syntax. For compatibility with these old configurations, the specification of the pure file path without URI prefix is permitted. Specifying the file extension .json is optional.

db://{name}[/{stage}[/{version}]]

Configurations stored in the database are subject to versioning. A distinction is made between the "development", "test" and "production" stages.

Notice

For more information on the versioning logic, see The Configurator.

When specifying a reference, the unique technical name of the configuration is mandatory. The stage and the version are optional components. These two components are interdependent, i.e. specifying a stage without a version is possible, but specifying a version without a stage is not permitted.

The technical identifiers for the stages are Dev, Test and Prod. A version number is made up of 3 counters separated by a dot. The counters start at zero and can be incremented independently of each other, e.g. 2.17.0. If the version is not specified in the reference, the latest version of the relevant stage is implicitly loaded. If the stage is also not specified, the globally configured default value Config.DefaultStage applies.

Example:

Full reference: db://myConfig/Prod/2.17.0
Minimal form of reference: db://myConfig
Notice
If possible, use the minimal form. This way, you do not have to manually adjust all references every time you change the stage and version.

The configuration files are divided as follows:

Global configuration: a configuration file that includes the basic settings for program execution. An individual global configuration is assigned to each program instance of xSuite Interface. The global configuration must not be identical to the global configuration of another instance running in parallel on the same computer.
Scenario configuration: a configuration file that describes a specific processing scenario. How many scenario configurations are provided depends on which scenarios are processed by a single instance.

Each configuration is made available as a separate resource, with independent files or data sets existing for each global and for each scenario configuration. A global configuration is assigned directly to the program instance; scenario configurations are assigned within the global configuration by references to the scenarios to be processed. The same scenario configuration can be referenced in multiple global configurations for parallel processing of the same scenario by multiple instances.

Example

The following example shows the basic structure of the configuration data:

Notice

In JSON format, pay attention to the correct capitalization of the property names and the values.

{
   "General": {
      "ExitOnInitError": true
   },
   "Logging": {
      "Database": {
         "Type": "MsSqlServer",
         "Host": "localhost",
         "Port": 1433
      }
   },
   "WebService": {
      "Url": [
        "http://localhost:8000"     
        "http://testserver:8000"
      ] 
   },
   "Worker": [
      {
         "Type": "Input"
      },{
         "Type":"Output"
      }
   ]
}

The top-level JSON properties (e.g., General) are only structural elements and always contain an object with child properties as a value. These properties either directly describe an elementary value (e.g., .ExitOnInitError) or, in the case of a multi-level structure, represent an object (e.g., .Database below Logging).

JSON Format

Configuration properties and property values are presented in this documentation as follows:

Type of Specification	Example	Description
Path to a property	`Logging.Database.Type`	In this documentation, the full path to the lowest property (i.e., the elementary value) is generally provided. Individual properties are separated by a dot.
Property Values	`Logging.Database.Type: "MsSqlServer"`	A colon always separates a property values from the path specification. For the path, the quotation marks are omitted for better readability. Quotation marks surround the value to emphasize the correct data typ. Thus, string values are encased in quotation marks.
Numeric Values and Boolean Values	`Logging.Database.Port: 1433` `General.ExitOnInitError: true`	Numeric values and Boolean values are written without quotation marks. According to JSON syntax, a period must be used as a decimal separator for numeric values with decimal places.
String Values	`"Test(\"Hello\")"`	When specifying string values, mask embedded quotes as `\"`. In JSON format, a macro expression such as `Test("Hello")` (which in turn contains a string parameter and must be marked as a string in its entirety) will always need to be written `"Test(\"Hello\")"`. To obtain the masking character `\` as a normal character, specify this character twice (`\\`).
Arrays	`WebService.Url[]`	To indicate in the path specification that a property is an array, add square brackets to the property.
Arrays	`Worker[].Type`	If the array values are not elementary, but represent objects with subproperties, you can place another property after the square brackets.

In this section:

xSuite Interface Windows Prism 5.x – Online Help