Entity Versioning

Entity versioning allows you to implement a record update process that is certified and documented. The versioning process uses the Business Workflows Processor to assign different states to a record indicating if it is:

• a draft that hasn't been approved yet
• the currently active version of the record
• a discontinued prior version
• a substitute version that is a candidate to replace the currently active version.

The entity versioning process is illustrated below.

1. The original record starts out in a Draft state.
2. Once the draft is validated, the record goes into the Approved state, indicating that this it is the currently active version of the record.
   NOTE  
   Only one version of the record can be active (in the Approved) state at one time.
3. To modify an active record, you need to create a secondary version of it. The secondary version starts out in the Version Draft state, while the original record remains in the Approved state.
4. If the version draft is approved, then the original record transitions into the Version Closed state and the secondary version becomes the Approved currently active entity record.
5. The process can then be repeated from step 3 whenever a new version of the record is necessary.

Entity versioning is useful when you need a thorough validation and tracking of your record updates, such as when storing information about security roles or customer documents.

How to Set Up Versioning on an Entity

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:

var vh=importLibrary("FTOS.VersioningHelper");
context = vh.VersioningHelper.RunAfterInsert(context);

var vh=importLibrary("FTOS.VersioningHelper");
context = vh.VersioningHelper.RunAfterUpdate(context);

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:

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.

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 Save and Reload.
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.

Example of How to Version an Entity Record

After you have set up versioning on an entity, you can start versioning its individual records.

1. When a record reaches a business state that is versionable (see 6 Configure the Entity Status Settings), the versioning button will be displayed on the form or step you have set up accordingly (see 3 Set Up the Versioning Button).

   

2. If you click the versioning button, a new record version will be created and opened in the Version Draft status. By default, the text "new version" will be appended to the record's primary attribute.

   

3. If you approve the version draft, the new version becomes the active record and the original record automatically transitions into the Version Closed status.