Business Object Versioning

What is Versioning?

In FNZ Studio, each Business Object is versioned: instead of having only one specific version, Business Objects can have many different versions which were created at different points in time.

Important! Besides Business Objects, the Packages that contain the Business Objects are also versioned. See Creating Package Versions for more information on the connection between versions of Packages and versions of Business Objects.>

To understand why this is important, consider the following scenario: Alice starts a Process and proceeds to work through it. Meanwhile, Bob updates the Business Application on Alice's FNZ Studio installation. Without versioning, Alice's Process Instance and Screens could suddenly change. Assume that the Screen she is currently in was removed from the new version of its Process: Suddenly, Alice's Process Instance is in a state which does not exist anymore, and Alice would get an error message. The Process Instance she started could not be finished because it is now in an inconsistent state.

With FNZ Studio versioning, Bob can make updates to the Business Application without creating any issues for Alice. If Bob updates the Business Objects Alice is currently working on, FNZ Studio creates new versions of these Business Objects. Alice's Process Instance finishes using the versions of the Business Objects which were available at the time when she started the Process. Bob's changes thus do not cause problems for Alice. Finally, when Alice starts a new Process Instance, Bob's new versions of the Business Objects are used.

Important! The rule that a Process by default uses the versions of Business Objects which were available at the time when the Process was started does not apply to Integration Links. See Integration Link Versioning for more details.

But these are not the only ways versions can help you. If you're working in FNZ Studio Composition and accidentally delete a Business Object, or if you make changes you want to undo, you can. Reverting to earlier versions of Business Objects is simple and fully supported by FNZ Studio.

How Versions are Created

FNZ Studio creates new versions of Business Objects automatically. Each time a Business Object is changed, a new version is created. Business Objects can be changed in many ways:

• If you open a Business Object in its editor, make a change and save, a new version is created.
• If you select a Business Object in the library and change its properties, a new version is created.
• If you import a Business Object into a Package, a new version is created.

Note: In contrast, if you import a Package, all Business Objects in the Package are committed (except if you are importing the modifiedversion).

These new versions are temporary versions. They are only visible in FNZ Studio Composition, and Workspace users do not see them. To allow Workspace users to see new versions, commit your Business Objects. Committing Business Objects removes all temporary versions and creates a committed, static version. Committed Business Objects are never deleted.

Example of Versions

The following example shows how versioning is applied to a Screen, but the principle is the same for all Business Objects.

1. When you create a new Screen, a new initial version is created:
2. If you open this Screen, make a change and save, FNZ Studio creates a second version of the Screen. This is still only one Screen, but there are now two versions of this Screen. If you close the Screen and open it again, FNZ Studio automatically shows the most recent version of the Screen.
3. If you make another change and save the Screen, a third version is created. But these are all temporary versions. They are only visible within FNZ Studio Composition, users never see them.
4. In order to turn these temporary versions into one final, static version that is visible in FNZ Studio Runtime, commit the Business Object. After committing, the temporary versions are discarded and replaced with one committed version:

5. If you open the Screen, make additional changes and save, a new temporary version is created:
6. If you continue working with your Screen, committing versions as you deem them usable for Workspace users, you eventually end up with a version history that would look similar to the image below. Here, there are five committed, static versions as well as three newer, temporary versions.

Head and Latest Committed Versions

Two versions in a Business Object's version history are referred to by specific names:

• The newest version is called the Head Version, regardless of whether it is a temporary version or a committed version. This is the version that you see when you double-click on a Business Object in FNZ Studio Composition, opening it in its editor.
• The version which was most recently committed is called Latest Committed Version. This is the version which Workspace users see by default.

Note: Users do not always see this version. For example, if they start a Process, this Process Instance continues to run with the Business Object versions that were the latest committed at the time the Process was started. If Business Objects are committed after the Process was started, these newer committed versions are ignored.>

Versions in FNZ Studio Composition

While you are working on a Business Object inside FNZ Studio Composition, versions are helpful because they allow you to change things without the risk of losing data. As long as you do not commit your changes, all intermediate versions of your Business Objects remain in the repository. You can revert to these earlier versions of your Business Objects at any time.

This chapter explains how to work with Business Objects using versions.

Version Symbols

FNZ Studio shows blue or black dots next to Business Objects in a number of places, including the Business Object library and the Business Object Editor header. These dots indicate whether a Business Object:

• Has uncommitted changes
• Has ever been committed
• Was modified by you

The dot applies to specific versions of a Business Object:

• In the Business Object library and Editor header, it applies to the Business Object's Head version.
• In a list of Business Object versions, the dots apply to each individual version.

The following cheat sheet explains what the dots mean:

Committing Business Objects

When you have completed work on your Business Objects, make them available to Workspace users by committing them:

1. Right-click on any of your Business Objects, and select the appropriate option Commit Selected, Commit Mine or Commit All:

   • Commit Selected – Opens the Commit dialog and populates it with all uncommitted Business Objects currently selected in FNZ Studio Composition (press CTRL to multi-select).
   • Commit Mine – Opens the Commit dialog and populates it with all uncommitted Business Objects where the last change was made by you.
   • Commit All – Opens the Commit dialog and populates it with all uncommitted Business Objects.

   The commit dialog is opened and populated with Business Objects according to your selection:

   

2. You can change the selection of Business Objects to be committed as needed in the Commit column.

3. Enter a Comment (a description identifying this commit) and click on Commit. FNZ Studio locks the selected Business Objects, commits them, and closes the window automatically.

Reverting to Earlier Versions

Sometimes you make a change to a Business Object which you would like to undo at a later point. To revert a Business Object to an earlier version:

1. Right-click on the Business Object you want to revert and select Revert Selected. This opens the following dialog:

2. Select which version to revert to at the top of the dialog (further information on this version is displayed in the middle part of the dialog).

Note: You can also select multiple Business Objects within a Package to revert. If you do so, you do not select a version to revert to, but a point in time, represented by commits to the platform. The commits related to the selected Business Objects are displayed in bold. Depending on the selected commit, the Business Objects are selected at the bottom of the dialog, indicating if they are affected by this revert operation or not.

3. To revert the Business Object to the selected version, click on Revert. This checks whether the resulting dependencies are satisfied, and reverts the Objects.

Tip: You can revert all Business Objects in a Package to the state they were in when an older Package version was created. To do so, export and re-import an older version of the Package. See Importing and Exporting Packages for details

Getting an Overview of Versions

There can be different reasons to look at the version history, e.g.:

• You want to revert to an earlier version, but are not quite sure which one you want to revert to.
• You want to get an overview of changes made to a Business Object.

To see the version history of a Business Object, right-click on it and select Show Versions.

Note how to read version history:

1. The list of versions grows from top to bottom, meaning the most recent (Head) version is located at the end of the list. The Latest Committed Version is the first version above the blue line. If there is no blue line as there are no uncommitted versions, the Latest Committed Version is the last entry in the list.
2. When you revert to an earlier version, or when you import an earlier version, your version history is no longer linear, meaning that the reverted/ imported Business Object is not based directly on the version placed above it in the list. This "version gap" is indicated by the grey line in the version history.
3. If there are uncommitted versions, this is indicated by the blue line – all versions below this line are not committed, as also indicated by the version symbols (dots).
4. If the Change Tracking feature is active, any associated Stories are also displayed below the editor's name (see Tracking Changes and Implications).

Besides viewing the version history, you can also perform the following actions here:

• Open in Editor – Opens the Business Object in the editor (in read-only mode if it is not the Head version).
• Compare to Head Version – Compares the version of the Business Object with the Head Version using the Diff Viewer.
• Compare to Previously Committed Version – Compares the Head Version with the most recently committed version using the Diff Viewer.
• Revert to this Version – Opens the Revert dialog allowing you to revert to this version. See Reverting to Earlier Versions for details.

Deleting Business Objects

Deleting a Business Object does not actually delete any of the older versions of the Business Object from the repository. Instead, deleting a Business Object creates a new version which tells the repository that this Business Object is now deleted and should not appear in FNZ Studio Composition in the future. Since the deleted Business Object remains in the repository, running Processes can continue unhindered, using old versions of the deleted Business Object.

What you need to know about deleting Business Objects:

• To delete a Business Object, right-click on it and select Delete. This creates a new, uncommitted and deleted version of the Business Object. In FNZ Studio Composition, the Business Object appears with its name struck-through:
• To undo the deletion of an uncommitted Business Object, right-click on it and select Undelete.
• As soon as you commit a deleted Business Object, it is no longer visible in FNZ Studio Composition. Again, this does not mean that the Business Object is removed from the repository, but only that its Head version indicates that the Business Object is deleted. For information on how to restore a Business Object in this scenario, see Restoring Deleted and Committed Business Objects.

• Deleting and undeleting of Business Objects is recorded in the version history.

Note: As described, deleting Business Objects does not remove them from the repository, even if they are deleted and committed. This means that these Business Objects continue to occupy disk space and memory. To permanently remove Business Objects to free up disk space, use the Obliteration functionality.

Restoring Deleted and Committed Business Objects

Business Objects which were deleted and committed are no longer visible in FNZ Studio Composition, but are still available in the repository and can be restored, so that they are again visible in FNZ Studio Composition.

To restore deleted and committed Business Objects:

• Press ALT before selecting a category in the Library (Process, Screen etc.) to see deleted and committed Business Objects. Right-click on the Business Object you want to restore and select Undelete.

Versions in FNZ Studio Runtime

FNZ Studio uses Version Filters to understand which version of a Business Object to use in FNZ Studio Runtime:

• The Timestamp Filter selects the Business Object version which was the latest committed at the time specified in the filter. This is the filter which is applied when a Process is started and which FNZ Studio uses by default.
• The Head Filter selects the Head Version of all Business Objects. This filter is used mainly for testing as you develop new Business Objects.

Note: If you are starting FNZ Studio Runtime from FNZ Studio Composition, two buttons are available to select a filter:

• Head – Opens FNZ Studio Runtime using the Head versions of all Business Objects.
• Committed – Opens FNZ Studio Runtime using the latest committed versions of all Business Objects.

Timestamp Filter Example In this simplified scenario, Alice starts a Process named P1 which uses two Screens (S1 and S2) as well as a Catalog C1 and a Rule R1.

Legend:

1. When Alice starts the Process (represented by the vertical red line), a new Timestamp Filter with the current time is created. Throughout the whole Process Instance, this filter always selects the versions which were the latest committed versions when the Process started.
2. If Bob creates more versions after the Process Instance was started, they are ignored because they appear later in the timeline, after the time specified in the Timestamp Filter.

FNZ Studio automatically passes the Timestamp Filter through the Process Instance, but there are two cases where you need to think about Version Filters:

• If you want to use a different version filter than the Timestamp Filter which is created when the Process is started.
• If you are using manually entered URLs to call resources etc.

Applying a New Version Filter during a Process

Imagine the following scenario: Alice starts a long-running Process which runs over many weeks. The last Screen of this Process contains a link which takes Alice back to FNZ Studio Runtime Portal.

While the Process Instance runs, FNZ Studio by default uses a Timestamp Filter that uses the Business Objects which were the latest committed Objects when Alice started the Process. This is exactly what you want: newer versions of Business Objects are disregarded to avoid creating issues with the Process Instance. However, there is one case where you do not want to use this Filter: For the last link back to FNZ Studio Runtime Portal, you want to use a different Filter. Otherwise, Alice sees the Portal version that was active back when she started the Process.

In other words, while the Process is running, you want every link to inherit the currently active Version Filter. However, for the last link back to the Portal, you want to use a new Version Filter. You can achieve this by explicitly setting the Version Filter property on the Action which links back to the Portal, e.g. the 'Display Screen' Action:

There are two Version Filters you can select from this dropdown box:

• Same Version (inherited) — This option simply continues using the currently active Version Filter. This is the default option, and it is what you want to use in most cases
• Newest committed Version (Timestamp) — FNZ Studio creates a new Version Filter based on the current timestamp and uses this new Version Filter for subsequent Objects. Use this at the end of a Process, when you want to use newer versions of Business Objects, created after the Process was started.

Manually Adding a Timestamp Filter to a URL

Whenever you enter URLs manually, FNZ Studio does not know which Version Filter it is supposed to use.

For example, if you set CSS properties which refer to images stored as Resources inside FNZ Studio, the Version Filter gets lost when FNZ Studio requests this resource. So you need to tell FNZ Studio manually which version to use.

Assume you've created a CSS file for your FNZ Studio solution. This CSS file is used in your Screens, and it contains the following code:

background-image: url(/resource/object/Gradient-Toolbar/toolbar.gif);

If your browser calls this URL, FNZ Studio simply gets a request for a Business Object and does not know which version to use. By default, it returns the latest committed version. This is the desired result in many cases, but not in all cases.

Going back to Alice's Process: If Alice starts a Process at 6pm, but Bob changes and commits an image Resource used in that Process at 7pm, Alice's Process will suddenly show that newly committed image.

Another example is an administrator working in the Head version, testing changes to a Business Application. That user may make changes to an image and not commit those changes; however, the user will not see the changes made to the image because FNZ Studio defaults to using the latest committed version instead of the Head version.

In all cases where you write URLs yourself, you need to make sure that you add the proper Version Filter to FNZ Studio. You can do this by setting a Version Filter property like this:

1
2
3
background-image:
url(/resource/object/Gradient-Toolbar/
toolbar.gif?versionFilter=TimestampFilter-1296709712074);

Note: Whenever you are writing URLs manually, remember to set: ?versionFilter=TimestampFilter-1296709712074

Appendix: Further Information

Why does FNZ Studio implements its own versioning system instead of relying on existing source control tools such as GIT?

There are plenty of reasons behind our choice; the main one is that no existing tool on the market provides the extensive list of features needed to support fully integrated version control. Let's look at what FNZ Studio's versioning does, and why no existing versioning system can adequately cover its requirements. 

Design-Time Versioning

FNZ Studio does not rely on external, manual versioning systems. Instead, every action any user executes in FNZ Studio is immediately and automatically subject to versioning. Unlike competing systems, which depend on external integration with third-party versioning systems, no manual action is required to push changes to a repository and therefore, no errors occur; every change is tracked immediately and automatically. 

Versioning in FNZ Studio is completely non-destructive. This means that FNZ Studio allows for unprecedented safety (regular user actions will always create new versions, and never discard existing committed versions), and fine-grained developer governance (versioning tracks which developer is responsible for which change).

Unlike other systems, where versioning only covers part of a solution, versioning in FNZ Studio covers every single Business Object, as well as Packages, Package configurations, Entry Points, Web API endpoints, and other parts of a solution. Package versions in particular are a part of FNZ Studio’s versioning system and we support explicit semantic versioning of Packages.

Changes to Business Objects can be reverted at any time, and reversion itself uses FNZ Studio’s versioning system, meaning that it is non-destructive: it is possible to revert reversions.

Runtime Versioning

Versioning also automatically applies at runtime. Since FNZ Studio Solutions are fully versioned, when new versions of an FNZ Studio solution are deployed to a live system, these changes have no impact on any running Process Instances. All previous versions of Business Objects on that system remain intact, and all existing running Process Instances will continue to run unaffected by the newly deployed Business Objects (an exception applies to Integration Links). As a result, it is always safe to deploy new versions of FNZ Studio solutions.

In FNZ Studio, every part of your solution, down to the data model, is fully versioned. Most of the changes, including the ones impacting the data model, will not affect running Process Instances negatively.

In cases where control over active versions is required, FNZ Studio's version selection feature allows fine-grained version selection.

Since versioning is a built-in first class FNZ Studio feature, FNZ Studio itself knows which versions of a solution can potentially be used by running Process Instances. This allows FNZ Studio versioning to provide tools to safely delete versions of Business Objects that are no longer in use, allowing for safe storage and memory cleanup.

A final important aspect of runtime versioning is that each FNZ Studio instance requires its own fully isolated repository. Since FNZ Studio's versioning system is built into the FNZ Studio instance, isolation is guaranteed without the need for manually setting up and maintaining multiple different instances of versioning systems.

For cases where a solution is required to run on a specific version (e.g., the latest committed version), or a Business Object in an existing Process version needs to be changed or fixed, the Platform add-ons offer features such as Process Migration and Business Object Patching.

External Versioning Systems

Since external versioning systems do not provide the feature set and integration options discussed above, they can not be used to replace FNZ Studio’s versioning system. However, if desired, FNZ Studio solutions can be exported from FNZ Studio and checked into a versioning system which then acts solely as a model repository.

Remember: any changes to the FNZ Studio model must be done inside FNZ Studio. This way, you ensure that every action any user executes in FNZ Studio is immediately and automatically subject to versioning. This ensures the integrity of your FNZ Studio model.