Writing a Value in a JSON File - API Server - Foundation 24.1 - Foundation 24.1 - Ready - OnBase - Essential - Premier - Standard - external - Standard - Essential

The write command allows you to write a specified property value to a JSON configuration file. By default, the write command writes values to the file in plain text, but you can encrypt a value by using the --encrypt parameter.

CAUTION: Be very careful when updating the JSON configuration files. If a copy exists with a similar naming scheme (for example, appsettings.backup.json), and that copy is not deleted, the incorrect JSON configuration file may be used. Configuration files are read in lexicographic order, or the order in which they are loaded. This means that the last file saved is the first file loaded. The order of precedence for the loading of the configuration sources is: 1) appsettings.json file, 2) appsettings.{AltName}.json file, 3) Key-per-file directories, 4) Environment variables, and 5) Command Line arguments. As a result, if a JSON configuration file is configured with an alternate name, and is the most recently saved version of the JSON configuration file, the file with the alternate name will take precedence, which causes major errors during login.

Note the following considerations:

If a value already exists for the specified property, the write command overwrites the existing value. This is true regardless of whether the original value is plain text or encrypted.
If you are encrypting a value, the configuration file must remain in the location specified in the parameters for the write command. If the file is moved after the value is encrypted, the value cannot be decrypted by the utility or the supported application.

The write command is executed by appending parameters to the Hyland.Application.Settings.Utility.exe write command. The following parameters are available:

Parameter	Short Name	Description	Required
--applicationRoot	-a	The path to the directory that contains the application using the configuration file. For example: -a C:\repo\application	Yes
--file		The file name of the JSON configuration file. If the file is located in a subdirectory of the location specified in the --applicationRoot parameter, also include the relative path to the file. For example: --file config\appsettings.json	Yes
--property	-p	The name of the property to write. For nested properties, use a colon (:) delimiter. For example, where a property called masterDB contains a sub-property called ConnectionString, to which you want to write a value: -p masterDB:ConnectionString	Yes
--value	-v	The value to write.	Yes
--verbose		Sets the diagnostics logging level for the information returned by the command. If this parameter is included in a command, detailed logging information is returned. If this parameter is not included in a command, logging information is returned only if an error occurs.	No
--force	-f	Forces the creation of the property if it is not already present in the configuration file.	No
--encrypt		Encrypts the property value written to the configuration file. If this parameter is included in a command, the specified value is encrypted, and the encrypted value is written to the file. If this parameter is not included in a command, the specified value is written to the file in plain text.	No

Required and optional parameters are added to the write command line, as shown in this example:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application --file config\appsettings.json -p masterDB:ConnectionString -v Server=myServer;Database=myDB; --verbose --force --encrypt

Note:

If a parameter value includes spaces, you must enclose the entire value in quotation marks. For example, if using the -a parameter to point to the path C:\Program Files\App, the full parameter and value would be: -a "C:\Program Files\App"

If the --force parameter is not used, the property passed in must already exist in the file. If the --force parameter is used, then the property passed in does not need to already exist.

If the property exists, --force will write the property value to the configuration file. If the property does not exist, --force will create the configuration sections for the property value and write the value to the configuration file.

If you are using the write command to write a property value in an array, you must use the proper index to refer to an element in the array. See Writing and Reading Array Elements for more information.