invantive documentation
Invantive Support ForumsLog In / Sign Up

Settings.xml

[!warning] Obsolete as of release 28.0 This topic describes the XML format of the settings file and the transition to the JSON format. Support for the XML format ends with Invantive UniversalSQL release 28.0, scheduled around the start of 2028. This topic and everything in it can then be discarded; Settings describes the format that remains.

Up to and including release 26.0, virtual databases were defined using the file settings.xml and other files matching the pattern settings*.xml. Starting at release 27.0, Invantive UniversalSQL reads database definitions from settings*.json instead, as described in Settings. Existing XML files are migrated automatically.

The concepts are unchanged: the search path, the merging of multiple files and the meaning of database groups, databases and data containers are the same in both formats. Only the notation differs.

Why the Format Changed

The XML format dates from 2009 and carries two problems that a format change resolves.

  • Tooling: reading or generating a settings file requires XPath and/or XSLT. Most languages parse JSON without additional libraries. Generating a settings file per customer or per environment becomes a text templating exercise rather than an XML one.
  • Obsolete elements: the XML format carries a lot of history on the database connectivity concepts. Many elements are no longer supported or relevant. The JSON format uses the current concepts, so what you read is what the term means.

Which Format is Used

Release Behaviour
26.0 and earlier settings*.xml is used; a settings*.json file is ignored.
26.1 (BETA of 27.0) settings*.json is used; an identically named settings*.xml is ignored and used to create the JSON variant.
27.0 settings*.json is used; an identically named settings*.xml is ignored and used to create the JSON variant.
28.0 settings*.json is used; the XML format is no longer supported or used to create the JSON variant.

Release 26.1 is the BETA of release 27.0 and behaves identically to it: in the Invantive release numbering an even second number denotes a production release and an odd second number the BETA of the next production release. Release 27.0 is therefore the first production release reading settings*.json.

Precedence applies per file name. A settings-acme.json supersedes settings-acme.xml, while a settings-other.xml without a JSON counterpart is still read and migrated.

Migration

An effort has been made to make the migration as easy as possible.

The first time a release 27.0 product reads a settings*.xml file for which no identically named .json file exists, it creates that functionally identical JSON file next to it. The XML file is left unchanged. Obsoleted properties are ignored.

Files produced by automatic discovery (settings-discovery*.xml) are never migrated, since they are associated with a specific major release.

Only the discovery file of the running release, settings-discovery-<version>.json in the databases folder, is read. Every discovery file in the XML format, settings-discovery*.xml of whichever version, and every settings-discovery-<version>.json of another version is skipped: every release writes its own, and an older one would list the same databases a second time under older names. All other settings*.xml and settings*.json files are read.

After migration, edit the JSON file. Changes made to the XML file no longer take effect from release 26.1 onwards.

A migrated file carries a migration member recording which file it was derived from, by whom, on which machine, when and with which product version. The member is absent on a settings file that was written by hand, so its presence is what identifies a file as migrated:

{ "migration":
  { "sourceFileNamePath": "C:\\Users\\john.doe\\invantive\\settings.xml"
  , "migratedBy": "ACME\\john.doe"
  , "migratedOn": "WS0001"
  , "migrationDate": "2026-08-05T08:15:00.4608219Z"
  , "migratedUsing": "27.0.1.1234"
  }
}

Removing the XML Files

When an environment only uses release 27.0 or newer, all settings*.xml files can safely be removed once the JSON format file exists. Keep an XML file only for as long as a product of release 26.0 or earlier reads the same folder, bearing in mind that such a product ignores every change made to the JSON file.

Differences in Notation

Both formats describe exactly the same databases. The differences are:

  • <connection> is termed database (singular) or databases (plural).
  • <database> is termed dataContainer (singular) or dataContainers (plural).
  • The <database> and <credentials> elements share one dataContainers array, in which the member kind states which of the two a data container is, using the value dataContainer or credentials.
  • Repeated elements become arrays with a plural name: <group> becomes groups, <provider> becomes providers, <attribute> becomes attributes and <failover> becomes failovers.
  • Member names are consistently camelCase, so PasswordLabel in XML is passwordLabel in JSON.

Structure

The settings files have the following structure in XML format; the full specification is available in invantive-databases.xsd in the attachments.

classDiagram
direction TB

class settings:::classDiagram {
  +VersionUpdatedBy: string
  +VersionUpdatedOn: string
  +VersionUpdateDate: dateTime
  +version: string
  +default: string
}

class group:::classDiagram {
  +name: string
  +comment: string
  +shortDescription: string
  +description: string
  +id: string
  +sortingOrder: int
  +createdBy: string
  +createdOn: string
  +creationDate: dateTime
  +iconResourceName16: string
  +iconResourceName32: string
}

class connection:::classDiagram {
  +name: string
  +id: string
  +description: string
  +shortDescription: string
  +comment: string
  +sqlTrace: boolean = false
  +starred: boolean = false
  +sortingOrder: int
  +authentication: AuthenticationModeType
  +IconResourceName16: string
  +manual: boolean = false
  +createdBy: string
  +createdOn: string
  +creationDate: dateTime
  +lastUsedDate: dateTime
  +forceNative: boolean = false
  +dataCacheConnectionString: string
  +iuidSource: string
  +dataDictionaryConnectionString: string
}

class provider:::classDiagram {
  +createdBy: string
  +createdOn: string
  +creationDate: dateTime
  +comment: string
  +order: int
  +file: string
  +class: string
}

class attribute:::classDiagram {
  +code: string
  +value: string
}

class credentials:::classDiagram {
  +database: string
  +server: string
  +datacontainers: string
  +order: int
  +createdBy: string
  +createdOn: string
  +creationDate: dateTime
  +description: string
  +comment: string
  +defaultUserLogonCode: string
  +userLogonCodeMode: EditabilityType
  +defaultPassword: string
  +PasswordLabel: string
  +PasswordHint: string
  +UserLogonCodeLabel: string
  +UserLogonCodeHint: string
  +passwordMode: EditabilityType
}

class database:::classDiagram {
  +connectionString: string
  +AllowConnectionStringRewrite: boolean = true
  +AllowConnectionPooling: boolean = true
  +order: int
  +createdBy: string
  +createdOn: string
  +creationDate: dateTime
  +description: string
  +comment: string
  +alias: string
  +provider: string
  +defaultUserLogonCode: string
  +userLogonCodeMode: EditabilityType
  +defaultPassword: string
  +PasswordLabel: string
  +PasswordHint: string
  +UserLogonCodeLabel: string
  +UserLogonCodeHint: string
  +passwordMode: EditabilityType
}

settings "1" *-- "0..*" group : group
group "1" *-- "0..*" connection : connection

connection "1" *-- "0..*" provider : provider
provider "1" *-- "0..*" attribute : attribute

connection "1" *-- "0..*" database : database

connection "1" *-- "0..*" credentials : credentials

A database consists of one or more data containers. Data containers can be defined using:

With EditabilityType being one of:

  • Auto,
  • ReadOnly,
  • Hidden,

With AuthenticationModeType one of:

  • Default,
  • Database,
  • Application.

The following elements have been excluded from the structure since they are obsolete, but XML files containing these will still be accepted:

  • fail over node type,
  • Invantive Web Service data containers,
  • attributes on connection: encryptedDataCacheConnectionString, encryptedDataDictionaryConnectionString, PasswordLabel, PasswordHint, UserLogonCodeLabel, UserLogonCodeHint, passwordMode, userLogonCodeMode, defaultUserLogonCode, defaultPassword, enableRequestLogging,
  • attribute on database: encryptedConnectionString,
  • attribute on settings: sqlTrace, enableRequestLogging, forcedefault.

Examples

The following database definition provides a PostgreSQL database, the cloud APIs of the Dutch parliament as well as the Exact Online and Salesforce data containers of an Invantive Cloud managed database. The same definition in JSON format is shown in Settings.

<?xml version="1.0" encoding="utf-8"?>
<settings 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 version="5"
>
  <group 
   name="ACME" 
   sortingOrder="0"
   shortDescription="ACME"
  >
    <connection 
     name="ACME" 
     sortingOrder="10"
     authentication="Database"
    >
      <database
       order="10"
       alias="db"
       provider="PostgreSql"
       userLogonCodeMode="Hidden"
       passwordMode="Hidden"
       connectionString="Server=host.acme.eu;Database=xxacme;User Id=xxacme_user;Password=secret;CommandTimeout=3600"
       AllowConnectionStringRewrite="false"
      />
      <database
        order="20"
        alias="twk"
        provider="TweedeKamerNl"
        AllowConnectionPooling="false" />
      <credentials
       order="30"
       description="Exact Online and Salesforce database"
       database="acme-exact-online-salesforce"
       datacontainers="*"
       userLogonCodeMode="Hidden"
       passwordMode="Hidden"
       defaultUserLogonCode="john.doe@acme.eu"
       defaultPassword="secret"
      />        
    </connection>
  </group>
</settings>