Entity Cloning and Versioning

Cloning allows you to replicate entity records for a variety of operations such as:

  • Reducing redundant manual entries when creating similar records.
  • Using standard records as templates with pre-filled attribute values.
  • Duplicating data for various purposes such as testing, training, or demos.

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. Versions can be used to preserve snapshots of the a record's values at different points in time, aiding in auditing or other regulatory requirements. The versioning process uses Business Workflows 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 record 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. When the version draft is ready for approval, 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.

How to Set Up Cloning and Versioning on an Entity

1 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 with the corresponding transitions.

HINT  

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

2 Configure the Clone and Version Settings

Use the FTOS_Versioning_Setting system entity to configure sets of clone and version settings that track your versioned entities, statuses, naming convention suffixes, etc. For this purpose, you can expose one of the entity's Data Views or Data Forms in one of theFintechOS Portal instance's Dashboards or Menu Items.

For instance, you can use the FTOS_Versioning_Setting entity's default form to populate the following fields:

  • Name - Assign a name to the set of clone and version settings.
  • Versioned Entity - Name of the entity you are making available for cloning or versioning.
  • Is Versionable - Toggles if the entity is available for versioning or only for cloning.
  • Naming Suffix Keys - Comma separated list of placeholders which will be replaced with suffixes to be appended to the cloned/versioned records' primary attributes.
  • Status Draft - State in the entity's business workflow you wish to map to the Draft status. Mandatory if the entity is versionable.
  • Status Approved - State in the entity's business workflow you wish to map to the Approved status. Mandatory if the entity is versionable.
  • Status Version Draft - State in the entity's business workflow you wish to map to the Version Draft status. Mandatory if the entity is versionable.
  • Status Version Closed - State in the entity's business workflow you wish to map to the Version Closed status. Mandatory if the entity is versionable.

(Optional) Set Up Related Versioned Entities

When you clone/version an entity record, you may also want to automatically clone/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 cloning/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.

For this purpose, scroll down to the FTOS Versioning Settings Items section and add the desired dependencies:

  • 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.
  • 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).
  • Disable Version or Clone - Allows you to temporarily disable cloning and versioning for the related entity.
  • Apply Naming Convention - Propagates the naming suffix keys to the related entity.

How to Clone an Entity Record

Use the ftos.data.clone Server SDK method to create a clone and retrieve its record ID.

How to Version an Entity Record

To clone or version an entity record:

  1. Use the ftos.data.version Server SDK method to create a draft version of the desired entity record.
  2. Make your edits on the draft version.
  3. Use the ftos.data.closeLastApprovedVersion Server SDK method to close the approved record version and redirect its references to the version draft.
  4. Approve the draft using the corresponding Business Workflows transition.

For example:

Copy 
var myEntity = ftos.context.entityName;
var currentRecord = ftos.context.id;

// Create a new draft version of the current record based on the version_config clone and versioning settings
var myDraft = ftos.data.version(currentRecord, version_config);

// Redact the first name and last name in the draft
ftos.data.update(myEntity, myDraft, { FirstName: 'Redacted', LastName: 'Redacted' });

// Close the previously approved version and redirect references to the draft
ftos.data.closeLastApprovedVersion(myDraft, version_config);

// Approve the draft
ftos.businessStatusWorkflow.update(myEntity, myDraft, ftos.businessStatusWorkflow.getId(myEntity, 'Approved'));

Legacy Entity Versioning (Deprecated)

Starting with v24.3, the entity versioning mechanism has been updated based on the model described above. For information on the legacy entity versioning mechanism, see the v24.2 documentation.