Release notes Thinkwise Deployment Center 3.1.0

Hello everyone,

In this release, we introduce a new manifest schema version that will be used by the Software Factory in platform version 2023.2. We have added the possibility to specify more than one upgrade path for database products from the same version. We have also fixed some regressions that were introduced in version 3.0.0.​​

Download the Thinkwise Deployment Center 3.1.0 here.

Contents

Manifest schema version 3

This version of the Deployment Center introduces support for a new manifest schema version. The main reason to create this new version is to change the default encoding used for scripts from windows-1252 to utf-8, but we also took the opportunity to change some other things. The Software Factory will start using this new schema in the 2023.2 platform release.

Model property for Application products

Some properties that describe information about the model of an application have been moved to a model property:

schema: 2
products:
  - type: "Application"
    projectId: "MY_APPLICATION_MODEL"
    version: "3.0.0"
    metaVersion: "2022.1"

This must be specified in manifest schema version 3 as:

schema: 3
products:
  - type: "Application"
    model:
      id: "MY_APPLICATION_MODEL"
      version: "3.0.0"
      metaVersion: "2023.2"

schema: 3
products:
  - type: "IAM"
    # The IAM/SF/Upcycler types use an implicit value for model:id and consider model:version to be the same as model:metaVersion.
    # Because of that, there is no model property, and only version has to be specified.
    version: "2023.2"

The defaultDatabaseName property has been moved

The defaultDatabaseName property can be used to let the Deployment Center know what the default name of the application database should be.

In schema version 2, this property was part of the install package:

schema: 2
products:
  - type: "Application"
    # etc.
    packages:
      - type: "Install"
        path: "Install"
        defaultDatabaseName: "MY_APPLICATION_DATABASE"

It was only used during the installation flow and (using an appsetting for the GUI) as the default name for a script variable that can be used during the post model synchronization script.

In schema version 3, the property has been moved to the product level:

schema: 3
products:
  - type: "Application"
    defaultDatabaseName: "MY_APPLICATION_DATABASE"
    # etc.

When using schema version 3, the Deployment Center will also try to use this value during the upgrade, hotfix, and syncModel (for selecting an IAM database) flows.

See (GUI) Also use defaultDatabaseNAme during upgrade/hotfix/syncModel for more information.

Package type keys

In manifest schema version 2, the packages property inside an IAM/SF/Upcycler/Application product used to be an array. Each item had to specify a type to indicate what kind of package it was:

schema: 2
products:
  - type: "Application"
    # etc.
    packages:
      - type: "Install"
        path: "Install"
      - type: "Upgrade"
        path: "Upgrade"
        supportedVersions:
          # etc.
      - type: "Hotfix"
        path: "Hotfixes"

This makes it seem like a product can support multiple packages of the same type, but the Deployment Center code never accounted for that. It was an array due to a technical limitation in the code which read the manifest. This has since been changed. To avoid confusion, the type property has now been turned into specific property keys on the packages property.

schema: 3
products:
  - type: "Application"
    # etc.
    packages:
      # Type values are turned into property keys.
      install:
        path: "Install"
      upgrade:
        path: "Upgrade"
        supportedVersions:
          # etc.
      hotfix:
        path: "Hotfixes"
      syncModel:
        path: "MetaModel"

SyncModel package type

In manifest schema version 2, the package that described to the Deployment Center that a product had the ability to synchronize the meta model into an IAM was inferred by checking if a MetaModel directory was present as the sibling to the directory where an Install or Upgrade package was located.

This was not ideal because it added a hidden feature of sorts to the manifest, and the path to the directory containing the package could not be changed. In schema version 3, the syncModel package can be added to a database product and its path must be explicitly specified like in the other packages:

schema: 3
products:
  - type: "Application"
    # etc.
    packages:
      syncModel:
        path: "MetaModel"

The syncModel package is considered optional for SF, Upcycler and Application product types, in the sense that an install or upgrade package will not break if it is not specified. They will simply skip the IAM synchronization step during deployment, which may or may not be what you want, depending on your deployment strategy.

For the IAM product type, it is considered mandatory to have a syncModel package. This is because every IAM is expected to have at least its own model synchronized to it.

Renamed supportedVersions version property to upgradesFrom

You could specify an upgrade path from version 1.0.0 to 2.0.0 for a database application in schema version 2 as follows:

schema: 2
products:
  - type: "Application"
    projectId: "MY_APPLICATION_MODEL"
    version: "2.0.0"
    metaVersion: "2022.1"
    # etc.
    packages:
      - type: "Upgrade"
        path: "Upgrade"
        supportedVersions:
          # Upgrade from version 1.0.0
          - version: "1.0.0"
          # to 2.0.0
            upgradesTo: "2.0.0"
          # using the scripts contained in directory 2.0.0 (relative to the package path, which itself is relative to the manifest location)
            path: "2.0.0"

This remains practically the same in schema version 3, but the version property did not immediately convey to users that it was the source version from which the upgrade could be performed.

To clarify what the property's relation is to the upgradesTo property, it has been renamed to upgradesFrom. version will remain available as an alias to upgradesFrom to make it easier to manually migrate manifests from schema version 2, but we recommend using upgradesFrom from now on.

schema: 3
products:
  - type: "Application"
    model:
      id: "MY_APPLICATION_MODEL"
      version: "2.0.0"
      metaVersion: "2023.2"
    # etc.
    packages:
      upgrade:
        path: "Upgrade"
        supportedVersions:
          - upgradesFrom: "1.0.0"
            upgradesTo: "2.0.0"
            path: "2.0.0"

Encoding

In platform version 2022.1, the Software Factory has been changed to generate scripts in utf-8 encoding instead of the previously used windows-1252 encoding. To support this, manifest schema version 2 was updated to include the ability to specify the encoding to use for scripts in several places of an IAM/SF/Upcycler/Application product.

The default had to remain windows-1252 for backwards compatibility reasons. This meant that the Software Factory also had to specify that utf-8 had to be used when it generated a deployment package:

schema: 2
products:
  - type: "Application"
    # Override default script encoding for the entire product.
    encoding: "utf-8"
    # etc.

In schema version 3, this will no longer be needed, because the default has been changed to utf-8. Any scripts generated by a Software Factory older than 2022.1 can still be specified as using windows-1252 by using the encoding on the package or supportedVersion level:

schema: 3
products:
  - type: "Application"
    model:
      id: "MY_APPLICATION_MODEL"
      version: "3.0.0"
      metaVersion: "2023.2"
    # Encoding does not have to be specified as utf-8 since that is now the default.
    packages:
      upgrade:
        path: "Upgrade"
        supportedVersions:
          - upgradesFrom: "1.0.0"
            upgradesTo: "2.0.0"
            # 1.0.0 to 2.0.0 was generated by a 2021.3 Software Factory and thus uses windows-1252 encoding.
            # 
            encoding: "windows-1252"
            files:
              - "1.0.0/020_Upgrade.sql"
              # etc.
          - upgradesFrom: "2.0.0"
            upgradesTo: "3.0.0"
            # 2.0.0 to 3.0.0 was generated by a 2023.2 Software Factory so the scripts use the new utf-8 default.
            path: "3.0.0"

Full examples

schema: 3
products:
  - type: "Application"
    model:
      id: "MY_APPLICATION_MODEL"
      version: "2.0.0"
      metaVersion: "2023.2"
    dependencies:
      - "CompatibilityLevel140"
    defaultDatabaseName: "MY_APPLICATION_DATABASE"
    packages:
      install:
        path: "Install"
      upgrade:
        path: "Upgrade"
        supportedVersions:
          - upgradesFrom: "1.0.0"
            upgradesTo: "2.0.0"
            path: "2.0.0"
      hotfix:
        path: "Hotfixes"
      syncModel:
        path: "MetaModel"
  - type: "IAM" # "SF", "Upcycler"
    version: "2023.2"
    dependencies:
      - "CompatibilityLevel140"
    defaultDatabaseName: "MY_IAM" # "MY_SF", "MY_UPCYCLER"
    packages:
      install:
        path: "Install"
      upgrade:
        path: "Upgrade"
        supportedVersions:
          - upgradesFrom: "2023.1"
            upgradesTo: "2023.2"
            path: "2023.2"
      hotfix:
        path: "Hotfixes"
      syncModel:
        path: "MetaModel"

New

Multiple upgrade paths

The Deployment Center now considers the supportedVersions section of the upgrade package type a graph instead of a sequential path. This makes it possible to specify more than one upgrade path from the same source version.

We do still recommend that upgrades should be performed sequentially in the order they were developed. However, if you have created an upgrade from one major version to the next while skipping any version in-between, you will no longer have to maintain a separate manifest for that.

The summary screen will also mention which path the Deployment Center is going to use:

Example

Given the following manifest:

schema: 3
products:
  - type: "Application"
    model:
      id: "MY_APPLICATION_MODEL"
      version: "3.0.0"
      metaVersion: "2023.2"
    dependencies:
      - "CompatibilityLevel140"
    packages:
      upgrade:
        path: "Upgrade"
        supportedVersions:
          - upgradesFrom: "1.0.0"
            upgradesTo: "1.1.0"
            path: "1.1.0"
          - upgradesFrom: "1.1.0"
            upgradesTo: "1.2.0"
            path: "1.2.0"
          - upgradesFrom: "1.2.0"
            upgradesTo: "1.2.1"
            path: "1.2.1"
          - upgradesFrom: "1.2.1"
            upgradesTo: "2.0.0"
            path: "2.0.0"
          - upgradesFrom: "2.0.0"
            upgradesTo: "2.0.1"
            path: "2.0.1"
          - upgradesFrom: "2.0.1"
            upgradesTo: "3.0.0"
            path: "3.0.0"
          - upgradesFrom: "1.0.0"
            upgradesTo: "2.0.0"
            path: "1.0.0_to_2.0.0"
          - upgradesFrom: "2.0.0"
            upgradesTo: "3.0.0"
            path: "2.0.0_to_3.0.0"

The upgrade package contains the following steps/edges:

• 1.0.0 -> 1.1.0
• 1.1.0 -> 1.2.0
• 1.2.0 -> 1.2.1
• 1.2.1 -> 2.0.0
• 2.0.0 -> 2.0.1
• 2.0.1 -> 3.0.0
• 1.0.0 -> 2.0.0
• 2.0.0 -> 3.0.0

The target version of the application is 3.0.0, so if the database that is being upgraded reports it is currently on version 1.0.0, there are three possible paths for the upgrade. The Deployment Center will always pick the path with the fewest steps, so in this case it will use (2 steps):

• 1.0.0 -> 2.0.0
• 2.0.0 -> 3.0.0

Instead of (5 steps):

• 1.0.0 -> 1.1.0
• 1.1.0 -> 1.2.0
• 1.2.0 -> 1.2.1
• 1.2.1 -> 2.0.0
• 2.0.0 -> 3.0.0

Or (6 steps):

• 1.0.0 -> 1.1.0
• 1.1.0 -> 1.2.0
• 1.2.0 -> 1.2.1
• 1.2.1 -> 2.0.0
• 2.0.0 -> 2.0.1
• 2.0.1 -> 3.0.0

Allow install into empty database

The Deployment Center will now allow empty databases as valid targets for the installation flow of IAM/SF/Upcycler/Application products. This can be helpful when deploying to Azure, because you will be able to create a database using the desired tier beforehand.

It will consider the database empty if it meets all of the following requirements:

• It contains no objects other than ones added by Microsoft.

• It is not a database with a reserved name (e.g. 'master', 'model' etc.).

• It is not otherwise a system database.

Changed

(GUI) Also use defaultDatabaseName during upgrade/hotfix/syncModel

When using a schema version 3 manifest, the Deployment Center GUI will now pre-fill the database selection drop-down lists with the value of defaultDatabaseName if a database with that name is available on the connected server.

So, given the following manifest:

schema: 3
products:
  - type: "IAM"
    defaultDatabaseName: "THINKWISE_IAM"
    # etc.
  - type: "SF"
    defaultDatabaseName: "THINKWISE_SF"

And starting an upgrade flow for the Software Factory:

And selecting to synchronize the meta model into an IAM:

Install and upgrade flow step order changed

The installation and upgrade flow for SF/Upcycler/Application  products did not use the order specified by the flow. For example, the upgrade flow previously used the following order:

1. Sync model into IAM

2. Upgrade database

3. Apply hotfixes

However, the order as specified by the flow was actually:

1. Upgrade database
2. Apply hotfixes
3. Sync model into IAM

Which was the intended order.

This was caused by the deployment step copying the steps order from the review/confirmation step. This applied a grouping of the steps and caused the IAM "group" to come before the others.

This grouping was introduced at a time where the IAM installation and upgrade flows also tried to allow configuring other components, such as Indicium. Because we do not allow this anymore, the grouping had become useless. Since it also influenced the deployment order in an unexpected way, we have removed it.

Fixed

DefaultDatabaseName property not read in manifest schema version 2

When we worked on version 3.0.0 of the Deployment Center to prepare for the introduction of schema version 3, changes were made to the way manifests were being read.

This accidentally broke the defaultDatabaseName property when using schema version 2. This has now been fixed, so it is once again used during the installation flow.

Indicium Basic installation is not detected when upgrading

We have fixed an issue where a selected IIS app was not being detected as an Indicium Basic installation when upgrading or reconfiguring.