How to Set Up Versioning on an Entity

IMPORTANT!  
Entity versioning requires the Digital Foundation deployment package. Make sure you have the Digital Foundation deployment package installed on your FintechOS instance before attempting to version an entity. The Digital Foundation deployment package is included in all FintechOS System Packs.

1 Configure the versioned entity's attributes

On the entity that you wish to version, add the following attributes:

  • masterAttributeId - lookup attribute that self-references the versioned entity. You need to also change the default relationship name to a custom value.
  • referencedAttributeId - lookup attribute that self-references the versioned entity. You need to also change the default relationship name to a custom value.
  • attributeVersion - Whole Number
  • attributeVersionDate - Date Time
  • isLastVersion - Boolean

2 Configure the versioned entity's data events

On the entity that you wish to version, create the following event-driven server side scripts:

Name Event Stage Code
<VersionedEntity>_After_Insert Insert After
Copy 
var vh=importLibrary("FTOS.VersioningHelper");
context = vh.VersioningHelper.RunAfterInsert(context);
<VersionedEntity>_After_Update Update After
Copy 
var vh=importLibrary("FTOS.VersioningHelper");
context = vh.VersioningHelper.RunAfterUpdate(context);
<VersionedEntity>_Before_Insert Insert Before
Copy 
var vh=importLibrary("FTOS.VersioningHelper");
context = vh.VersioningHelper.RunBeforeInsert(context);

3 Set Up the Versioning Button

On the form or step where you wish to be able to trigger the record versioning, add the following code in the After Events tab of the Advanced section:

Copy 
var vh = ebs.importClientScript("FTOS_VersioningHelper");
vh.createVersioningContext(formScope);
 

This will display the versioning button, which allows you to create a new version of the currently displayed record.

4 Set Up the Entity Workflow

Assign a business workflow to the versioned entity. You may use any workflow that has at least 4 states which you can map to the Draft, Approved, Version Draft, and Version Closed statuses.

HINT  
FTOS_VersioningWorkflow is an example of a preset business workflow that meets the above criteria.

5 Configure the Version Settings

  1. Go to Main Menu > Admin > Entity Versioning > Version Settings.
  2. Click Insert to create a new set of version settings.
  3. In the Add Version Settings window, enter the following information:
    • Versioned Entity - Name of the entity you are versioning.
    • Status Draft - State in the entity's business workflow you wish to map to the Draft status.
    • Status Approved - State in the entity's business workflow you wish to map to the Approved status.
    • Status Version Draft - State in the entity's business workflow you wish to map to the Version Draft status.
    • Status Version Closed - State in the entity's business workflow you wish to map to the Version Closed status.
    • Name - Assign a name to the set of version settings.

  4. Click Save and Reload.

(Optional) Set Up Related Versioned Entities

When you version an entity record, you may also want to automatically version some of its related entity records. These records belong to entities that have lookup attributes pointing to the versioned entity either directly or indirectly through a stream of intermediate related entities.

This allows you to propagate your versioning to any relevant dependencies. For instance, you may have an insurance product record with a number of related insured items records, each of which has multiple related covered risks records. When you create a new version of an insurance product, you will also be able to create new versions of all its insured items and all of their covered risks at the same time.

To add a related versioned entity, in the Version Settings window of your versioned entity:

  1. Scroll down to the Version Settings Items grid and click Insert .
  2. Fill in the Version Settings Item details as follows:
    • Related Version Entity - Name of the related versioned entity.
    • Versioning Attribute - Lookup attribute pointing to the main versioned entity (either directly or indirectly through a stream of intermediate related entities).
    • Parent Versioned Entity - If the versioning attribute points to the main versioned entity (is linked directly), leave empty. Otherwise (if it is linked indirectly), select the entity the versioning attribute points to.
    • Name - Enter a name for the version settings item.
    • Version Settings - Select the name you assigned to the set of version settings.
    • Is Update - Select if you want the related entity to be versioned together with the main entity.
  3. Click the Save and Reload button at the top right corner of the screen.
  4. Repeat for any additional related versioned entities.

6 Configure the Entity Status Settings

Go to Main Menu > Admin > Entity Versioning > Entity Status Settings and insert settings for each of the Draft, Approved, Version Draft, and Version Closed business states of the versioned entity:

  • Entity - Name of the versioned entity.
  • Is Versionable - Indicates if you can trigger the versioning when a record is in this status (typically, it's the Approved status).
  • Status - State in the versioned entity's business flow you mapped to either the Draft, Approved, Version Draft, and Version Closed statuses.
  • Is Listed - Label you can use for customization purposes. Doesn't impact entity behavior.
  • Is Editable - Indicates if you can edit the record when it is in the current status. For instance, you may want to be able to edit a record that is in Draft or Version Draft status, but avoid editing a record that has been archived (is in the Version Closed status).
  • Is Usable - Label you can use for customization purposes. Doesn't impact entity behavior.
  • Is Duplicable - Label you can use for customization purposes. Doesn't impact entity behavior.
  • Name - Assign a name to the entity status settings.