Updater

Type: User Documentation 06-Mar-2024 | Edvardas Rimkus

In this article

Updater v4 is available in R4 systems since 22 April 2020. Url: /af-updater.

Updater main task is:

  • Download and Apply - updates from an external source to the system.
  • Generate and Deploy - generate local changes and deploy generated and applied updates further to target sources.

Updater main data are transactions which consist of the following information:

  • ID - positive ID's need to be unique across all systems, uniqueness is defined by namespace. There is also negative IDs, which are called local change or hotfix. These will be described later in the article.
  • Namespace - object/transaction namespace.
  • Group - namespace group, defined on each namespace.
  • Type - there are 12+ Appframe object types that are versioned, for ex: Articles, Scripts, WinProjects and etc.. You can check the complete list on sviw_Deploy_Version
  • Name - Object name
  • Version - specific object version
  • Version Created - shows localized UTC dates when the version was originally created.
  • Description and Issue ID - taken from version info. Can be changed manually.
  • Status
    • 0 Ready - downloaded, and ready to be applied.
    • 1 Applied - applied from an external source.
    • 2 Error - apply failed with the following error.
    • 3 Deployed - update is exposed to external systems.
    • 4 On Hold - the update was ready before but set to on hold for some reason. This status will not allow further deployment.
    • 5 Skip - update status can be marked as skip. This means the update will not be applied, deployed, not available for download. Use this very carefully.
  • Generated - indicates if an update was generated locally or came from the external system.
  • Main SQL Update - stores actual change that is used when applying.
  • SQL Before - typically is used to run something before the main SQL.
  • SQL Check - will run after SQL Before, in most cases, it is checking if DDL trigger is enabled on the system or such object version existence on the system.
  • SQL After - will run after Main SQL Update.  If SQL after the statement fails, it will not set an update with the error.

Updater articulates around namespaces and created versions. During development work, it is therefore fundamental to correctly maintain the namespace attribute against each type of update-able Pims objects, specifically:

  • Database objects - namespace auto-assigned by naming convention
  • Assemblies - /af-assemblies, namespace assigned manually.
  • Articles - /appddesigner, setting tab, manually
  • Reports - in win Reports form, manually
  • Code Modules - /code-modules on each code module, settings tab manually
  • Web site scripts - /sitesetup, manually
  • Web site styles - /sitesetup, manually
  • Web site templates - /sitesetup, manually
  • SQL Templates - will try to parse namespace from the name, but can be assigned manually on a table.
  • Bundles - /af-bundle, manually
  • Data Change scripts - data change scripts are tied with a specific table so the namespace is auto-assigned depending on table namespace. Data change can be added in /af-dbmanager, choosing a specific table and pressing the button  Add data change.

Download and Apply (Updates tab)

An Updater instance gets updates from a pre-configured source environment. The app allows us to download deployed updates from such a source and apply them to the target environment it operates within.

The updates grid is showing only not applied updates ( downloaded and containing the error).


You can include skipped updates

When pressing on buttons Download or Apply it will show dialogs where the user needs to select specific namespaces to do an action.

In the dropdown menu, users can download or apply all not suspended namespaces.

Download

The counter is showing how many updates could be downloaded to the system. By pressing it will show the dialog.


Deleting downloaded updates does not reset sequence numbers and those updates will NOT BE downloaded again.

The grid in the dialog will contain only external namespaces. The counter on a button is showing how many actual updates it will download.

The Updater will only download new updates (updates with higher positive update ID in selected namespace than the newest on your service and lower negative IDs than on your service for hotfixes)

If a namespace is suspended you will see the default message, the message can be set in the namespaces article.

Apply

The counter is showing how many updates are downloaded and could be applied to the system. By pressing it will call the sstp_Deploy_Apply procedure and run each downloaded SQL within the transaction.

It is strongly recommended to update system namespaces (AF group) before applying product updates.

Each transaction will run in the sequence defined by Version Created, this is very important, not to change it.

If it fails to apply it will inform which object version failed. You may need to fix SQL, change the status to 0 Ready, and retry again

It is strongly recommended to reload app domain using /api/debug/cache article red button after applying AF namespace updates.

You can also set the status to 4 - On-Hold. Which means the update will be ignored by the apply procedure. ( This will change the update's sequence.)


Generate and Deploy (Changes tab)

This tab default where the clause is set to show only generated updates. Applied and deployed can be also included by pressing corresponding checkboxes.

  • Include Applied - applied updates from the external system, which are not yet deployed.
  • Include Deployed - exposed updates, you can deploy applied and generated updates.


Pressing the Generate & Deploy button will show a dialog containing all system namespaces. On an ideal case Generate & Deploy button should be clicked which would generate and deploy all not suspended namespaces.

In this dialog, namespaces need to be explicitly selected for needed action.

Counters are showing the number of namespaces that would be generated/deployed.

Duplicate updates, except database objects and change scripts, will be marked as skipped when deploying.

Local objects (ltbl, ltlv, lviw, lstp) will have only their first version deployed, all later versions will be set to 5 - Skipped during deployment.

Note: Deploy suspended means that only deploy is suspended, namespace versions would be still generated.


Hotfixes & local changes

Updates are typically peer-reviewed, cross-checked, and undergo thorough testing in RELEASE environments. Despite this due diligence and quality assurance processes, issues might still arise, requiring often urgent fixes. While such fixes would be included in the next monthly release together with the next changes, they might need to be made more immediately available to implementation teams & customers, in the current same month when underlying issues are found and fixed. 
 
Hotfixes are generated with negative IDs. The environment where a hotfix is implemented determines its nature, distinguishing hotfixes (local updates) from normal updates (updates downloaded from a source and locally applied). Except for data change scripts, this is the reason why any downloaded and applied newer version of an object for which a local hotfix was created will override such hotfix.

Note: you should be careful when making hotfixes. They will be applied in the same sequence defined by the VersionCreated field as regular updates. So after making a hotfix, you need to make sure, that is present in the original database.
Local changes & hotfixes will be auto skipped when the same object will be downloaded from the source. Except for data change scripts.
Each Hot Fix shall be notified to AST for immediate automated regression testing in STAGE.

Updater Win version

The  Sys.Database.DbUpdater Win application, available in Win Projects, has been introduced to update solutions without direct access to update servers.

This app is created only to download updates.


How to manage updates in client environments

Monthly Pims product version updates and any urgent hotfixes in between new monthly releases can be listened to from a suitable Pims RELEASE source environment by any relevant client environment, such as the local testing environment of a client Pims instance.

Irrespective of the nature of the client instance ("product version" or "customized solution"), updates shall be downloaded and applied first into a client sandbox or test environment.


SQL Before

SQL before can be used to change update status according to some predefined conditions. For example, you don't want to apply the update if some conditions are true or you might want to inform the user to do some manual actions before applying.

IF Object_ID('atbl_Namespace_Table1') IS NOT NULL
BEGIN
    SET @status = 1; --Applied
    SET @message = 'This update is set as applied because it already exists.';
END
SQL
IF EXISTS (SELECT * FROM atbl_Namespace_Table1)
BEGIN
    --DELETE FROM atbl_Namespace_Table1
    SET @status = 2; --error
    SET @message = 'Check SQL Before. Consider deleting all table data before applying this update.';
END
SQL
Local customizations

There is a possibility to mark specific objects as customized and define SQL Before when updates are downloaded.

Objects can be marked as customized in /af-updater-customizations article.

In this article, you can define [SQLBefore] field. Also, you can pick up snippets from lookup.

A default template is 'af_default' and it can't be deleted or renamed. It will be used as the default value when adding customization. This template can be edited on your solution as well. By default, it will set transaction as applied and skip it when Apply is pressed.

You can have your own templates under the same article and define your own strategy what to gave in SQL Before.

Default actions will silently skip it, you could have status set to error and inform you when customized object will be updated.

Warnings

In an environment where the AD domain name matches the update source name, use a different name for the update source. E.g. if the AD domain is contoso.com, the update source should not be contoso.com, but update.contoso.com.

A namespace is auto-assigned for DB objects and SQL templates, for the rest of items like Web Articles, Code Modules and etc. you need explicitly set the namespace for them. It can be done in the corresponding developer applications. 

When using SSMS make sure you have setting enabled "Prevent saving changes that require the table to be re-created". Otherwise, changes might not be compatible with Updater. Microsoft article

Troubleshooting / Applying updates from SQL Server Management Studio

In case if during updates process website goes down due to a failed update, it is possible to skip that update and continue applying updates using SQL Server Management Studio (SSMS).

First you need to find the failed update by running:

SELECT * FROM stbl_Deploy_Transactions WITH (NOLOCK) WHERE Status = 2

After noting down the PrimKey of the failed update you can set it as skipped using following query:

UPPDATE stbl_Deploy_Transactions
SET [Status] = 5
WHERE  PrimKey = '[PrimKey from previous query]'

After this you can launch update apply procedure:

EXEC sstp_Deploy_Apply @Namespaces = '[namespace_id],[namespace_id]'

To apply all framework updates you can run the following code:

DECLARE @NamespaceIDS AS NVARCHAR(MAX)
SELECT @NamespaceIDS = COALESCE(@NamespaceIDS + ',' + cast(ID AS VARCHAR(30)), cast(ID AS VARCHAR(30))) FROM stbl_deploy_namespaces WITH (NOLOCK) WHERE [Group] = 1

EXEC sstp_deploy_apply @Namespaces = @NamespaceIDS




In this article