Writing and Reading Array Elements - API Server - Foundation 23.1 - Foundation 23.1 - Ready - OnBase - Essential - Premier - Standard - external - Standard - Essential - Premier

API Server

Platform
OnBase
Product
API Server
Release
Foundation 23.1
License
Standard
Essential
Premier

The Hyland Application Settings Utility can write and read array elements, as well as encrypt and decrypt values within array elements.

Array indexing begins at zero, so an element at the n position in an array has an index of n-1. The following table lists common array scenarios and the appropriate index to use.

Scenario

Index

Creating a new array

When creating a new array, the element is added to the first position of the array.

The first element is in the n=1 position, and it has an index of 0.

Accessing an element in an existing array

An element in the n position has an index of n-1.

For example, the third element in an array (the n=3 position) has an index of 2.

Adding to an array

When adding an element to an array, the new element is added to the last position in the array.

For example, if an array has five elements and a new element is added, it is added to the sixth position (n=6), and it has an index of 5.

In the following example JSON configuration, the Certs array contains two elements, representing multiple Thumbprint properties. The first element in the array has an index of 0, and the second element has an index of 1.

In this example, the following write command can be used to encrypt and write the value myCertThumbprint to the first Thumbprint element:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application --file config\appsettings.json -p config:Certs[0]:Thumbprint -v myCertThumbprint --encrypt

Similarly, the following read command can be used to decrypt and return the value in the first Thumbprint element:

Hyland.Application.Settings.Utility.exe read -a C:\repo\application --file config\appsettings.json -p config:Certs[0]:Thumbprint --decrypt

In either command, you could use either Certs[0] or Certs:0 in the -p parameter to reference the first element in the Certs array and the Thumbprint property in that element. To write or read the values of any other array elements, update the array index number to point to the element you want to reference.

To create a new element in an array, you must use the --force parameter. In the previous JSON example, only indexes 0 and 1 exist, so the new element will be created with an index of 2. The following command demonstrates how to force-create and encrypt the value of myCertThumbprint in a new element in the array:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application --file config\appsettings.json -p config:Certs[2]:Thumbprint -v myCertThumbprint --force --encrypt

In all of the example commands above, Thumbprint is appended after the index reference to designate which parameter in the element is being set or retrieved, as an element can be a single field or a collection of fields. If a specific parameter within the referenced element is not designated while using the --force parameter, the entire element will be overwritten.