Each Invantive server product writes a sample of its settings when it starts. The sample holds every setting the product can read, with its description, its default value and, where one helps, an example. The product never reads the sample itself: it is a reference to copy settings from. ## Name and Location The sample is named `appsettings.<product>-<major>-<minor>.sample`, with the name of the product in lower case and its release. Release 27.0 of [[Invantive Data Hub]], for instance, writes `appsettings.invantive-data-hub-multi-platform-27-0.sample`. The sample is written to the folder where the product looks for `appsettings.json`. That is the folder of the product for a web application, and the configuration folder, normally `%USERPROFILE%\Invantive`, for Invantive Data Hub. When that folder cannot be written, the sample is written to the temporary folder of the operating system instead: `/tmp` on Linux and `%TEMP%` on Windows. This happens, for instance, when the configuration folder is mounted read-only in a container. The sample then lives inside the container and disappears with it. The sample is written only when its content differs from the file already there. A new release adds its own sample and leaves the one of the previous release in place. ## Console Message Every start reports on the console where the sample is: - `itgencsw001`: the sample was written to the folder searched. - `itgencsw002`: the sample in the folder searched is up to date and was left as it is. - `itgencsw003`: the folder searched cannot be written, so the sample was written to the temporary folder. - `itgencsw004`: the sample could not be written anywhere. This is a warning; the product starts as usual. The sample is written before the settings themselves are checked. A start which fails on a missing or wrong setting therefore still leaves the sample behind. ## Content The sample is JSON with comments, in the notation of the settings files of Invantive: one setting per line, a comma at the start of every line after the first, and two spaces of indentation per level. The description of a setting stands on the lines above it: ```json // // Sample settings of Invantive Data Hub (multi-platform) 27.0.0.0. Not read by the product. // The product reads: // - C:\Users\<user>\Invantive\appsettings.json // - C:\Users\<user>\Invantive\appsettings.Production.json // Copy only a changed setting into one of them. // { "DataHub": // // Settings of the Elastic APM agent to which Invantive Data Hub reports its activity; it is off // unless enabled in these settings. // { "ElasticApm": // // Whether the Elastic APM agent is enabled; data is recorded only when Recording is true as // well. // { "Enabled": false // // Base64-encoded API key with which the agent authenticates at the APM server. // , "ApiKey": "somesecret" ... ``` Every value in the sample is the default: the value the product uses when the setting is absent. A secret such as a password, a client secret or an API key reads `somesecret` instead of its default. A list of objects shows one element with the settings of such an element, and a group keyed by name shows one entry named `<name>`. ## Using the Sample Copy only the settings which have to differ from their default into `appsettings.json` or `appsettings.<environment>.json`. Copying the whole sample fixes every default at the value of the release which wrote it, so a default improved in a later release no longer takes effect. A copied list is also added to the elements the product already holds, and a copied list of objects adds its example element. ## Products The following products write a sample, available from release 27.0: - [[Invantive Bridge Online]], [[Invantive App Online]] and [[Invantive Credentials Server]]: one sample for each role the installation plays. - [[Invantive Cloud]] and the services behind it. - [[Invantive Data Access Point]]. - [[Invantive Data Hub]]. - [[Invantive MCP Server]]. - [[Invantive UniversalSQL Server]].