Versioning

Versioning allows you to track the changes that have been done to a BRFplus object over time. It is based on the timestamp that the system assigns to objects when they are saved and activated. Different versions of the same objects can be kept in the system and processed based on the timestamp. Also, using the BRFplus Lean Trace function normally requires that all of the traced objects are versioned.

The system creates a new version every time an active object is changed and saved (except for versioning mode Transport-dependent — see section Default Versioning Behavior below). As opposed to that, any changes done to an inactive object do not create a new version. Versioning can be switched on or switched off.

Old versions can be accessed by passing the timestamp to the PROCESS method or the GET<...> methods. If you pass a timestamp and access an object, a version of the object at that particular time is returned. If no timestamp is passed then the most recently activated version is used for processing. In the case of a GET<...> method, the latest object properties (active or inactive) are returned.

Example Example

A constant expression has been created on June 24, 2007 (date) at 01:56:19 (time). The value assigned to the constant is ABC. The value is changed to XYZ on July 14, 2007 at 04:46:17. The change is activated and saved. The value is again changed to HIJ but is not activated. The table below summarizes the changes:

Incident (Event)	State	Change timestamp (Date Time format)	Version	Constant Value	Text
A new object is created.	Inactive	2007–06–24 01:56:19	1	ABC	text ABC
The object is activated.	Active	2007–06–24 01:58:35	1	ABC	text ABC
The constant value is changed and activated.	Active	2007–07–14 04:46:17	2	XYZ	text XYZ
The constant value is changed and saved.	Inactive	2007–08–12 01:56:19	3	HIJ

The current version of the constant has the value HIJ and is not activated. The BRFplus Application Programming Interface (APIs), however´, processes only activated versions. The last active version (in this example, the last active version is 2) is valid until another active version is created.

End of the example.

Note Note

Versioning only makes sense for objects that are relevant for processing. This is true for almost all BRFplus object types, with the exception of the following object types that are never versioned:

Catalog
User-defined expression type
User-defined expression types are not versioned although they are processing-relevant. This is due to the fact that BRFplus has no control over the design of user-defined expression types. It is therefore possible that a given expression type is totally redesigned and shows completely different behavior over time. In combination with the Lean Trace function, this would lead to problems that the system cannot resolve.

End of the note.

Features

Default Versioning Behavior

You can define whether newly created objects are put under version control or not by default. This default setting is done on application level and affects all objects that are created in the scope of that application. You can adjust this setting for an application in the BRFplus workbench on the Default Settings tab.

You can choose from the following default versioning modes:

Off
Objects that you create have the versioning attribute set off by default. You can manually set versioning for all objects in the application on or off at any point in time. The versioning setting of already existing objects is not affected by this default versioning mode.
On
Objects that you create have the versioning attribute set on by default. You can manually set versioning for all objects in the application on or off at any point in time. The versioning setting of already existing objects is not affected by this default versioning mode.
Enforced
This is the recommended setting for applications where you want to use the Lean Trace function.

Objects that you create have the versioning attribute set on by default. As long as this default versioning mode is in effect, versioning of all objects in the application is enforced and cannot be set off.

When you set this default versioning mode, the system offers to set versioning on for all objects that already exist in the application. If you confirm, versioning is set on for all existing objects in the application. If you reject, the version setting for all existing objects is left unchanged. In both cases, newly created objects will have versioning set on, and versioning cannot be set off.

Depending on the system status, the confirmation dialog mentioned above can contain additional controls:
- Transport Objects: Tick this checkbox to make sure that the changed objects are recorded on a transport request. This checkbox is available only if the application is transportable, and the system client has been configured such that changes to client-specific objects are not automatically recorded.
- Transport Request: ID of the transport request to be used for recording the changes. If the application is already assigned to a transport request, the respective transport ID is displayed and cannot be changed. Otherwise, you can choose a suitable transport request.
Note
If you decide to let the system set versioning on for all existing objects, you should be aware that this is only possible for objects that are active and in a consistent state. If there are any inactive objects in the application, the system does not change the versioning setting of these objects. You can manually activate these objects, either individually or with the mass change tool.

If, at a later point in time, you decide that the Enforced versioning mode is no longer needed, you can easily choose one of the other default versioning modes. This is a prerequisite for you to set versioning off for selected objects if you so desire.

End of the note.
Transport-dependent
Objects that you create have the versioning attribute set on by default. This mode is a refinement of the Versioning=Enforced mode and is specially designed to reduce the number of versions to a reasonable amount, thus saving storage capacity. This versioning mode shows the following behavior:
- Transport-dependent versioning is possible only for objects in applications that are transportable (storage type System or Customizing; development package properly assigned).
- When you modify an already active object, the system creates a new version for that object. As opposed to the other versioning modes, this new version remains in effect until the object is transported from the design time system to other systems. This means that during the time between the first change to the object and the time it is transported, you can apply as many changes to it as you like, and you can activate it as often as you like, without creating a new version for each single modification.
- Versioning is mandatory for all objects in an application and cannot be set off for individual objects.
This versioning behavior is useful in design time systems where objects under development are frequently changed, while these changes have no impact on your company's business because the changes are done in a separate, non-productive system. Also, this versioning mode results in an automatic synchronization of object versions in both the development system and the productive systems.

When you set this default versioning mode, the system offers to set versioning on for all objects that already exist in the application. If you confirm, versioning is set on for all existing objects in the application. If you reject, the version setting for all existing objects is left unchanged. In both cases, newly created objects will have versioning set on, and versioning cannot be set off.

Timestamp

For each version of an object, the system maintains a timestamp. Depending on the object version status, the meaning of this timestamp varies:

Inactive: As long as a version is still inactive, the version timestamp indicates the point in time when the object has last been saved.
Active: For an active version of an object, the version timestamp indicates the point in time when the object has been activated.

It can be helpful to keep in mind these two different notions of the timestamp when you need to understand clearly which object version is used at runtime. For example, a situation may occur where a versioned object for which an active version already exists is changed, but the activation of the changed version is postponed to a later point in time. The system then continues to use the older active version at runtime as long as the changed current version is not activated. In other words, for the changes to take effect, the relevant date is the moment when the changed version is activated, not the moment when it was changed. Therefore, the version timestamp holds the most relevant data with respect to the object version status. As a side effect of this system behavior, it is not possible to tell for an active version when the last changes have been applied to the object.

Versioning of Texts And Documentation

For objects under version control, you can decide that the object texts and documentation shall also be version-dependent. With this feature, you can keep track of naming changes that have been applied between different versions.

Example Example

In a BRFplus application for compensation management, you may have modeled a number of data objects representing different tax amounts that are applicable in a country. After a government change, some of the taxes are still in place but have been renamed by the authorities. You would then reflect the new tax name by creating a new version-dependent name for the affected data objects, while keeping the previously used names in an older version due to legal compliance.

End of the example.

Also, if the internal structure of a particular object changes significantly over time, it may be a good idea to mention this in the object documentation.

Example Example

In a BRFplus application, you have a complex formula expression used for risk assessments as a basis for insurance premium calculation. Over time, you may have to add a number of risk factors that were not in scope at the beginning. To clarify what the formula in its revised state can do, you maintain a version-dependent documentation for the expression.

End of the example.

Note Note

Versioning of texts and documentation leads to significantly higher consumption of database storage capacity. We therefore recommend to use this feature only in cases where this is mandatory from a use-case perspective.

End of the note.

Versioning Status

Depending on the different versioning modes explained in the Default Versioning Behavior section above, the status of an object version can take different values. These values are:

Versioning Status	Description
Not versioned	Only one version exists for an object. All changes to an object are stored in the same version, thereby overwriting the object without a possibility to revert to the previous state.
Versioned	In addition to the initial version that exists for each object, this status leads to the creation of a new version whenever a previously activated object is changed. The cumulated changes to an object version are frozen in that version by activating it.
Versioned by transport	Similar to Versioned. However, a version is frozen not by activation, but by transporting the activated object to another system. In other words, the same version can be activated several times as long as it is not transported.
Not transported	A version that was created while the versioning behavior was set to Versioned by transport, but the behavior was changed before the respective transport was released.

The following table explains how a particular change that is done to an object corresponds with its versioning status:

Object Changes	Version No.	Versioning Status
New object O created with versioning switched off.	1	Not versioned
Versioning switched on for O.	1	Not versioned
O activated.	1	Versioned
Versioning behavior of the application set to transport-dependent.	1	Versioned
O changed.	2	Versioned
Versioning behavior of the application set to Versioning enforced.	2	Not transported
O activated.	3	Versioned
Transport request containing O released.	3	Versioned by transport <transport ID>

The table shows that with transport-dependent versioning, two additional status values have been introduced, Versioned by transport <transport ID> and Not transported. The two values denote the following situations with respect to versioning:

Versioned by transport <transport ID>: Transport-dependent versioning is in effect for the application to which the object belongs. The object has been recorded on transport request <transport ID>, and the transport has been released.
Not transported: Transport-dependent versioning was initially in effect for the application to which the object belongs. However, before the transport was released, the versioning mode has been set to Versioning enforced. As a consequence, the system creates a new version for the object. The previous version that should have been related to the release of a transport is now marked as Not transported.

More Information

Application

Tracing

Setting Versions