Preparing input parameters in a JSON file

You can create a JSON file (.json) to provide input parameters for one-touch Domino setup.

About this task

The JSON input data is organized into top-level JSON objects each corresponding to a specific component. Each top-level object can contain nested objects. For example, the serverSetup object contains the object server that includes all server-related parameters, the object network that includes all network-related parameters, and so on.

Note: The JSON file must be saved in UTF-8 format without a byte order mark (BOM) at the beginning of the file. Because UTF-8 is a superset of the ASCII character set, any file with purely printable ASCII characters is also a valid UTF-8 file.
The following tables describe the supported JSON objects and parameters for the following top-level objects:
  • serverSetup, used to set up servers and described in Table 1.
  • IDVault, used to set up an ID vault and described in Table 2.
  • appConfiguration, used to configure applications and described in Table 3.
  • autoConfigPreferences, used to specify preferences for running one-touch setup and described in Table 4.
An X in the First server or Additional server column indicates that a parameter pertains to that type of server setup. An asterisk (*) next to an X indicates a required parameter.

The JSON file must contain valid JSON as described at json.org.

  • Value types are string unless otherwise noted. Specify strings in quotes.
  • Boolean values are indicated by true or false without quotes.
  • Numeric values are specified without quotes except when they function as strings, such as notes.ini values.
  • To apply a default value, specify null without quotes or omit the parameter.
Table 1. JSON parameters for server setup
Parameter First server Additional server Default Description

serverSetup:

Server setup parameters:

          server:

Server parameters:

                    type

X* X* Server type. Must be either:
  • "first" for first server in a Domino domain.
  • "additional" for additional servers in the domain.

                    name

X* X* Server common name, for example, "Adminserver"

                    domainName

X* X* Domino domain name

                    title

X X none Server title

                    password

X X none Server ID password

                    minPasswordLength

X X 5 Minimum password length for all passwords. (Integer)

                     useExistingServerID

X false Value of true uses the existing server ID specified by IDFilePath. Default is to create a new server ID that defaults to server.id in the Domino data directory.

                    IDFilePath

X X* Path of server ID file. On Docker, the ID must be relative to the container.

                    serverTasks

X X "Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr" A comma-separated list of server tasks that run on the server.

                    additionalServerTasks

X X A comma-separated list of additional tasks to run on the server. Use this to add to the default list of server tasks.

          network:

Network parameters:

                    hostName

X* X* DNS host name

                    enablePortEncryption

X X true Value of true enables port encryption. (Boolean)

                    enablePortCompression

X X true Value of true enables port compression. (Boolean)

          org:

Organization parameters:

                    countryCode

X X none Organization country code

                    orgName

X* X* Organization name

                    certifierPassword

X* Organization certifier password

                    orgUnitName

X X none Organization unit name

                    orgUnitPassword

X X none Organization unit password

                   useExistingCertifierID

X false Value of true uses the existing certifier ID specified by certifierIDFilePath. Default is to create a new certifier ID that defaults to cert.id in the Domino data directory.

                   certifierIDFilePath

X none Path of certifier ID used when useExistingCertifierID is true. On Docker, the ID must be relative to the container.

                   useExistingOrgUnitID

X false Value of true uses the existing organization unit certifier ID specified by orgUnitIDFilePath. Default when an orgUnitName is specified is to create a new organization unit certifier ID that defaults to oucert.id in the Domino data directory.

                   orgUnitIDFilePath

X none Path of organization unit certifier ID used when useExistingOrgUnitID is true. On Docker, the ID must be relative to the container.

          admin:

Administrator parameters:

                    firstName

X none Administrator first name

                    middleName

X none Administrator middle name or initial

                    lastName

X* Administrator last name

                    password

X* Administrator ID password

                    IDFilePath

X* Administrator ID file path. On Docker, the ID must be relative to the container.

                    useExistingAdminID

X false Value of true uses the existing server ID specified by IDFilePath. Default is to create a new administrator ID and save it as IDFilePath.

                    CN

X* Administrator common name, for example, "Bill Ranney."

          notesINI:

notes.ini parameters: (All values must be strings)

                   <any name>

X X none Any notes.ini setting can be defined when using JSON input. Use with caution when defining notes.ini settings that might be independently defined by server setup; the value defined here overrides any value previously defined by setup.

          security:

Security parameters:

                    ACL:

Default database ACL entries for all new databases:

                              prohibitAnonymousAccess

X X true Value of true gives Anonymous users No Access. (Boolean)

                              addLocalDomainAdmins

X X true Value of true gives the LocalDomainAdmins group entry Manager access. (Boolean)

          autoregister:

Parameters to register additional servers automatically. If not specified, you register additional servers manually.

                    count

X 0 Number of servers to register (Integer)

                    IDPath

X none Specifies the directory in which to put generated server ID files. The directory must already exist. On Docker, the ID must be relative to the container.

                    pattern

X none Specifies a pattern for the names of generated server ID files. Pattern must contain a single '#' character which will be replaced with the numbers 0, 1, ... up to count-1.

For example, if count is 3 and pattern is "mailserver#", the resulting ID files are named mailserver0.id, mailserver1.id, mailserver2.id.

          existingServer:

Parameters specifying an existing server to use to replicate the directory and other databases:

                    CN

X* Server common name, for example, "Adminserver"

                    hostNameOrIP

X none Server DNS host name or IP address
Table 2. JSON parameters for ID vault setup
Parameter First server Additional server Default Description
IDVault X ID Vault parameters. All are Required if IDVault is specified.

          name

X Vault name. Specify as "O=<vaultname>" for example, "O=DemoVault". You must include the "O=" prefix. If you omit it, you can get an 'Entry not found in index' error when the vault creation is attempted.

          description

X Vault description

          IDFile

X Vault ID file

          IDPassword

X Vault ID file password

          path

Vault database path. This is an optional parameter and we recommend you not specify it since it can be derived from the name parameter. If you do specify it, the directory portion of the path must be IBM_ID_VAULT and the filename portion of the path must match the name parameter, without the O= prefix, for example, "IBM_ID_VAULT/DemoVault.nsf"

          passwordReset:

Vault password reset parameters:

                    helpText

X Help text for users who forget their passwords

          securitySettingsPolicy:

Security Settings policy parameters:

                    name

X Security Settings policy name

                    description

X Security Settings policy description

          masterPolicy:

Master policy parameters:

                    description

X Master policy description
Table 3. JSON parameters for application configuration
Parameter First server Additional server Default Description

appConfiguration:

X X Application configuration parameters:

   notesINI:

notes.ini parameters: (All values must be strings.)

       <any-name>

X X Any notes.ini variables may be defined here as an alternative to specifying them within serverSetup properties.

   databases

X X An array of databases (applications). The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the database data to be created or updated.

      action

X* X* Specify "create" to create a new database, or "update" to update an existing database.

      filePath

X* X* Database file path.

      title

X X Database title.

      templatePath

X X Database template file path. Required when action is "create".

      signUsingAdminp

X X false When set true, an adminp request is issued to sign all design documents using the server's ID.

      ACL

X X Database ACL parameters:

            roles

X X An array of role names. Example: [ "SpecApprover", "SpecAuthor" ]

            ACLEntries

An array of ACL entries. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the data for an ACL entry.

                name

X* X* ACL entry name in hierarchical format (e.g. "adminserver/sherlock"). The name can be specified in canonical format (e.g. "CN=adminserver/O=sherlock") but it needn't be because one-touch setup automatically canonicalizes the name.

               level

X* X* Access level. Must be one of: "noAccess", "depositor", "reader", "author", "editor", "designer", "manager"

               type

X X "unspecified" Access type. Must be one of: "unspecified", "person", "server", "personGroup", "serverGroup", "mixedGroup"

               canCreateDocuments

X X false Named entity can create documents.

               canDeleteDocuments

X X false Named entity can delete documents.

               canCreatePersonalAgent

X X false Named entity can create private agents.

               canCreatePersonalFolder

X X false Named entity can create personal folders and views.

               canCreateSharedFolder

X X false Named entity can create shared folders and views

               canCreateLSOrJavaAgent

X X false Named entity can create LotusScript and Java agents

                isPublicReader

X X false Named entity can read public documents.

                isPublicWriter

X X false Named entity can write public documents.

                canReplicateOrCopyDocuments

X X false Named entity can replicate and copy documents.

                roles

X X false An array of roles granted to the named entity. Example: [ "SpecApprover", "SpecAuthor" ]

      documents

X X An array of documents within the database. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the document data to be created or updated.

         action

X* X* Specify "create" to create a new document, or "update" to update an existing document.

         findDocument

X X Required when action is "update", the properties in this object define one or more items used to find the document to update. The document must have all of those items with the exact values as specified. For example:
"findDocument": 
  { "Type": "Server", 
  "ServerName": "CN=adminserver/O=sherlock" 
} 

         computeWithForm

X X false Compute/Validate the document against its form. If true, form logic such as input validation formulas and default value formulas execute, possibly modifying the document (for example, adding additional items).

         items

X X Document items. These can be in a simple format or "canonical" format. You may specify some items in simple format and some in canonical format. The canonical format is required for setting any of the item flags. The simple formats are shown first, then the canonical format. The supported data types are text, number, text list, and number list.

            "<item-name>": "<item-value>"

X X Simple format for text item.

             "<item-name>": <item-value>

X X Simple format for number item. Note there are no quotes around the value.

              "<item-name>": [ "v1", "v2" ]

X X Simple format for text list item. Array may contain one or more items (two shown here).

              "<item-name>": [ 1, 2 ]

X X Simple format for number list item. Note there are no quotes around the values. Array may contain one or more items (two shown here).

             "<item-name>":

X X Canonical format for item:

                  "type"

X X Item data type. Optional; may be deduced from JSON data type as with the simple formats above. If specified, must be one of: "text", "number".

                  "value"

X X For type "text", must be either a single string or an array of strings. For type "number", must be a single number or an array of numbers.

                   "names"

X X false Item contains names.

                  "readers"

X X false Readers item used to determine who can read document.

                  "authors"

X X false Authors item used to determine who can edit document.

                  "protected"

X X false Item is protected.

                  "sign"

X X false Item is part of document signature computation if document is signed.

                   "encrypt"

X X false Item is encrypted if document is encrypted.

                 "nonSummary"

X X false Item is not a summary item. By default, items are summary items.

      agents

X X An array of agents within the database. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the information on the agent to be processed.

         name

X* X* Agent name.

         action

X* X* Action(s) to perform on agent. Value may be a single string or an array of strings. Valid values are:
  • "enable" - Enable the agent
  • "disable" - Disable the agent
  • "sign" - Sign the agent with the server ID
  • "run" - Run the agent
Table 4. JSON parameters for one-touch setup preferences
Parameter First server Additional server Default Description
autoConfigPreferences: One-touch setup preferences

   deleteInputFileAfterProcessing

X X false If true, the input JSON file is deleted when processing is complete. This assures that confidential data such as passwords is not left on the file system. When using this option, be sure to have a backup copy of your JSON file in a secure location in case it is needed again.

   startServerAfterConfiguration

X X true If true, Domino starts after successful setup. If false, setup exits and does not start Domino.

   consoleLogOutput:

X X

      show

X X "errors" Specifies which one-touch setup output to write to console log. Possible values are "none", "errors", or "all".

      pauseOnErrorSeconds

X X 15 Time to pause (in seconds) before exiting when one-touch setup completes with error. Note that for certain errors that happen early in the setup process, there is no pause. You can always consult IBM_TECHNICAL_SUPPORT/autoconfigure.log for output.