invantive documentation
Foros de Soporte de InvantiveIniciar Sesión / Registrarse

Settings.xml

[!warning] Obsoleto desde la versión 28.0 Este tema describe el formato XML del archivo de ajustes y la transición al formato JSON. El soporte del formato XML finaliza con la versión 28.0 de Invantive UniversalSQL, prevista para alrededor del inicio de 2028. Este tema y todo su contenido pueden descartarse entonces; Settings describe el formato que permanece.

Hasta la versión 26.0 inclusive, las bases de datos virtuales se definían con el archivo settings.xml y otros archivos que coincidían con el patrón settings*.xml. A partir de la versión 27.0, Invantive UniversalSQL lee las definiciones de bases de datos desde settings*.json, como se describe en Settings. Los archivos XML existentes se migran automáticamente.

Los conceptos no cambian: la ruta de búsqueda, la combinación de varios archivos y el significado de los grupos de bases de datos, las bases de datos y los contenedores de datos son los mismos en ambos formatos. Solo cambia la notación.

Por qué cambió el formato

El formato XML data de 2009 y presenta dos problemas que un cambio de formato resuelve.

  • Herramientas: leer o generar un archivo de ajustes requiere XPath y/o XSLT. La mayoría de los lenguajes analizan JSON sin bibliotecas adicionales. Generar un archivo de ajustes por cliente o por entorno pasa a ser un ejercicio de plantillas de texto en lugar de uno de XML.
  • Elementos obsoletos: el formato XML conserva mucho historial sobre los conceptos de conectividad de bases de datos. Muchos elementos ya no son compatibles ni relevantes. El formato JSON utiliza los conceptos actuales, así que lo que lee es lo que significa el término.

Formato que se utiliza

Release Behaviour
26.0 y anteriores Se utiliza settings*.xml; un archivo settings*.json se ignora.
26.1 (BETA de 27.0) Se utiliza settings*.json; un settings*.xml con el mismo nombre se ignora y se usa para crear la variante JSON.
27.0 Se utiliza settings*.json; un settings*.xml con el mismo nombre se ignora y se usa para crear la variante JSON.
28.0 se utiliza settings*.json; el formato XML ya no se admite ni se utiliza para crear la variante JSON.

La versión 26.1 es la BETA de la versión 27.0 y se comporta de forma idéntica a ella: en la numeración de versiones de Invantive, un segundo número par indica una versión de producción y un segundo número impar indica la BETA de la siguiente versión de producción. Por lo tanto, la versión 27.0 es la primera versión de producción que lee settings*.json.

La precedencia se aplica por nombre de archivo. Un settings-acme.json sustituye a settings-acme.xml, mientras que un settings-other.xml sin equivalente en JSON se sigue leyendo y migrando.

Migración

Se ha hecho un esfuerzo para que la migración sea lo más sencilla posible.

La primera vez que un producto de la versión 27.0 lee un archivo settings*.xml para el que no existe un archivo .json con el mismo nombre, crea junto a él ese archivo JSON funcionalmente idéntico. El archivo XML no se modifica. Las propiedades obsoletas se ignoran.

Los archivos generados por el descubrimiento automático (settings-discovery*.xml) nunca se migran, ya que están asociados a una versión principal específica.

Solo se lee el archivo de descubrimiento de la versión en ejecución, settings-discovery-<version>.json, en la carpeta de bases de datos. Se omite todo archivo de descubrimiento en formato XML, settings-discovery*.xml de cualquier versión, y cada settings-discovery-<version>.json de otra versión: cada versión escribe el suyo, y uno anterior listaría las mismas bases de datos por segunda vez con nombres antiguos. Se leen todos los demás archivos settings*.xml y settings*.json.

Después de la migración, edite el archivo JSON. Los cambios realizados en el archivo XML ya no surten efecto a partir de la versión 26.1.

Un archivo migrado incluye un miembro migration que registra de qué archivo se derivó, por quién, en qué equipo, cuándo y con qué versión del producto. El miembro no está presente en un archivo de ajustes escrito a mano, por lo que su presencia es lo que identifica a un archivo como migrado:

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

Eliminación de los archivos XML

Cuando un entorno solo utiliza la versión 27.0 o una posterior, todos los archivos settings*.xml pueden eliminarse de forma segura una vez que exista el archivo en formato JSON. Conserve un archivo XML solo mientras un producto de la versión 26.0 o anterior lea la misma carpeta, teniendo en cuenta que dicho producto ignora cualquier cambio realizado en el archivo JSON.

Diferencias en la notación

Ambos formatos describen exactamente las mismas bases de datos. Las diferencias son:

  • <connection> se denomina database (singular) o databases (plural).
  • <database> se denomina dataContainer (singular) o dataContainers (plural).
  • Los elementos <database> y <credentials> comparten una matriz dataContainers, en la que el miembro kind indica cuál de los dos es un contenedor de datos, mediante el valor dataContainer o credentials.
  • Los elementos repetidos se convierten en matrices con nombre en plural: <group> pasa a ser groups, <provider> pasa a ser providers, <attribute> pasa a ser attributes y <failover> pasa a ser failovers.
  • Los nombres de los miembros son coherentes: camelCase, de modo que PasswordLabel en XML equivale a passwordLabel en JSON.

Estructura

Los archivos de ajustes tienen la siguiente estructura en formato XML; la especificación completa está disponible en invantive-databases.xsd en los anexos.

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

Una base de datos consta de uno o más contenedores de datos. Los contenedores de datos pueden definirse mediante:

  • database: uno por cada contenedor de datos definido localmente;
  • credentials: uno, varios o todos los contenedores de datos en una base de datos gestionada por Invantive Cloud (mediante Invantive Credentials Server).

Con EditabilityType siendo uno de los siguientes:

  • Auto,
  • ReadOnly,
  • Hidden,

Con AuthenticationModeType uno de los siguientes:

  • Default,
  • Database,
  • Application.

Los siguientes elementos se han excluido de la estructura por estar obsoletos, pero los archivos XML que los contengan seguirán siendo aceptados:

  • tipo de nodo de conmutación por error,
  • Contenedores de datos de Invantive Web Service,
  • attributes on connection: encryptedDataCacheConnectionString, encryptedDataDictionaryConnectionString, PasswordLabel, PasswordHint, UserLogonCodeLabel, UserLogonCodeHint, passwordMode, userLogonCodeMode, defaultUserLogonCode, defaultPassword, enableRequestLogging,
  • atributo en database: encryptedConnectionString,
  • atributo en settings: sqlTrace, enableRequestLogging, forcedefault.

Ejemplos

La siguiente definición de base de datos proporciona una base de datos PostgreSQL, las API en la nube del parlamento neerlandés, así como los contenedores de datos de Exact Online y Salesforce de una base de datos gestionada de Invantive Cloud. La misma definición en formato JSON se muestra en 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>