Page History

Concept

In briefshort, the VCS configuration pack provides version control in SimpleOne. Version control system allows:

• monitoring changes, tracking who updated the record and when 
• restoring record versions
• transferring record versions created when updating or developing applications between unrelated instances.

VCS records provide a way conception can be defined as an ability to transfer data from one instance to another , in an automatic or semi-automatic way. It is intended for application version control. Configuration packs help to automate transfer data and configurations from one instance to another, lessen the manual effort. The key point is configurations transfer, for not to reiterate it more and more on every instance, you can just import a configuration pack. So, this technology really is to make it easy and automate a migration update from one instance to another.

Application configurations are stored in configuration packs which are represented as a .SOP file containing a set of the application version records. In an OOB supply, the SimpleOne platform contains only the Simple application, but administrators (users with the admin role) can create their own Applications if needed.

Initially, the configuration pack should be assembled on the source instance (the instance containing source data) within the local pack related to the specific application. After that, the local pack can be exported to the configuration pack as a .SOP file.

You can just import a configuration pack in order to avoid recreation of changes on every instance.This technology ensures easy update migration between instances.

For example, your team has created a new application on the development instance. Instead of copying scripts and recreating all elements one by one manually, they assemble a configuration pack and import it to the production instance. While importing this pack into the target instance, the system checks changes for possible collisions. This way, you can make sure that these changes work fine.

Configuration pack flow

Good practice is to develop new applications and implement changes into existing ones on a separate instance. This will lessen mistakes and risks for everyday processes on the production instance. Therefore, VCS records should be collected into one local pack within the relevant application.

The configuration management involves two main processes:

• Export – collecting VCS records into a local pack on Instance #1, the result of which is a Local Pack in the Completed state and a .SOP file.
• Import – uploading and deployment of the previously prepared configuration pack on Instance #2.

To learn more about version control in SimpleOne and more, see the following articles:

• Assembling and exporting local packs
• Importing configuration packs

Image Added

Local packs 

Anchor
local pack local pack

Local packs allow the development of application configurations on a separate instance, exporting it as a .SOP file, and implementing changes to the production instance. This approach minimizes the risks of mistakes, errors, and conflicts, which may affect the production instance during application development.

Using configuration packs allows deploying this configuration on other instances, or, if needed, rollback versions of the specified record or some local pack as a whole to the previous state.

Technically, the configuration pack is the set of the saved records of the Local pack is a record in the VCS Local Pack (sys_vcs_local_pack) table compiling relevant records from the VCS Record (sys_vcs_record) table. Every record of this table contains table. This allows associating VCS records with a particular pack and exporting them as a complete set.

Every single version is an atomic state of versioned tables (those ones which have the Is VCS Enabled checkbox selected). All records in this table contain JSON formatted changes and other attributes described below.

{"value": "Report Item", "policy": "Open", "sys_id": 159653803414986194, "column_id": 156941403909472422, "record_id": 159653803414985080, "language_id": 156628684306541141, "application_id": 155931135900000002, "sys_created_at": "2020-08-04 10:47:14", "sys_created_by": 155931135900000001, "sys_updated_at": "2020-08-04 10:47:14", "sys_updated_by": 155931135900000001}

The configuration pack transfer between instances can be also called "import". On the picture below, you can find the cross-instance configuration versions import flow:

Image Removed

Record versions

After any transaction (create/update/delete) for the versioned table object, the record is created in the VCS Record (sys_vcs_record) table corresponding to the object state after the transaction. The record version contains the information described below.

VCS Record form fields

The table name for the target record.

Transaction type. Available options:

• Create
• Update
• Delete

Application configurations are stored in configuration packs represented as a .SOP file. Administrators can create their own applications if needed.

All record versions in a local pack are displayed in the VCS Record related list.

Image Added

VCS Local Pack form fields

If this attribute value is equal to TRUE, then this version will take precedence over the existing version when the import process will go on.

Local packs

Technically, a local pack is a record in the VCS Local Pack (sys_vcs_local_pack) table related to versions of the related records in a VCS Record (sys_vcs_record) table. Every single version is an atomic state of versioned tables (those ones which have the is_VCS_enabled attribute turned ON). All record versions in the local pack are displayed on a related list on a local pack form.

Image Removed

To create a local pack, please complete the steps below:

1. Navigate to Configuration Pack → Local Packs.
2. Click New and fill in the fields.
3. Click Save or Save and Exit to apply changes.

VCS Local Pack form fields

Version restoring

A non-actual version (the is_current attribute value is equal to FALSE) can be restored if needed. To perform this, please complete the steps below:

1. Navigate to Configuration Pack → Records.
2. Find the record to be recovered. You can use list search for search criteria narrowing, or a Condition Builder.
3. Click on a desirable record to navigate into it.
4. Click Restore Version.

After that, a new VCS record is created in the current local pack; the Restored by field value of this record is equal to the ID of the version used for restoring.

Default local pack

Default local pack is a local pack named "Default 1" created automatically after creating a new application. It is not recommended to use this local pack to store versions for the purpose of further import to other instances; create separate packs for these tasks.

If a version has been created in a default local pack erroneously, then you can move it to the required local pack. For this, please complete the steps below:

1. Navigate to Configuration Pack → Records.
2. Find the record to recover. You can use list search for search criteria narrowing, or a Condition Builder.
3. Click on a desirable record to navigate into it.
4. Click the magnifier icon on the left of the Local Pack field and choose the required local pack.
5. Click Save or Save and Exit to apply changes.

Protection Policy

The Protection Policy (policy) attribute is responsible for the possibility of the record changing (for example, overwriting). It it used, in particular, for data protection purposes.

How it works

When the record in the versioned table is created, its Record and Record Policy attribute values are equal to Open. After first updating, its Record and Record Policy attribute values changes to Changed.

Records with these two states for the Record and Record Policy attributes are freely modifiable.

Also, one more protection policy state for record is Protected. Records with this state cannot be changed or deleted.

Local Pack Exporting

After you are done with record versions collection within the task implementing, you need to export the changes for further import to other instances. For this, please complete the steps below:

1. Navigate to Configuration Pack → Local Packs.
2. Find the local pack to export. You can use list search for search criteria narrowing, or a Condition Builder.
3. Click on a desirable local pack to navigate into it.
4. Change the state value to Completed.
5. Click Export Local Pack link.

As a result, 

Merging Local Packs

Two local packs can be merged in one if necessary. For this, please complete the steps below:

1. Navigate to Configuration Packs → Local Packs.
2. Choose local packs you need to merge selecting the appropriate checkboxes and click the Merge button;
3. Fill in the name and description of the consequent local pack.
4. Wait until local packs are merged;
5. As a result, a new local pack is created referenced with the last versions of the VCS Record (sys_vcs_record) for every record;
6. Resulting local pack transits into the In Progress state.
7. The original local packs are removed;
8. If any versions were referenced to original local packs and didn't get into the resulting one, then this reference is reset.

Local Pack Importing

To deliver an exported local pack on a target instance, the import procedure should proceed. What is implemented within this procedure:

• The transactions stored in configuration pack (a local pack that was exported) are applied on a target instance.
• A local pack copy created on a target instance.

To import a local pack, please complete the steps below:

1. Navigate to Configuration Pack → Retrieved Packs.
2. Click New to create a new configuration pack and fill in the fields.
3. Attach previously exported .SOP file to this configuration pack.
4. Click Save or Save and Exit to apply changes.

VCS retrieved pack form fields

State of the current configuration pack imported. Available options:

• New
• Previewed
• Loaded
• Committed

VCS Records

Anchor
VCS records VCS records

Configuration packs are also used to monitor changes in particular records.

After any transaction (create/update/delete) for the versioned table object, the record is created in the VCS Records (sys_vcs_record) table corresponding to the object state after the transaction. The record version contains the information described below.

VCS Record form fields

{"value": "Report Item", "policy": "Open", "sys_id": 159653803414986194, "column_id": 156941403909472422, "record_id": 159653803414985080, "language_id": 156628684306541141, "application_id": 155931135900000002, "sys_created_at": "2020-08-04 10:47:14", "sys_created_by": 155931135900000001, "sys_updated_at": "2020-08-04 10:47:14", "sys_updated_by": 155931135900000001}

The import process includes three phases:

1. Preview
2. Import
3. Apply

Preview

During this phase, the import engine checks for the possible conflicts before the pack is imported. To preview the configuration pack, please complete the steps below:

1. Navigate to Configuration Pack → Retrieved Packs.
2. Find the configuration pack to preview (it should not be previewed before, so the state should be equal to New).
3. Click on it to navigate into it.
4. Click the Preview Local Pack link.

As a result:

1. The VCS Preview Log records are created and displayed at the related list appropriate for this configuration pack.
2. The configuration pack state changes to Previewed.

VCS Preview Log fields description

Restoring VCS

Records

All the record versions – both previous and current – are stored in the VCS Record table. Current versions have the Is Current checkbox selected.

If you need to restore one of the record previous versions,

Import

complete the steps below:

1. Navigate to Configuration Pack → Retrieved Packs.
2. Find the previously previewed configuration pack (the state should be equal to Previewed).
3. Click the Import Local Pack button.

As a result:

• VCS records are created on the target instance with the attributes as listed below:
  • Is Current = FALSE
  • Not related to any local pack in the system.
• The retrieved pack state changes to Loaded.
• The date and time of this operation are displayed at the Loaded at field.

Apply

The final import phase is an applying. For this, please complete the steps below:

1. Navigate to Configuration Pack → Retrieved Packs.
2. Find the previously imported configuration pack (the state should be equal to Loaded).
3. Click Apply Local Pack.

As a result:

• A local pack record on a target instance is created.
• All versions created on the previous stage are copied onto this local pack.
• The is_current attribute value for these records changes to TRUE.
• The retrieved pack state changes to Committed.
• The date and time of this operation are displayed at the Committed at field.

Snapshots

In version control systems (VCS), snapshot is the fixed system or database status description. To create a table snapshot, a table managing form can be used, and also, server-side API class SimpleVcs was implemented.

Role required: admin.

Option 1

1. Navigate to System Definition → All Tables.
2. Using the search bar and/or a Condition Builder, find the table you want to create a snapshot and navigate into it;
3. Click the Create VCS Snapshot button at the right top. This button is visible only when the versioning for this table is on (the is_vcs_enabled attribute is set to TRUE).

Option 2

1. Navigate to System Definition → Scripts.
2. Write down a script and call SimpleVcs#createTableSnapshot(tableName) method in it.

In both cases, the result is the snapshot, that is, the set of the VCS records for all the documents in this table that do not have such records at the moment of the snapshot creating.

Rollback

Rollbacks in brief

1. Any completed local pack can be rolled back;
2. Rollback will restore the versions of all the records in this local pack as they were before update collection within this local pack started, or before committing this local pack.
3. Deleted records are restored, and created records are deleted.

Example

• Before local pack committing, the record had a version X;
• After the local pack committing, it has version Y;
• And after rollbacking, it will have version X again, even if after local pack completing it has had any other version.

How to rollback a local pack

To rollback a local pack, please complete the steps below:

Resolve the issues encountered.

1. The currently selected application affects what options are available for the local pack. So please make sure that you select the application, such as Platform, that matches the content of the local pack.
2. Do not rollback the Default 1 local pack without an absolute necessity; otherwise, your SimpleOne instance configuration may be damaged.
   1. Rollback of any local pack is an operation that shouldn't be invoked without an emergency need; so use it cautiously.

1. Open the record which version you need to restore.
2. Scroll down to the Related Lists area and open the VCS Records tab.
3. Open the record version you need to restore.
4. Click Restore Version.

Image Added

After that, a new VCS record is associated with the current local pack. It will be displayed in the VCS Records related list.

Protection Policy

Anchor
protection policy protection policy

The Protection Policy attribute is responsible for data protection purposes. After creating a record in the versioned table, the Protection Policy for this record is Open. Once the record is updated, the Protection Policy becomes Changed. These values are transferred to the Record Policy field in the related VCS record, that is, the record version has the same Policy as the record itself.

Admin can update only the Local Pack and Is Strong Overwrite fields of records with any protection policy.

During the importing process, the records possible to overwrite can be updated. Both record policy values set in the system and in the configuration pack are taken into account. All possible policy combinations are described in the table below.

/

This process both record updates and dictionary changes. Some changes caused by the rollback may lead to data loss.

Here is the expected result of the process:

Update

Rollback result