Change Tracking

Introduction

Note that, if you are upgrading to FNZ Studio 2024.5 from a lower version, you need a license to use the BO Change Tracking feature. Please, contact Support . See also System Upgrade: FNZ Studio 2025.

FNZStudio’s Change Tracking feature allows FNZ Studio developers to collect all Business Object changes related to a unit of work (change, new feature, bugfix) which, in this context, is referred to as Story.

This in turn allows:

  • Tracing back to the business requirement behind each change to the Solution (the purpose and context of the change).

  • Exploring all completed and in progress work organized by Story.

  • Reviewing all the changes made for a Story by comparing the Business Object versions before and after the changes made for the Story. This can be done either by the developer who implemented the changes or by a peer developer checking the changes for quality assurance purposes.

Note that, even though the Change Tracking feature allows grouping changes related to a Story, it is not a "branching" feature: all developers still work on the same "working copy" of Business Objects.

Important! The Change Tracking feature can be fully enabled/disabled using the feature toggle nm.featuretoggles.isChangeTrackingEnabled. If your project does not require tracking changes against Stories, disable the functionality by setting the feature toggle to false. This will hide all related functionalities and options in FNZ Studio.

Stories

A Story is a functional unit of work to be performed on an FNZ Studio solution. It can be a feature, change, bug or task.

It is characterized by:

  • An ID (mandatory): It idenfies the story and works as a "tag" applied to changes to connect them to the Story.

  • A title(optional ): It is used for easier identification and exploration of Stories in FNZStudio.

  • A link(optional):It isused to reference the Story as defined on an external tracking tool (e.g, Atlassian Jira), in case the Story was originally created on such source system.

Stories must be created in FNZ Studio to be able to track changes against them. In case the Story was originally defined on a dedicated source system (e.g. Atlassian Jira), creating the Story in FNZStudi o means referencing the original story from FNZ Studio; all Story information remains in the original system, and the provided Story link allows navigating from FNZ Studio to the external tool to access all Story details.

Tracking Changes against a Story

In order to track changes against a Story, FNZ Studio Composition offers a global selector that each developer can use to specify the Story they are working on. Usually, this is done as soon as they enter the Solution Design module section and before they make any changes.

Once they have selected a Story from the Tracking Story selector, developers can proceed with their work on the Solution as usual: all the changes they apply are automatically tracked against the selected Story. At any time, developers can see the Story they are tracking against, stop tracking against that Story, or switch to a different Story. The Story selection applies to the current user only (each developer can work on a different Story); the same developer cannot track changes against multiple Stories at the same time.

Even when the Change Tracking feature is enabled in FNZ Studio, the selection of a Story to be used for tracking is not mandatory, since there can be changes to be done outside of the scope of a Story. When the developer logs into FNZ Studio, if no Story is selected, a notification warns that the changes are not being tracked.

In case the developer forgets to track changes against a Story or tracks against the wrong Story by mistake, the Story Management module allows manually adding, removing and moving changes across Stories (see Browsing and managing stories section).

Creating and Selecting Stories

When the Change Tracking feature is enabled, the Change Tracking banner is shown at the top of the Solution Design module of FNZ Studio.

In the banner, the Tracking Story selector is available to pick the current Story being worked on. Click on the selector to browse the list of Stories defined in FNZ Studio and select the appropriate one. Once a Story has been selected, it remains visible in the Change Tracking banner to easily check the currently selected Story.

The Stop Tracking button is available to stop tracking changes.

The Tracking Story selector allows changing the selected Story at any time during development. In this case, all the changes from that time onward are tracked against the new Story.

If the desired Story does not exist in FNZ Studio yet (therefore, it is not available in the Story selector), you can create it using the dedicated option in the selector.

In this case, specify:

  • Story ID (mandatory): the Story identifier - it must be unique across all Stories.

  • Story Title (optional but recommended): Enter a short title that describes the Story for easier identification of the Story in Studio.

  • Story Link(optional) : if the Story was originally defined on an external system (e.g, Atlassian Jira), enter the URL that points to the Story on the external tool in order to be able to easily navigate from FNZ Studio to the original definition of the Story. This allows accessing all additional information about the Story available on the source system (status, assignee etc).

Tracking information can also be accessed directly from inside Business Object editors. Click on the Change Tracking icon at the right of the editor top bar to see which is the currently selected Story, stop tracking or change the selected Story. Note that such changes apply globally to all editors. For inline editors such as Label and Resource editors, the tracking information is available under the Change Tracking section at the bottom of the page.

Tracking Changes and Implications

If a Story is selected for tracking, every Business Object change in any non-Platform Package is tracked against that Story. This includes:

  • Creating (or importing) a Business Object

  • Deleting a Business Object

  • Modifying a Business Object

  • Committing a Business Object

More precisely, tracking occurs at the level of the Business Object version: while tracking is active, all versions that get created are associated with the selected Story. In fact, if you right-click on a Business Object from the Editor and select the Show Versions option, the associated Story/ies (if any) are displayed (see Business Object Versioning for further information).

Note that there are some implications on the Commit operation:

  • If Change Tracking is disabled, when committing a Business Object, all intermediate uncommitted versions up to the previous commit are deleted.

  • If Change Tracking is enabled, the first and last versions tracked against a Story for a given Business Object are always kept, even if uncommitted and followed by a commit. In addition, the version preceding the first one tracked is also preserved, even if uncommitted and followed by a commit. This version is considered the "base version" used to compare the Business Object before/after the implementation of the Story. For Business Objects created in the context of a Story, the base version is the very first (empty/default) version of the Business Object being created. These uncommitted versions are kept in FNZ Studio in order to check what changes were performed until the corresponding Story is deleted, or until they are manually removed from the Story using the features provided by the Story Management module.

    Note: For additional safety, the Unused Business Object Versions Cleanup Job configurable in System Maintenance > Job Scheduling takes care of cleaning up any intermediate uncommitted versions of Business Objects that may become orphan (not associated to any Story) for any reason.

Browsing and Managing Stories

FNZ Studio provides a dedicated module to browse all Stories and manage them, which includes adding and removing Stories as well as adding and removing changes from Stories (in case of tracking mistakes done while applying changes to Business Objects). This module is located under Solution Maintenance > Change Tracking > Story Management.

Note that using this module requires Packages (Full Access) Permission. It can be hidden using the feature toggle nm.featuretoggles.isChangeTrackingEnabled like all other Change Tracking features.

Story Management Module

The Story Management module contains a table with all the Stories defined in FNZ Studio. For each Story, the following information is shown:

  • Story ID and title as defined when creating the Story; the Story ID is clickable if a link is set for the Story. Clicking on the Story ID opens a new browser tab and navigates to the specified external link for the story.

  • Status: Represents the progress of each Story (Development, To Be Reviewed, Reviewed, Done). See details in section Story Status.

  • First Change and Last Change tracked for the Story.

  • Changed BOs: Number of Business Objects that have at least one version tracked for the Story.

  • Contributors: List of users who made changes for a given Story since its creation. Active users on the Story are marked by an icon.

This Story Management page has the following options:

  • The table can be sorted and filtered.

  • The Add Story button allows defining a new Story. The available settings are the same as described in section Creating and Selecting Stories.

For each Story the following actions are available in the menu at the right-hand side of each row:

  • Show Changes: Opens a modal window that lists all Business Objects changed for the Story (see details in List of Business Objects changed for a Story). You can also double-click anywhere on a Story row to open the modal window.

  • Edit Story Properties: Allows editing the Story Title and Story Link.

  • Delete Story: Permanently deletes the Story and all related tracking information, including all uncommitted versions which were kept since tracked for the Story. Note that this action does not undo the changes performed on Business Objects while the Story was selected for tracking. This action requires confirmation.

Story Status

All Stories have a Status that represents their progress. This can be browsed and changed from the Status column in the Story Management Module. Possible statuses are:

  • Development: This is the default status for a newly created Story in FNZ Studio. It represents a Story currently being worked on and not yetready for a peer review. Changes can be made for a Story with this Status.

  • To Be Reviewed: Represents Stories for which all necessary changes have been implemented and, therefore, are ready for a peer review. While in this status, the content of the Story is "frozen", thus making it impossible to apply further changes. If review is not successful, the Story can be pushed back to its Development phase and more changes can be applied.

  • Reviewed: Represents Stories that have already been peer-reviewed, where all the changes have been approved. While in this status, the content of the Story is "frozen", thus making it impossible to apply further changes. If necessary, the Story can be pushed back to its Development phase and more changes can be applied.

  • Done: Represents Stories for which all activities have been completed but must still be kept in FNZ Studioto to check what changes have been applied to each of them. While in this status, the content of the Story is "frozen", thus making it impossible to apply further changes. If necessary, the Story can be pushed back to its Development phase and more changes can be applied. Note that, if a Story does not require a peer review, it can be moved from status Development to Done directly.

Possible Status transitions are represented in the following diagram:

All Status transitions, the user who executed them and the corresponding date/time are kept for auditing purposes and can be displayed by clicking on the Status History option available in the right-hand side menu for each Story. Such History can also be exported in .csv format using the Export button in the modal window.

Notes on Status

Consider the following notes:

  • Only Stories in Development can be selected for tracking and can be altered by adding/removing Business Objects and versions.

  • When moving a Story from Done to Development, it is possible to decide whether to keep the association between the Story and the previously tracked base, first and last versions of the various Business Objects, or to drop the associations, thus starting over Story tracking.

  • When the Review Changes option is selected for a Business Object included in a Storyset to Done, the "new" version displayed on the right of the Compare Versions tool (List of Business Object Versions Tracked for a Story) is the last version of the Business Object associated with the Story (instead of the Head version used for all other Statuses).

List of Business Objects Changed for a Story

When the Show Changes action is executed for a Story, a modal window that displays the list of Business Objects changed for the Story is shown. The window contains a table that lists the Business Objects, with their Id, Type and Last editor. Note that:

  • All data can be filtered and sorted.

  • A warning icon next to a Business Object indicates that, during the development of the current Story, such BO has also been modified in the context of other Stories. The list of such Stories, as well as their status, is provided when hovering on the icon.

  • A blue or black dot next to the BO indicates the commit status of such BO (see Business Object Versioning).

The following actions are possible

  • Add Business Object to Story (overall action): Allows adding a Business Object to the Story and it is useful e.g., when a developer accidentally forgot to start tracking against the Story before making changes to the Business Objects. In order to add a Business Object, select it from the Business Object selector dropdown and pick the version(s) to be added (either all versions or a range of versions specified as a From-To interval). This action is only available for Stories with Status Development (Story Status).

  • Review Changes: Opens the Compare Versions tool in a new browser tab. It pre-selects the versions to be compared: the "old" version is the Base version for the Story, i.e. the version right before the first one tracked for the Business Object in the current Story (as described in Tracking Changes and implications); the "new" version is the latest version tracked for the Story in case the Story has Status Done (Story Status), and the Head version in all other cases.

  • Show Versions: Expands the table row and shows a list of all versions of the Business Object tracked for the Story (see details in List of Business Object versions tracked for a Story). It is the same as clicking on the small arrow to the left of the Business Object Id.

  • Move to Another Story: Allows moving some or all versions of the selected Business Object to another Story, therefore resulting in the same situation as if the changes were originally tracked for the new Story. This is useful in case of mistakes done when applying changes. In order to move the changes, select the target Story and the versions to be moved (either all versions or a range of versions specified as a From-To interval). This action is only available for Stories with Status Development (Story Status).

  • Add Version to Story: Allows adding some or all versions of the selected Business Object to the current story, therefore resulting in the same situation as if the changes were originally tracked for the current Story. This is useful in case of mistakes done when applying changes. In order to do this, select the versions to be added to the Story (either all versions or a range of versions specified as a From-To interval). This action is only available for Stories with Status Development (Story Status).

  • Remove From Story: Allows removing all changes related to the selected Business Object from the current Story, therefore resulting in the same situation as if the changes were not originally tracked against any Story. This is useful in case of mistakes done when applying changes. Note that this action does not undo the changes performed on the Business Object while the Story was selected for tracking. This action requires confirmation. This action is only available for Stories with Status Development (Story Status).

List of Business Object Versions Tracked for a Story

When the Show Versions action is executed for a Business Object, the table row is expanded and shows the list of Business Object versions tracked for the Story, including the type of change, date and author.

For each version the following actions are available at the right-hand side of the row:

  • Review Changes up to this version:Opens the Compare Versions tool in a new browser tab. It pre-selects the versions to be compared: the "old" version is the base version for the Story, i.e. the version right before the first one tracked for the Business Object in the current Story (as described in Tracking Changes and implications); the "new" version is the currently selected one. The action is not available if the version is the first existing one for the Business Object (creation of the Business Object).

  • Remove from Story: Allows removing the selected version from the current Story, therefore resulting in the same situation as if the changes were not originally tracked against any Story. This is useful in case of mistakes done when applying changes. Note that this action does not undo the changes performed in the selected version. This action requires confirmation. This action is only available for Stories with Status Development (Story Status).

JiraConnector Extension

Change Tracking can optionally be integrated with Atlassian Jira ® using the JiraConnector Extension, released with FNZ Studio 2025.2.2 and higher. This allows retrieving information about existing Stories and their details from Jira for increased visibility in FNZ Studio.

Extension Installation

In order to set up Jira integration, install the JiraConnector Extension compatible with your FNZ Studio version and set the following Extension configuration properties:

  • jira.base.url: The base URL of the Jira instance to connect to, for example https://portal.fnz.com/jira.

  • jira.type: The type of Jira installation: datacenter, server or cloud. For FNZ Jira version, use option datacenter.

  • jira.project.keys (optional): The comma-separated list of Jira Projects to fetch Stories from, for example STP1, STP2, STP3. If not specified, all Projects are used.

Jira Authentication

When the JiraConnector Extension is installed and configured as described above, FNZ Studio users are required to log in to Jira in order to use Change Tracking features. The options described below are available:

Jira Datacenter

If jira.type = datacenter was selected in Extension Installation, FNZ Studio users need to upload their Jira Personal Access Token, which can be generated in the User Profile section in Jira (see Using Personal Access Tokens - Atlassian Documentation).

The Jira Personal Access Token can be uploaded in FNZ Studio by clicking on the Jira Login button, which is shown in the Change Tracking toolbar in the main FNZ Studio window and in each Business Object editor. The Jira Personal Access Token is stored in FNZ Studio Secrets Management Framework (Passwords tab) and is only visible and editable by the corresponding user.

If the Jira Personal Access Token expires or is revoked in Jira, the user is prompted to upload it again in order to continue using Change Tracking.

Jira Cloud

If jira.type = cloud was selected in Extension Installation,FNZ Studio users need to upload their Jira API Token, which can be generated in the Security section of their Jira Account (see Jira documentation) For now, an API Token without scopes must be used.

The Jira API Token can then be uploaded in FNZ Studio by clicking on the Jira Login button shown in the Change Tracking toolbar on the main FNZ Studio window and in each Business Object Editor. When logging in, users must specify their Jira User Id and the Jira API Token. The Jira API Token is stored in FNZ Studio Secrets Management Framework (Passwords tab) and is only visible and editable by the corresponding user. The Jira User Id is stored as a User Preference (Users, Groups and Roles).

If the Jira API Token expires or is revoked in Jira, the user is prompted to upload it again in order to continue using Change Tracking.

Feature Overview

If the JiraConnector Extension is installed and configured, and if the current user is authenticated inJira, the following features are available in Change Tracking, in addition to the basic ones available for the non-integrated version (see section above).

  • When adding new Stories to FNZ Studio, it is possible to search through a list coming from Jira instead of entering Story information manually. The list retrieved from Jira includes Stories, Bugs and Tasks which do not have Resolution Status set to Done. Story id, URL, Summary, Epic and Assignee information are retrieved from Jira to support the user during the Story selection. Such information cannot be manually edited in FNZ Studio.

  • When browsing Stories in the Story Management Module , the table contains the columns Epic and Assignee with data coming from Jira, to support the user in the identification and filtering of Stories. Note that the columns First Change is not shown in this case. The information coming from Jira (Summary, Epic and Assignee) is updated periodically in FNZ Studio.