How to version your application model

[vikter (Viktor Ter)]

This guide explains and demonstrates how application model versioning works in ORIGAM, and what steps you need to take in order to collaborate effectively with other team members.

[!success]- Prerequisites for proceeding

Before proceeding, ensure you meet the following prerequisites:

• Database server installed
• ORIGAM Server installed
• ORIGAM Architect installed
• Project created in ORIGAM Architect

To maintain consistency across the development environment, the versions of all major components should be synchronized:

1. Application Model
2. Application Database
3. ORIGAM Server
4. ORIGAM Architect
5. Metamodel

Instructions for upgrading the ORIGAM Server, Architect and metamodel are provided in a separate article. This guide focuses on versioning your application models and their databases.

The purpose of versioning your models is to keep them aligned with the database and the development platform versions across all environments (such as development, testing, and production), especially when multiple team members are involved.

Model versioning ensures synchronization among all activities related to model and database development throughout the entire process, regardless of the number of contributors.

Versioning Basics

It is standard practice for version numbers to consist of three digits separated by periods, which represent:

• Major update
• Minor update
• Fix

To check the package versions, navigate to the Architect’s Packages tab, where you can see the versions of all packages included in your application project — both default and those created by you:

The initial version of your application package is 1.0.0 by default. If you examine the versions of existing default packages, you will notice that some, like Root or Security, have undergone several updates.

The Versioning Process

We recommend creating a new model version whenever the database (structure or content) is changed, which also involves creating a new deployment script.

The process is as follows:

1. Create a new deployment version.
2. Set that version as the current version.
3. Add a new deployment script.
4. Commit and push the changes in Git.

Follow these steps whenever you plan to make changes to your application that affect the database. This ensures consistency across all environments and for all collaborators.

New Version Creation

You can view your application’s deployment versions in the Architect’s Model Browser under your application’s package, in the Common / Deployment section:

Double-click on the version name (e.g. 1.0.0) to view its properties in the property editor:

The Name field holds the version name used in the model. You can either retain the numbering or add additional information, such as “1.1.0 version with Projects.”

The VersionString field contains a value that is checked against OrigamModelVersion database table when you open a package in the Architect. It is compared to determine if the model has the same version as the database or not.

A version’s content consists of deployment scripts that update the database’s structure or content, for example:

To create a new deployment version (a new version of your application’s model), right-click on your package’s name and select New / Deployment Version:

After filling in the Name and VersionString fields and saving it, you will have created a new version for your new deployment scripts:

Version Upgrade

After creating a new version, you must set it as the current version. Only then will any new deployment scripts be saved under that version, and all environments will be updated to it, or at least notified that a new version is available.

If this step is skipped, newly generated deployment scripts will be saved under the previous version (set as current) and will not be automatically executed which may result in version conflicts across all development environments.

To set the newly created version as the current version, use the Make Version Current button on the toolbar:

Alternatively, you can use Actions / Make Version Current after right-clicking on the version name in the Model Browser:

Once set, opening a package in Architect will compare the model version with the database and offer running any scripts if the model version is higher than the database version. This mechanism ensures the model and database versions are in sync.

Deployment scripts can also be executed automatically when the application starts. To enable this, change the OrigamSettings.config file for the Server. Set the following value in the Services section:

ExecuteUpgradeScriptsOnStart = True

This setting will execute the deployment scripts automatically without any notification. If set to False, no updates will be executed and the older version of the application will run, potentially causing conflicts, e.g. a screen will fail to open when you have added a new field in the model, but didn’t add it to the database.

When a new version is created and set as current, the following actions occur:

1. The Deployment Script Generator will automatically prompt to save new scripts to the current version:

2. The current version will be compared with the database when opening the project in Architect or running it in the Server.

3. The current version will display a different icon:

4. The dbo.OrigamModelVersion table in the database will be updated:

5. The file OrigamProjects\MyApplication\model\myapplication\.origam.Package will be modified: