The SimpleOne system allows exporting and importing configuration packs to keep unrelated instances synchronized.

Concept

In brief, the VCS configuration pack 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.

There can be more than one local pack in the system, but the changes made by a single source can be written only in one localpack at every moment. You can choose the preferable localpack using the Preferences menu at the right. Please refer to the Interface#AdminPreferences article for the details.

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.

Please note: all system configuration activities should be performed within a detached local pack (do not use default local pack for these needs).

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 VCS Record (sys_vcs_record) table. Every record of this table contains 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:


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

FieldDescription
RecordAn ID of the source record processed by the transaction.
Table name

The table name for the target record.

Please note that only system names for tables are used in this field, not titles.

Right: sys_vcs_record.

Wrong: VCS record.


Record document

This ID stores table name and target record ID for which the current record is created. For example:

Is CurrentThis attribute is responsible for current version relevance. When its value is equal to TRUE, then the version corresponds to the target record state relevant for now.
JSON CopyThe record version data in JSON format as an associative array. This array stores the target record object relevant state after the transaction.
Action

Transaction type. Available options:

  • Create
  • Update
  • Delete
Local packReference to the local pack containing this record version.
Retrieved packReference to the configuration pack containing this record version.
Restored byThe ID of the record version from which the current version has been restored.
Platform versionThe solution platform version used for version creating.
ApplicationA related application containing the target record.
Is Strong Overwrite

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.

Record PolicyThe current record protection policy after the transaction is over.

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.


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

FieldDescription
Origin IDThis ID is assigned to the local pack after creating it on a source instance.
IDThis ID is assigned to the local pack after importing.
Is DefaultThis attribute defines that this local pack will be set as default for any user changing the application to the one specified in the Application field.
ApplicationSpecify an application of which record changes are stored in this local pack.
NameLocal pack name.
DescriptionLocal pack description.
State

Local pack state. Available options:

  • In Progress
  • Completed
  • Ignored
  • Rollback Previewed
  • Rollbacked.
Completed atThe date and time when the local pack state changed to Completed.
Completed byReference to the user who has set the state to Completed.

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.

You can add a versions list to the versioned table form as a related list. After that, all previous versions of the current record are displayed on the record form.


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.


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, 

Recommendations:

  1. It is a good practice to give a relevant name to the local pack after exporting, for example:
    1. Good - "New Incident States.sop"
    2. Bad - "some task.sop", or leaving the name generated by system, like this: 2020-08-06_08-47-19_159654161718816631.sop
  2. Also, it is recommended to download your local pack straight away after the job is done; otherwise, the versions stored in it may go out of date.


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.

Team Development

In SimpleOne, you can perform your parallel development on multiple instances. For now, team development is represented an an operation approach and is handled by two engines:

  1. Configuration packs;
  2. Merging.

In brief, in order to facilitate the team development process, you need to perform the steps below:

  1. Every team member does his work part; it is written down on the instance in the configuration pack;
  2. When the development is over, these configuration packs must be exported onto the main one and merged;
  3. After merging, work on collisions if there are some, and after that, the final configuration pack will be the result of the team development.

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

FieldDescription
NameRetrieved Pack name, taken from the SOP file attached.
State

State of the current configuration pack imported. Available options:

  • New
  • Previewed
  • Loaded
  • Committed
Remote IDID of the local pack exported.
Remote ApplicationApplication specified in the local pack exporting.
ApplicationSpecify the application within which the pack should be imported.
InsertedThe number of records in this pack with the Action attribute value equal to Insert.
UpdatedThe number of records in this pack with the Action attribute value equal to Update.
DeletedThe number of records in this pack with the Action attribute value equal to Delete.
WarningThe number of the Preview Log records with the State equal to Warning.
SkippedThe number of the Preview Log records with the State equal to Skipped.
CollisionsThe number of the Preview Log records with the State equal to Collisions.
TotalTotal records number.
DescriptionRetrieved Pack description, taken from the SOP file attached.
Loaded atThe date and time when the configuration pack import has been finished (the state has been changed to Loaded).
Committed atThe date and time when the configuration pack was applied (the state has been changed to Committed)

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

FieldDescription
Local PackReference to the local pack containing this preview log record.
Retrieved packReference to the configuration pack containing this preview log record.
Record Document

Table Name

The table name for the target record.

Please note that only system names for tables are used in this field, not titles.


RecordThis ID stores table name and target record ID for which the current record is created.
Platform VersionThe solution platform version used when the record created.
JSON CopyThe record version data in JSON format as an associative array. This array stores the target record object relevant state after the transaction.
Error TextThe error text displayed in case of collision (the preview log record state is equal to Warning or Skipped or Collision).
State

The preview log record state. Available options:

  • Good
  • Allowed
  • Warning
  • Skipped
  • Collision
Action

The type of transaction created the version object. Available options:

  • Create
  • Update
  • Delete

If the record with action = Update is absent on target instance, then it is imported with the action = Insert (the new record is created instead of updating the existing one).


Record Policy
Is Strong OverwriteThis attribute determines the priority of the imported version over the existing one.
VCS RecordThe related version record created after configuration pack importing.
ApplicationThe application within of which the preview has been executed.


Import

After the configuration pack has been previewed, preview log records have been analyzed and possible collisions have been solved, you can proceed with further configuration pack importing. For this, please 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.




Политика/Policy

Значение Policy определяет возможность изменения записи. После создания записи в версионируемой таблице, ее Policy и Record policy ее версии принимают значение Open. 

После первого обновления записи, значения ее Policy и Record policy ее версии меняются на Changed.

Записи в статусе Open и Changed могут свободно редактироваться. При импорте версии с Record Policy = Open, при условии что целевая запись на инстансе редактировалась (Policy = Changed) будет возникать коллизия "Don't update, record is changed".

Еще одно допустимое значение Policy - Protected. Записи с данным значением политики не могут быть изменены или удалены.