Configuration Keys and Internal Keys

This page lists the configuration keys of an Engine and the internal variables holding some state (they are automatically determined). Configuration Keys, in difference to Profile Keys, are meant to be individual for one Engine/Machine and not for a whole group of Engines, e.g. setting the log level.

Engine: Configuration Keys

Here are the values of the config_default.json file. If a user needs to change some key/value, it should be done in a (new) config.json file, see: PROCEED Config files and the Architecture Diagram

AutoSetByEngine: All configuration values marked with AutoSetByEngine are dynamically defined by the Engine depending on the capabilities of the Machine it is running on. This value can be overridden or extended with the user configuration.

Config Key	Default Value	Type	Explanation
name	""	String	AutoSetByEngine An identifier for the engine/machine, used to register the engine under the PROCEED mDNS service type: {name}._proceed._tcp, If not given the OS hostname value will be used. Alias: machine.name
description	""	String	For describing the machine, e.g. "Raspberry Pi with camera connected" Alias: machine.description
log.enabled	true	Boolean	If logs should be created
log.logLevel	"info"	LogLevel, String	Indicates the minimum level a message has to have to be persistently saved. Setting the logLevel to warn, means that only messages that are assigned warn, error and fatal will be stored
log.forwardToConsole	true	Boolean	Logs are only printed to the console
log.consoleLevel	"info"	LogLevel, String	Specifies the minimum level that has to be assigned to a message for that log to be printed to the console, if forwardToConsole = true
log.maxProcessLogEntries	500	Int	TODO: old name maxLogEntries needs to be changed Log Rotation: The number of process-related logs entries that can be stored in a table before a new table is created
log.maxProcessLogTables	5	Int	Log Rotation: The number of tables that can be created for the logs of a specific process
log.rotationInterval	600	Int; Time in Seconds	Log Rotation: The interval at which the log rotation is triggered
log.maxStandardLogEntries	1000	Int	The number of log entries that can exist in the table used to store logs that are not made in relation to a business process
processes.acceptUserTasks	false	String	AutoSetByEngine Indicates, if the Engine is allowed to execute User Tasks. It is automatically assumed to be true if "Screen" is available in machine.outputs. Can be manually set to true or false. E.g. if a server has no own screen, but should serve the user tasks over a HTTP endpoint. Or e.g. if a Screen is detachable, so the Machine should never serve User Tasks.
processes .deactivateProcessExecution	false	Boolean	Deactivates the acceptance and execution of new processes
engine.networkRequestTimeout	10	Number	The maximum time in seconds that the engine waits for an answer to a network request. E.g. if a servers does not answer an online-checking request within 10s, it is considered to not be able to reach the server.
engine.loadInterval	10	Int; Time in Seconds; Min: 1, Max: 60	It specifies the interval at which the CPU information are fetched for calculating the average load. It allows the user to decide on the needed precision.
engine.discoveryInterval	10000	Int; Time in Seconds	The interval the discovery of other Engine is "checked". This mainly looks into the mDNS list and tests if every listed Engine is available. This also means, that the maximum time to notice the mDNS registration of an Engines in the network takes on one Engine additionally at max the discoveryInterval time.
machine.port	33029	Number	Moved to Env Profile, but for test purposes it is still configurable here
machine.classes	[ ]	Array of Keywords/Strings	Sets the Machine class/category. There are some predefined values (e.g. "Portable" or "Static"), but it can also contain self-defined keywords (e.g. "Transportation"). Some of them can be set automatically by the platform, e.g. on mobile Phone "Portable" is automatically set. The class of a Machine is used for multiple things: 1. sending a process to a specific machine category and 2. sending the Class Profiles to a correct Machine 3. matching the stored Profiles to determine the currently active profile.
machine.domains	[ ]	Array of Strings not case-sensitive, allowed characters for the name: a-z, A-Z, 0-9, -_ (no spaces) Special Characters with meaning: / separates the domain levels (not as a leading character on the first place)	A Machine can belong to a location domain, e.g. max-office/cupboard/motion-sensor. The string is a hierarchical structure of names separated by "/". This is written like a MQTT topic name and can be easily filtered at runtime via process constraints.
machine.inputs	[ ]	Array of Keywords/Strings	AutoSetByEngine Complements the possible input methods of the Machine, if they are not automatically detected. Possible values are: "TouchScreen", "Microphone", "Keyboard", "Numpad", "Camera"
machine.outputs	[ ]	Array of Keywords/Strings	AutoSetByEngine Complements the possible output methods of the Machine, if they are not automatically detected. Possible values are: "Screen", "Speaker"
machine .onlineCheckingAddresses	["clients3.google.com", "1.1.1.1"]	Array of IP Addresses or domain names	If it is possible to reach one of multiple IP addresses, it is assumed to be online.
machine .currentlyConnectedEnvironments	[ ]	Array of Objects with [{id: "...", name: "..."}, ...]	AutoSetByEngine The environments a Machine is currently working in. This list extends the automatically detected environments. Is needed to determine, which env profiles are currently active.
messaging .serverAddress	""	String	see MQTT Configuration
messaging .username	""	String	see MQTT Configuration
messaging .password	""	String	see MQTT Configuration
messaging .baseTopic	""	String	see MQTT Configuration

Backup: old values

| machine.hasScreen | true | Boolean | If the Machine is connected to a Screen; default = true because for testing on laptops and this is mostly used for user tasks which can also be requested remotely from another machine with a screen connected |

| machine.hasInput | true | Boolean | If the Machine is connected to a input, e.g. a keyboard or speech recognition; default = true => see hasScreen |

Engine: Internal Variables

Internal Variables hold a state that is important for the Engine and process execution. They can sometimes be influenced or overwritten by configuration values or environment profiles.

Internal Variable	Type	Module	Rewritable/Extended by	Explanation
machine.id	UUIDv4 (String)	Machine		Unique id of a machine, e.g. "6bd9c3cf-8164-453a-a039-e8aaf138f192"
machine.name		Machine	Configuration	see Configuration name
machine.hostname	String	Machine		The Hostname of the OS
machine.inputs		Machine	Configuration	see Configuration
machine.outputs		Machine	Configuration	see Configuration
machine.classes		Machine	Configuration	see Configuration
machine .currentlyConnectedEnvironments		Machine	Configuration	see Configuration
machine .currentlyActiveProfile	Profile	Machine		The mixed, current profile values for the current Environment. It is calculated by the Configuration Module with the following Priority: Home Env > Current Third-Party Env > Current User Profile > Default Profile
machine.online	Boolean	Machine	Profile	Indicates, if a connection to the WWW and Internet is possible with a ping to the machine.onlineCheckingAddresses (In the MS on Windows a fallback to HTTP GET is implemented). true if a connection is possible.
process.runUntrustedCode	Boolean	Process	Profile	If the Code/Script execution is done by a secure method (vm2, web workers), it is set to true, else false. If true it can run every code, because this code is not able to manipulate the Engine.
process.acceptUserTasks	Boolean	Machine	Configuration	see Configuration
user.currentlyLoggedInUser	User-Id (Number)	Tasklist

Furthermore, there is a whole bunch of Machine-related information automatically detected and accessible via the machine module, e.g. the IP address or the CPUs.

Architecture of the Configuration Component

In the Node.js implementation of the Native Part configurations can be set via three possibilities:

• Command-Line Interface: on start
• config.json: before start (not at runtime)
• Via the Configuration component: at runtime, e.g. via the UI or REST endpoint

The default configuration values are stored in and read from config_default.json, if they are not be overwritten by any of the previous methods.

At runtime the configuration component just keeps a non-persistent data structure of all config values in memory. All modules that need a value have to ask the Configuration component with readConfig(„<configKey>“) (and are not allowed to directly use config.js inside the Dispatcher Libs). E.g. module.js is responsible for setting some engine properties, so it reads the port configuration to set the TCP port for the HTTP Endpoints.

The configuration values can be changed at runtime via the Configuration component with changeConfig(“<configKey>”, “<configValue>”). In the Node.js implementation it is not possible to change config.json at runtime (it isn't re-read at runtime)

There are currently two ways how the configuration can be changed at runtime: via the Monitoring Endpoint and via the Configuration Page of the UI module.

All config values that are changed at runtime (via changeConfig()) are persistently stored in the native part with config.js. In Node.js this means the new config values are inserted/overwritten in config.json.

For storing config changes `data.js` is **not** used, because ...

...of the platform independence requirement: every platform usually has other ways of setting the start configuration persistently. E.g. in Node.js this could be completely done inside config.json and we don't necessarily need REST or the UI. But e.g. on IOS you usually configure apps over the OS configuration and on Android via the app configuration. You often don't have an easy possibility to change text files on these mobile platforms.

The requirement is that admins or users can change a configuration which is used at the next start of the engine.

That is why runtime changes of the configuration in the universal part needs to be stored persistently (because on Android a User can only change it via the app UI or REST). But it is not possible to use data.js, since this would make it complicated for a Node.js implementation user to change the configuration (then it would not be with config.json anymore but with the DB choice).

---

If other modules want to be notified if a configuration key/value gets updated at runtime, they have to register with registerForConfigChange(„<configKey>“, clb).