invantive documentation
Invantive Support ForumsAanmelden / Inschrijven

Settings.xml

[!warning] Verouderd vanaf release 28.0 Dit onderwerp beschrijft het XML-formaat van het instellingenbestand en de overgang naar het JSON-formaat. Ondersteuning voor het XML-formaat eindigt met Invantive UniversalSQL release 28.0, gepland rond het begin van 2028. Dit onderwerp en alles wat erin staat, kan daarna worden verwijderd; Settings beschrijft het formaat dat overblijft.

Tot en met release 26.0 werden virtuele databases gedefinieerd met het bestand settings.xml en andere bestanden die aan het patroon settings*.xml voldoen. Vanaf release 27.0 leest Invantive UniversalSQL databasedefinities in plaats daarvan uit settings*.json, zoals beschreven in Settings. Bestaande XML-bestanden worden automatisch gemigreerd.

De concepten zijn ongewijzigd: het zoekpad, het samenvoegen van meerdere bestanden en de betekenis van databasegroepen, databases en datacontainers zijn in beide formaten gelijk. Alleen de notatie verschilt.

Waarom het formaat is veranderd

Het XML-formaat dateert van 2009 en kent twee problemen die een formaatwijziging oplost.

  • Gereedschap: het lezen of genereren van een instellingenbestand vereist XPath en/of XSLT. De meeste talen verwerken JSON zonder extra bibliotheken. Het genereren van een instellingenbestand per klant of per omgeving wordt eerder een kwestie van tekstsjablonen dan van XML.
  • Verouderde elementen: het XML-formaat bevat veel geschiedenis over de concepten van databaseconnectiviteit. Veel elementen worden niet meer ondersteund of zijn niet langer relevant. Het JSON-formaat gebruikt de huidige concepten, dus wat u leest is wat de term betekent.

Welk formaat wordt gebruikt

Release Behaviour
26.0 en eerder settings*.xml wordt gebruikt; een settings*.json-bestand wordt genegeerd.
26.1 (BETA van 27.0) settings*.json wordt gebruikt; een identiek benoemd settings*.xml wordt genegeerd en gebruikt om de JSON-variant te maken.
27.0 settings*.json wordt gebruikt; een identiek benoemd settings*.xml wordt genegeerd en gebruikt om de JSON-variant te maken.
28.0 settings*.json wordt gebruikt; het XML-formaat wordt niet langer ondersteund of gebruikt om de JSON-variant te maken.

Release 26.1 is de BETA van release 27.0 en gedraagt zich er identiek aan: in de Invantive-releasenummering duidt een even tweede getal een productierelease aan en een oneven tweede getal de BETA van de volgende productierelease. Release 27.0 is daarom de eerste productierelease die settings*.json leest.

Voorrang geldt per bestandsnaam. Een settings-acme.json vervangt settings-acme.xml, terwijl een settings-other.xml zonder JSON-tegenhanger nog steeds wordt gelezen en gemigreerd.

Migratie

Er is moeite gedaan om de migratie zo eenvoudig mogelijk te maken.

De eerste keer dat een product van release 27.0 een settings*.xml-bestand leest waarvoor geen identiek benoemd .json-bestand bestaat, maakt het ernaast een functioneel identiek JSON-bestand aan. Het XML-bestand blijft ongewijzigd. Verouderde eigenschappen worden genegeerd.

Bestanden die door automatische detectie zijn geproduceerd (settings-discovery*.xml) worden nooit gemigreerd, omdat ze aan een specifieke hoofdrelease zijn gekoppeld.

Alleen het discovery-bestand van de draaiende release, settings-discovery-<version>.json in de databasesmap, wordt gelezen. Elk discovery-bestand in het XML-formaat, settings-discovery*.xml van welke versie ook, en elke settings-discovery-<version>.json van een andere versie wordt overgeslagen: elke release schrijft zijn eigen bestand, en een oudere zou dezelfde databases nogmaals onder oudere namen vermelden. Alle overige settings*.xml- en settings*.json-bestanden worden gelezen.

Bewerk na migratie het JSON-bestand. Wijzigingen in het XML-bestand werken vanaf release 26.1 niet meer.

Een gemigreerd bestand bevat een migration-lid dat vastlegt van welk bestand het is afgeleid, door wie, op welke machine, wanneer en met welke productversie. Het lid ontbreekt in een instellingenbestand dat met de hand is geschreven, dus de aanwezigheid ervan geeft aan dat een bestand is gemigreerd:

{ "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"
  }
}

XML-bestanden verwijderen

Wanneer een omgeving alleen release 27.0 of nieuwer gebruikt, kunnen alle settings*.xml-bestanden veilig worden verwijderd zodra het JSON-formaatbestand bestaat. Bewaar een XML-bestand alleen zolang een product van release 26.0 of eerder dezelfde map leest, met de kanttekening dat zo'n product elke wijziging in het JSON-bestand negeert.

Verschillen in notatie

Beide formaten beschrijven exact dezelfde databases. De verschillen zijn:

  • <connection> wordt database genoemd (enkelvoud) of databases (meervoud).
  • <database> wordt dataContainer genoemd (enkelvoud) of dataContainers (meervoud).
  • De elementen <database> en <credentials> delen één dataContainers-array, waarin het lid kind aangeeft welke van de twee een datacontainer is, met de waarde dataContainer of credentials.
  • Herhaalde elementen worden arrays met een meervoudige naam: <group> wordt groups, <provider> wordt providers, <attribute> wordt attributes en <failover> wordt failovers.
  • Ledennamen zijn consequent camelCase, dus PasswordLabel in XML is passwordLabel in JSON.

Structuur

De instellingenbestanden hebben de volgende structuur in XML-formaat; de volledige specificatie is beschikbaar in invantive-databases.xsd in de bijlagen.

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

Een database bestaat uit een of meer datacontainers. Datacontainers kunnen worden gedefinieerd met behulp van:

Met EditabilityType als een van:

  • Auto,
  • ReadOnly,
  • Hidden,

Met AuthenticationModeType één van:

  • Default,
  • Database,
  • Application.

De volgende elementen zijn uit de structuur weggelaten omdat ze verouderd zijn, maar XML-bestanden die deze bevatten worden nog steeds geaccepteerd:

  • type fail-over-knoop,
  • Invantive Web Service-datacontainers,
  • attributes on connection: encryptedDataCacheConnectionString, encryptedDataDictionaryConnectionString, PasswordLabel, PasswordHint, UserLogonCodeLabel, UserLogonCodeHint, passwordMode, userLogonCodeMode, defaultUserLogonCode, defaultPassword, enableRequestLogging,
  • kenmerk op database: encryptedConnectionString,
  • kenmerk op settings: sqlTrace, enableRequestLogging, forcedefault.

Voorbeelden

De volgende databasedefinitie biedt een PostgreSQL-database, de cloud-API's van het Nederlandse parlement en de Exact Online- en Salesforce-datacontainers van een door Invantive Cloud beheerde database. Dezelfde definitie in JSON-formaat wordt getoond 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>