Schema-cli

Configuration JSON schema

The Create command receives a full configuration JSON template template as an input parameter. All the other commands may work with just the configuratorInformation section.

For all the upcoming sections, settings that are used by an action are marked as (✅) while unused settings are marked as (⬜️).

Configurator Information

The Configurator Information section contains information needed to connect to the (Azure) SQL database server. This section is used for all actions. The Delete, Upgrade, ImportData, and ExportData actions need only this section to run. The Upgrade action may need additional settings though.

JSON template:

Parameters:

Name Data type Required? Default value
databaseServerName string true localhost
databaseLoginUserName string false
databaseLoginUserPassword string false

Corresponding configuration on UI:

Index Name
(1) databaseServerName
(2) databaseLoginUserName
(3) databaseLoginUserPassword

database-configuration

Examples

  • If your database server is installed on localhost, you can leave the databaseServerName setting empty:

    Corresponding configuration on UI:

    configuration-template-1

  • If you want to connect to the SQL server using Windows integrated authentication, you need to leave databaseLoginUserName and databaseLoginUserPassword settings empty:

    Corresponding configuration on UI:

    configuration-template-2

  • If you are using an SQL server installed on another machine which is always the case in production, you need to specify the SQL server name and credentials (or leave the credentials empty if you are using Windows integrated authentication):

    Corresponding configuration on UI:

    configuration-template-3

General information configuration

JSON template:

Parameters:

Name Data type Required? Default value Create Replicate
clientName string true
defaultLanguage string true
tenantId string true ⬜️
passwordAdmin string true ⬜️
safewhereAdminIdleTimeout string false 20 ⬜️

Corresponding configuration on UI:

Index Name
(1) tenantId
(2) clientName
(3) defaultLanguage
(4) passwordAdmin
(5) safewhereAdminIdleTimeout

general-information-configuration-1

Examples

  • Input settings for an instance:

    Corresponding configuration on UI:

general-information-configuration-1

Instance's database connection configuration

JSON template:

Enable multi subnet fail over parameters

Name Data type Required? Default value Create Replicate
isMultiSubnetFailover boolean false false ⬜️

Corresponding configuration on UI:

Index Name
(1) isMultiSubnetFailover

general-configuration-multisubnetfailover

Example

Corresponding configuration on UI:

database-connection-configuration-1

Database configuration parameters

Name Data type Required? Default value Create Replicate
schema string false ⬜️
server string false localhost ⬜️
loginUserName string false false ⬜️
loginPassword string false false
dbAuthenticationType Enum = {SQLServerAuthentication, WindowsAuthentication} false SQLServerAuthentication ⬜️
  • When the dbAuthenticationType setting is "SQLServerAuthentication", processing rules for the other optional settings are:

    Index Name Required? Description
    (1) schema false If you leave it empty, it will take the value of tenantConfiguration.tenantId
    (2) server false If you leave it empty, it will take the value of configuratorInformation.databaseServerName
    (3) dbAuthenticationType true Must be "SQLServerAuthentication" in this case
    (4) loginUserName false A username is generated automatically using the schema name as the prefix
    (5) loginPassword false A random password is generated automatically

    Their respective settings on the UI are:

tenant-database-configuration

The respective configuration on the UI is:

[![database-connection-configuration-2](http://docs.safewhere.com/wp-content/uploads/2020/04/database-connection-configuration-21.png)](http://docs.safewhere.com/wp-content/uploads/2020/04/database-connection-configuration-21.png)
  • When the dbAuthenticationType setting is "WindowsAuthentication", processing rules for the other optional settings are:

    Index Name Required? Description
    (1) schema false If you leave it empty, it will take the value of tenantConfiguration.tenantId
    (2) server false If you leave it empty, it will take the value of configuratorInformation.databaseServerName
    (3) dbAuthenticationType true Must be "WindowsAuthentication" in this case
    (4) loginUserName false Specify the username for the selected database server. For domain users, it should be in the format "domain\\user". If the user’s login credentials do not exist in the database, they will be added automatically.
    (5) loginPassword true Enter the password of the above user.

    database-connection-configuration-3

    An example of the tenant database configuration using Windows authentication is:

    The respective configuration on the UI is:

    database-connection-configuration-3-1

Audit configuration parameters

Name Data type Required? Default value Create Replicate
providerType Enum = {SQLDatabase, MongoDb, CosmosDb} true SQLDatabase ⬜️
host string false ⬜️
loginName string false ⬜️
password string false ⬜️
port number false 1433 ⬜️
connectionTimeout number false 60 ⬜️
cosmosDBMaxIdleTime number false 120000 ⬜️
  • When the providerType setting is "SQLDatabase", processing rules for the other optional settings are:

    Index Name Required? Description
    (1) providerType true Must be "SQLDatabase" in this case
    (2) host false You don't need to specify value for it. The default value is always taken from databaseConfiguration.server of the tenant database configuration
    (3) loginName false You don't need to specify value for it. The default value is always taken from databaseConfiguration.loginUserName of the tenant database configuration
    (4) password false You don't need to specify value for it. The default value is always taken from databaseConfiguration.loginPassword of the tenant database configuration
    (5) port false You can specify a value for it or leave it empty. The default value is 1433
    (6) connectionTimeout false You can specify a value for it or leave it empty. The default value is 60 seconds

    tenant-audit-database-configuration

    An example of the configuration section using SQL database is:

  • When the providerType setting is "MongoDb", processing rules for the other optional settings are:

    Index Name Required? Description
    (1) providerType true Must be "MongoDb" in this case
    (2) host false You don't need to specify value for it. The default value is always taken from databaseConfiguration.server of the tenant database configuration
    (3) loginName false Specify the username for the selected database server. For domain users, it should be in the format domain\\user. If the user’s login credentials do not exist in the database, they will be added automatically. If you leave it empty, the default value will be taken from databaseConfiguration.loginUserName of the tenant database configuration
    (4) password false Enter the password of the above user. If you leave it empty, the default value will be taken from databaseConfiguration.loginPassword of the tenant database configuration
    (5) port false You can specify a value for it or leave it empty. The default value is 27017
    (6) connectionTimeout false You can specify a value for it or leave it empty. The default value is 60 seconds

    tenant-audit-database-configuration-mongodb

    An example of the configuration Audit log using MongoDb database as below:

  • When the providerType setting is "CosmosDb", processing rules for the other optional settings are:

    Index Name Required? Description
    (1) providerType true Must be "CosmosDb" in this case
    (2) host true Specify the HOST of an Azure Cosmos DB account
    (3) loginName true Specify the USERNAME of Azure Cosmos DB account
    (4) password true Specify the PRIMARY PASSWORD or SECONDARY PASSWORD of the account
    (5) port false You can specify a value for it or leave it empty. The default value is 10255
    (6) cosmosDBMaxIdleTime false You can specify a value for it or leave it empty. The default value is 120000 seconds

    tenant-audit-database-configuration-cosmosdb

    To use the CosmosDB, you must create a CosmosDB account on the Azure portal. Navigate to the Connection String tab to get the required information for the Identify Configurator.

    tenant-audit-database-configuration-cosmosdb-azure

    An example of the configuration Audit log using Cosmos database as below:

Session state configuration parameters

Name Data type Required? Default value Create Replicate
sessionStateMode Enum = [InProc, SQLServer] false InProc ⬜️
timeOut number false 60 ⬜️

Corresponding configuration on UI:

Index Name
(1) sessionStateMode
(2) timeOut

tenant-session-state-configuration

Example
  • Input value InProc for sessionStateMode:

    Corresponding configuration on UI:

    database-connection-configuration-5

  • Input value SQLServer for sessionStateMode :

    Corresponding configuration on UI:

    database-connection-configuration-6

Instance's IIS configuration

JSON template:

Parameters:

Name Data type Required? Default value Create Replicate
generateDefaultValues boolean false true ⬜️
serverIpAddress string false 127.0.0.1 ⬜️
port number value 443 ⬜️
domainName string true ⬜️
siteName string true ⬜️
sitePool string true ⬜️
adminPool string true ⬜️
runtimePool string true ⬜️
servicePool string true ⬜️
bindCertificate boolean false true ⬜️
requireServerNameIndication boolean false false ⬜️
useHttpSecurityHeaders boolean false true ⬜️

Corresponding configuration on UIs:

Index Name
(1) generateDefaultValues

tenant-database-configuration-auto-generate-values

Index Name
(1) serverIpAddress
(2) port
(3) domainName
(4) bindCertificate
(5) requireServerNameIndication
(6) siteName
(7) sitePool
(8) adminPool
(9) runtimePool
(10) servicePool

tenant-iis-configuration

Index Name
(1) useHttpSecurityHeaders

tenant-iis-configuration-security-headers

Example

  • If generateDefaultValues is true, based on tenantId some settings will auto-generate such as domainName, siteName, sitePool, adminPool, runtimePool, servicePool and default values of bindCertificate, requireServerNameIndication are true:

    Corresponding configuration on UI:

    iis-configuration-1

  • If generateDefaultValues is false, you need to specify values for IIS settings:

    Corresponding configuration on UI:

    iis-configuration-2

  • Set value of useHttpSecurityHeaders to true, if you want to use recommended security headers:

    Corresponding configuration on UI:

    iis-configuration-3

  • Otherwise, set value of useHttpSecurityHeaders to false:

    Corresponding configuration on UI:

    iis-configuration-4

Instance's certificates configuration

JSON template:

Trusted Root CA certificate configuration

Parameters:

Name Data type Required? Default value Create Replicate
pathToTrustedRootCertificateToImport string false ⬜️

Corresponding configuration on UI:

Index Name
(1) pathToTrustedRootCertificateToImport

tenant-ca-certifcates-configuration

Example

Input value for pathToTrustedRootCertificateToImport:

Corresponding configuration on UI:

certificate-configuration-9

SSL certificate configuration parameters

Name Data type Required? Default value Create Replicate
certificateSetupType Enum = {UseDefaultCertificate, UseAutoGeneratedCertificate, ImportFromFile, SelectFromServerCertificateStore} false UseDefaultCertificate ⬜️
sslDomainName string false "safewhere.local" ⬜️
filePath string false ⬜️
password string false ⬜️
certificateThumbprintInStore string false ⬜️

Corresponding configuration on UI:

Index Name
(1.1) certificateSetupType = UseDefaultCertificate
(1.2) certificateSetupType = UseAutoGeneratedCertificate
(1.3) certificateSetupType = ImportFromFile
(1.4) certificateSetupType = SelectFromServerCertificateStore
(2) sslDomainName
(3) filePath
(4) password
(5) certificateThumbprintInStore

tenant-ssl-certifcate-configuration

Example
  • If certificateSetupType = UseDefaultCertificate, you don't need to input values for other settings:

    Corresponding configuration on UI:

    certificate-configuration-1

  • If certificateSetupType = UseAutoGeneratedCertificate, you need to input value for sslDomainName:

    Corresponding configuration on UI:

    certificate-configuration-2

  • If certificateSetupType = ImportFromFile, you need to input values for filePath and password:

    Corresponding configuration on UI:

    certificate-configuration-3

  • If certificateSetupType = SelectFromServerCertificateStore, you need to input values for certificateThumbprintInStore:

    Corresponding configuration on UI:

    certificate-configuration-4

Signing certificate configuration parameters

Name Data type Required? Default value Create Replicate
certificateSetupType Enum = {UseDefaultCertificate, UseAutoGeneratedCertificate, ImportFromFile, SelectFromServerCertificateStore, UseAzureKeyVault} false UseDefaultCertificate ⬜️
filePath string false ⬜️
password string false ⬜️
certificateThumbprintInStore string false ⬜️
keyVaultMode string false Certificate ⬜️
azureTenantId string false ⬜️
applicationClientId string false ⬜️
applicationClientSecret string false ⬜️
azureKeyVaultUrl string false ⬜️
certificateName string false ⬜️
keyName string false ⬜️
base64Certificate string false ⬜️

Corresponding configuration on UI:

Index Name
(1.1) certificateSetupType = UseDefaultCertificate
(1.2) certificateSetupType = UseAutoGeneratedCertificate
(1.3) certificateSetupType = ImportFromFile
(1.4) certificateSetupType = SelectFromServerCertificateStore
(1.5) certificateSetupType = UseAzureKeyVault
(2) filePath
(3) password
(4) certificateThumbprintInStore
(5.1) keyVaultMode = Certificate
(5.2) keyVaultMode = Key
(6) azureTenantId
(7) applicationClientId
(8) applicationClientSecret
(9) azureKeyVaultUrl
(10) certificateName
(11) keyName
(12) base64Certificate

tenant-signing-certifcates-configuration

azure-key-vault-configuration-certificate

azure-key-vault-configuration-key

Example
  • If certificateSetupType = UseDefaultCertificate, you don't need to input values for other settings:

    Corresponding configuration on UI:

    certificate-configuration-5

  • If certificateSetupType = UseAutoGeneratedCertificate, you don't need to input values for other settings:

    Corresponding configuration on UI:

    certificate-configuration-6

  • If certificateSetupType = ImportFromFile, you need to input values for filePath and password:

    Corresponding configuration on UI:

    certificate-configuration-7

  • If certificateSetupType = SelectFromServerCertificateStore, you need to input values for certificateThumbprintInStore:

    Corresponding configuration on UI:

    certificate-configuration-8

  • If certificateSetupType = UseAzureKeyVault and keyVaultMode = Certificate, you need to input values for azureTenantId, applicationClientId, applicationClientSecret, azureKeyVaultUrl and azureKeyVaultKeyName:

    Corresponding configuration on UI:

    create-instance-configure-select-azurekeyvault

    create-instance-configure-certificate-using-azurekeyvault-certificate

  • If certificateSetupType = UseAzureKeyVault and keyVaultMode = Key, you need to input values for azureTenantId, applicationClientId, applicationClientSecret, azureKeyVaultUrl, azureKeyVaultKeyName and base64Certificate:

    Corresponding configuration on UI:

    create-instance-configure-select-azurekeyvault

    create-instance-configure-certificate-using-azurekeyvault-key