Scope: managed applications, ordinary applications.
Applies to configurations based on Standard Subsystems Library.
Contains clarifications of requirements of other standards.
See the "Infobase version update" subsystem documentation $$$ on ITS website.
1. Main information about the library (main configuration)
2. Location of update handlers
3. Implementation of update handlers
4. Migration to new library versions
1. Main information about the library (main configuration)
1.1. When developing configurations based on libraries, each library must provide information about itself required for correct update of the infobase to a new configuration version:
- Name
- Version
- List of update handlers
- Dependencies on other libraries
This information is stored in a special common module of the library whose name must begin with InfobaseUpdate…
Example:
In TM 11 configuration, the update handlers module is called InfobaseUpdateTM
Explicitly list module names of all libraries used in the configuration in the ConfigurationSubsystemsOverridable common module as follows:
Procedure OnAddSubsystems(SubsystemsModules) Export
SubsystemsModules.Add("InfobaseUpdateTM");
EndProcedure
A similar module must also be defined for the main configuration.
When creating the InfobaseUpdate... common module, use the following template:
////////////////////////////////////////////////////////////////////////////////
// Updating an infobase <a library or a configuration>.
//
/////////////////////////////////////////////////////////////////////////////
#Region Public
////////////////////////////////////////////////////////////////////////////////
// Getting information about the library or configuration.
// Fills in main information about the library or main configuration.
// A library whose name matches the configuration name in metadata is defined as the main configuration.
//
// Parameters:
// Details - Structure - information about the library:
//
// Name - String - a library name, for example, "StandardSubsystems".
// Version - String - a 4-digit version, for example, "2.1.3.1".
//
// RequiredSubsystems - Array - names of other libraries (String), on which this library depend.
// Handlers for updating such libraries must be called earlier
// than handlers for updating this library.
// In case of circular dependencies or no dependencies,
// the order of calling update handlers is determined by the order of adding modules
// in the OnAddSubsystems procedure of the ConfigurationSubsystemsOverridable common module.
// DefferedHandlerExecutionMode - String - "Sequentially" - update handlers run
// sequentially in the interval from the infobase version number to the configuration version number
// inclusive or "Parallel" - a deffered handler after
// processing the first data batch passes control to another handler, once
// the last handler is executed, the cycle is repetead.
//
Procedure OnAddSubsystems(Details) Export
Details.Name = "<Library name>";
Details.Version = "XX.XX.XX.XX";
Details.RequiredSubsystems.Add("StandardSubsystems");
Details.DefferedHandlerExecutionMode = "Sequentially";
EndProcedure
////////////////////////////////////////////////////////////////////////////////
// Infobase update handlers.
// Adds infobase data update handlers to the list
// for all supported versions of the library or configuration.
// Called before updating infobase data to build an update plan.
//
// Parameters:
// Handlers - ValueTable - field details
// see in the InfobaseUpdate.NewUpdateHandlerTable procedure
//
// An example of adding a handler to the list:
// Handler = Handlers.Add();
// Handler.Version = "1.0.0.0";
// Handler.Procedure = "IBUpdate.MigrateToVersion_1_0_0_0";
// Handler.ExecutionMode = "Exclusive";
//
Procedure OnAddUpdateHandlers(Handlers) Export
// Handlers executed upon each infobase update
// Handlers executed upon migration to a specific version
// Handlers executed when filling in an empty infobase
EndProcedure
// Called before infobase data update handlers.
//
Procedure BeforeUpdateInfobase() Export
EndProcedure
// Called after completion of the infobase update.
//
// Parameters:
// PreviousVersion - String - a version before update. "0.0.0.0" for "empty" infobase.
// CurrentVersion - String - a version after the update.
// ExecutedHandlers - ValueTree - a list of executed update handlers
// grouped by a version number.
// OutputUpdatesDetails - Boolean - (return value) if True,
// a form with the update details is displayed. The default value is True.
// ExclusiveMode - Boolean - True if update was executed in the exclusive mode.
//
Procedure AfterUpdateInfobase(Val PreviousVersion, Val CurrentVersion,
Val CompletedHandlers, OutputUpdatesDetails, ExclusiveMode) Export
EndProcedure
//Called upon creating a spreadsheet document with changes in the application.
//
// Parameters:
// Template - SpreadsheetDocument - details of update of all libraries and configuration.
// The template can be supplemented or changed.
// See also the ChangeHistory common template.
//
Procedure OnPrepareUpdateDetailsTemplate(Val Template) Export
EndProcedure
// Allows you to override the infobase data update mode.
// For use in rare (exceptional) cases of migrations not provided in
// the standard procedure for defining the update mode.
//
// Parameters:
// DataUpdateMode - String - in the handler, you can assign one of the values:
// "InitialFilling" - if this is the first start of the empty base (data area);
// "VersionUpdate" - if this is the first start after updating the database configuration;
// "MigrationFromAnotherApplication" - if this is the first start after updating the database configuration,
// in which the main configuration name changed.
//
// StandardProcessing - Boolean - if False, the standard procedure
// of defining the update mode is not executed,
// the DataUpdateMode value is used instead.
//
Procedure OnDefineDataUpdateMode(DataUpdateMode, StandardProcessing) Export
EndProcedure
// Adds the handlers of migration from another application (with another configuration name) to the list.
// For example, to migrate between different similar configurations: standard -> prof -> corp.
// Called before the infobase update start.
//
// Parameters:
// Handlers - ValueTable - with columns:
// * PreviousConfigurationName - String - a name of the configuration to migrate from;
// or "*" if it must be executed while migrating from any configuration.
// * Procedure - String - a full name of the handler for migration from PreviousConfigurationName.
// For example, "InfobaseUpdateMEM.FillAccountingPolicy "
// must be an export procedure.
//
// Example of adding the handler to the list:
// Handler = Handlers.Add();
// Handler.PreviousConfigurationName = "TradeManagement";
// Handler.Procedure = "InfobaseUpdateMEM.FillAccountingPolicy";
//
Procedure OnAddApplicationMigrationHandlers(Handlers) Export
EndProcedure
// Called after all handlers for migration from another application (with a different configuration name) are executed,
// and before start of the infobase data update.
//
// Parameters:
// PreviousConfigurationName - String - a configuration name before migration.
// PreviousConfigurationVersion - String - a previous configuration name (before migration).
// Parameters - Structure -
// * ExecuteUpdateFromVersion - Boolean - True by default. If False,
// only required update handlers will be executed (with "*" version).
// * ConfigurationVersion - String - a version number after migration.
// By default, it is equal to the value of the configuration version in metadata properties.
// To execute, for example, all update handlers from the PreviousConfigurationVersion version,
// set the parameter value to PreviousConfigurationVersion.
// To execute all update handlers, set the value to "0.0.0.1".
// * ClearPreviousConfigurationInfo - Boolean - True by default.
// Set False if the previous configuration name matches a name of the current configuration subsystem.
//
Procedure OnCompleteApplicationMigration(Val PreviousConfigurationName,
Val PreviousConfigurationVersion, Parameters) Export
EndProcedure
#EndRegion
#Region Private
////////////////////////////////////////////////////////////////////////////////
// Filling in an empty infobase
////////////////////////////////////////////////////////////////////////////////
// Updating the infobase
#EndRegion
1.2. Handlers of infobase data update are used for additional data processing after the database configuration update:
- Initialization of new constants, attributes, attributes of new predefined items.
- Data transfer from obsolete metadata structures to new ones.
- New data generation
- $$$
1.3. The infobase data update handler consists of two parts:
-
Descriptive - informs when the handler is executed and where it is located in the configuration.
-
Programmatic - infobase data modification code as an update handler procedure.
You can add details of new handlers in the OnAddUpdateHandlers procedure by inserting a code snippet as follows:
Handler = Handlers.Add();
Handler.Version = "<version number>";
Handler.Procedure = "<full name of the export procedure>";
Handler.InitialFilling = {True|False};
Handler.ExecutionMode = {"Exclusive"|"Seamless"|"Deferred"};
This code adds a new row to the Handlers value table. The table row has the following fields:
Version (String) – a configuration version number. When updating to this version, the update procedure specified in the Procedure parameter must be called.
-
The configuration version number is specified in the "R.P.V.B" format (R – a major revision number; P – a minor revision number; V – a version number; B – a build number. If the next version cannot be defined, the next build number can be specified).
-
If an asterisk ("*") is specified as a version, the update handler must run upon every infobase update, no matter what the configuration version is. Handlers of this type are used to update service, system data (for example, update of built-in profiles and access groups).
-
If the Version property is not set, the InitialFilling property must be set to True (see below).
Procedure (String) – a procedure ID that contains a full path to the update handler.
For example, "Catalog.Currencies.FillCodeForSearch".
InitialFilling(Boolean) – if True, the handler will be called upon the first start of the empty infobase (version "0.0.0.0") created from the configuration distribution package file and not containing data.
These are handlers of initial infobase filling.
ExecutionMode (String) – possible values: "Exclusive", "Seamless", and "Deferred". If the property is not set, the handler is exclusive by default.
- Exclusive – if the update handler needs to be executed exclusively in case of no active user sessions, scheduled jobs, external connections, and connections through web services. Otherwise, the application version update is interrupted. For more information, see Restrictions on the use of exclusive mode of update handlers
Exclusive handlers are used to update data whose processing must be completed by the time users sign in the application. To reduce downtime (waiting for data processing), we recommend that you update large amounts of data in the deferred mode (see below).
Examples of exclusive handlers: processing a small amount of data of the current period, active product items, and other.
If at least one configuration update handler is exclusive, all seamless handlers (see below) are executed in the exclusive mode.
If the update handler is required (the Version property = "*" ), the Exclusive value must be set only when update handlers must programmatically determine whether the exclusive mode is required for its execution:- Such handler is called twice, the Parameters parameter of the Structure type is passed to it. The parameter has the ExclusiveMode (Boolean) property.
- Upon the first call in the test mode, the ExclusiveMode property contains False.
- The handler code must not modify the infobase data.
- If upon execution of the handler, you need to make changes to the infobase, the handler must set the property value to True and stop its execution.
- Upon the second call in the execution mode, the ExclusiveMode property contains True.
- Code handler can modify infobase data.
- Changing a property value in this case is ignored.
- Seamless – if the update handler must not be executed exclusively: with active user sessions, scheduled jobs, external connections and connections through web services.
Use seamless update handlers when it is important to reduce user waiting time upon migration to corrective releases that do not contain changes in the data structure and are updated dynamically.
For more information, see Seamless data update. - Deferred – if the update handler needs to be executed in the background after execution of exclusive (seamless) update handlers is completed, and users are authorized to sign in the application.
Deferred handlers are used to process the infobase data that does not prevent users from starting a new application version without waiting for processing of this data to complete.
Examples of deferred handlers: processing large data archives for closed or previous periods, inactive product items, various data that is currently disabled by functional options, and other.
For more information, see: Deferred data update.
If the parallel deferred update mode is used in the configuration (library) (in the OnAddSubsystem procedure, the DeferredHandlerExecutionMode = "Parallel" property), to design deferred update handlers, follow the Parallel deferred update mode standard.
Example of the handler that requires the exclusive mode:
Handler = Handlers.Add();
Handler.ExecutionMode = "Exclusive";
Handler.Version = "11.1.0.0";
Handler.Procedure = "Catalog.MyCatalog.FillCodeForSearch";
Example of implementation of the handler in the Catalog.MyCatalog manager module:
// TM 11.1.0.0 update handler
//
// Iterating over all catalog items with unfilled search code,
// and filling in with the catalog code without leading zeros and prefixes
//
Procedure FillCodeForSearch () Export
...
2. Location of update handlers
2.1. Handlers must be designed as export procedures.
Place the handlers in manager modules of metadata objects whose update the handlers perform.
Example:
If a new attribute is added to the "Departments" catalog and the attribute must be filled in with the default value, the handler must be located in the manager module of this catalog.
2.2. In some cases, when it is impossible to refer a handler to any specific metadata object, you can place the handler to the server common module whose purpose is connected with the infobase data processor being executed. For example, locate update procedures related to warehouse functionality in the WarehouseServer common module. The procedure must be located in the service part of the module in the "Infobase update" section.
3. Implementation of update handlers
3.1. Handlers must meet the following requirements:
-
The handler must not contain logic for interactive user actions.
- In case of a critical error during the update, an exception must be thrown in the handler. The exception must stop the update procedure. The application cannot be started until the error causes are fixed.
-
The handler must be designed for repeated execution. Handler execution results must be the same for the same data no matter what the number of calls of this handler is. For example, repeated start of the handler must not lead to data duplication in the infobase.
- Within one version (the Version property value), the handler performance must not be dependent on its execution sequence. If such dependencies occur, combine such handlers into a single one.
- If the configuration includes DIB exchange plans with filters, note that the DIB subordinate node being updated might contain incomplete data: for example, it has records in the register, and the registrar itself is absent. In this case, the update handler must skip such data update.
3.2. Update handler must not contain redundant actions with data, it must be quick.
3.2.1. To do this, you need to disable the business logic when processing data. In most cases, by setting the DataExchange.Import flag:
DocumentObject.DataExchange.Import = True;
In some cases, to partially disable the business logic, it is possible to provide an additional flag, for example:
DocumentObject.AdditionalProperties.Insert("DisableMyBusinessLogic");
3.2.2. For most data being registered, disable registration of changes on exchange plan nodes to avoid sending the entire amount of processed data to all nodes. $$$
- In the distributed infobase (DIB), data must be processed independently on each node.
- Upon exchange between user-defined configurations (applications), data processing must not lead to their export to receiving infobases.
Exceptions are cases of creating reference objects, which must be transferred by data exchange tools to other DIB nodes with the same value of the Reference attribute.
3.2.3. In the update handler code, instead of
DocumentObject.Write();
use the following:
DocumentObject.DataExchange.Import = True; // Disabling all business logic upon writing
DocumentObject.AdditionalProperties.Insert("DisableObjectChangeRecordMechanism");
DocumentObject.DataExchange.Recipients.AutoFill = False;
Document.Object.Write();
When Standard Subsystems Library (SSL) 2.1.4 and higher is used in the configuration, use the WriteData procedure of the InfobaseUpdate common module:
InfobaseUpdate.WriteData(DocumentObject);
3.3. Specify comments before handlers. The first comment line must contain information about the configuration version, for which the handler is designed. The following comment lines must contain answers to the following questions:
-
Which data will be changed (what do we change)?
-
What changes will be made to this data (how do we change it)?
Example:
// TM 11.1.0.0 update handler
//
// Iterating through all catalog items, in which the search code is not filled in,
// and filling in with the catalog code without leading zeros and prefixes
//
Procedure FillCodeForSearch() Export
4. Migration to new library versions
4.1. When a configuration is started being supported by a new library version, increase the configuration version number. It is required to start infobase update handlers.