Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Tip

Role required: admin.

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. It allows associating VCS records with a particular pack and exporting them as a complete set.Local packs allow developing application configurations on a separate instance, exporting it as a .SOP file, and implementing it to another instance.

See the Configuration Packs article to the main instance. This approach allows minimizing risks of mistakes, error and conflicts, which may affect the main instance during application development.

Warning

All system configuration activities should be performed within a separate local pack. Do not use a default local pack for these needs.

Info

Default local pack is a local pack with the Is Default checkbox selected.

learn more.

For configuration pack export, the following elements are used:

  • Local Pack – compiles all relevant VCS records so that they are linked as a complete set. Then these records can be implemented as one configuration pack in another instance. In other words, local pack collects references to records that will be changed, inserted, or deleted on the target instance.
  • VCS Record – contains the version of a record.
  • .SOP file – physical file in the .SOP format. It contains all record versions from the completed local pack. Implement it on any other SimpleOne instance.

Assembling a local pack


Local pack configuration and export includes the following important stages:

  1. Configuring VCS records in a local pack:
  2. Merging several local packs (optional).
  3. Exporting a .SOP file.
Tip

If you are going to export records for a custom application, make sure that the relevant application is implemented in the target instance or that the local pack contains the application VCS record.

Expand
titleHow to import custom applications

If you need to implement the custom application, perform the following steps on the source instance:

  1. Navigate to Configuration → Applications.
  2. Find the application record using the list search or the Condition Builder and open it.
  3. Scroll down to the Related Lists area.
  4. In the VCS Record tab, open a relevant record (with the Is Current=true). 

    Tooltip
    onlyIcontrue
    appendIconinfo-filled
    iconColorblue

    The application will be imported to a target instance even if the Action type of the VCS record is Update.


  5. In the VCS Record form, select the local pack you need in the Local Pack field.
  6. Click Save or Save and Exit.

Local pack is a record in the VCS Local Pack (sys_vcs_local_pack) table containing versions of instance records from the VCS Record (sys_vcs_record) table. Every single version is an atomic state of versioned tables (those ones which have the Is VCS Enabled checkbox selected). All record versions in the local pack are displayed in the Related Lists area.

Image Removed


Team Development

In SimpleOne, developers can work on their task separately you can export separate local packs and upload them one by one. Another option is to work as a team on one task. For this, developers should do their part of work in separate local packs and then combine the results into team's final configuration pack. You can see the process in the scheme below:

Image Removed

Tip

Image Added


Briefly

In brief

, in order to facilitate the team development process, you need to perform the following steps:

  1. Every team member creates a separate local pack and works within it collecting necessary records. The results go into
this
  1. separate local
pack
  1. packs.
  2. When
the development
  1. assembling is over, these local packs must be merged into the
main one.After merging, work on collisions if there are some, and after that, the final configuration pack is ready for implementation
  1. final one.

Create a local pack 
Anchor
create a local pack
create a local pack


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

  1. Navigate to Configuration → Local Packs.
  2. Click New and fill in the fields.
  3. There are two ways to apply changes and continue assembling a local pack:
    • Click Save. Then click Set current to switch the local pack in the Admin Preferences menu and start working on it.
    • Click Set current and Save to switch the local pack in the Admin Preferences menu, apply changes and start working on it
    Click Save or Save and Exit to apply changes
    • .

VCS Local Pack form fields

FieldMandatoryDescription
NameYDefine the name of the local pack.
Is DefaultN
This 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
Select this checkbox to set the local pack as default. When moving version from other local packs, selected VCS records will be moved to this default pack.
StateY

Local pack state. Available options:

  • In progress
  • Completed
  • Ignored
  • Rollback Previewed
  • Rollbacked.
ApplicationN
Specify
Select an application
of
which
record changes are stored in
records this local pack contains. One local pack cannot contain records belonging to different applications.
DescriptionN
Local
Type local pack description.

Managing VCS records

Anchor
restore a vcs record
restore a vcs record


Configure the set of record versions in the VCS Records related list to build the local pack you need. Restore and move records to collect only those you need.

Restoring a VCS record


If you need to restore one of previous record versions, you need to make it actual by clicking Restore Version. Actual records a are marked with the Is current checkbox selected. Thus, restoring is available only to the VCS records with the cleared Is Current checkbox.

Info

Restoring is unavailable for records with the Protected record policy and related to the Simple application.

To restore a record version, please complete the steps below:

  1. Open the record you need.
  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.
Info

Another way to restore a record version is the following:

  1. Navigate to Configuration → VCS Records.
  2. Find the record to be recovered. You can use list search
for
  1. boxes or the Condition Builder.
  2. Open the record you need.
  3. Click Restore Version.

Image Removed

After that, a new VCS record is created in the current local pack.

Removing a VCS record tip

Anchor

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

remove a vcs record
remove a vcs record


VCS records cannot be deleted; therefore, they are moved to the default local packIf your local pack contains a VCS record that is created accidentally or belongs to another configuration pack, you can remove it from this local pack.

To move a VCS record

To do that

, perform the following steps:

  1. Navigate to Configuration → Local Packs.
  2. Open
a record from the table
  1. the local pack containing the VCS record you need to
add the related table
  1. move.
  • In the hamburger menu, select Configure → Related List → Layout.
  • Move the VCS Record->Document Record element from the Available box to the Selected box.
  • Click Save to apply changes.
  • Image Removed

    1. Scroll down to the Related Lists area and open the VCS Record tab.
    2. Select a record or records to be moved using the checkboxes and click Move to Default.
    3. These records will be moved to the default local pack of the same application.

    As a result:

    • All selected record versions are moved to the default pack.
    • All record versions with the same Record IDas the selected ones are moved to the default pack, too. That is, all previous and current versions of the same record are moved.
    Note

    This option is not available in default local packs.

    Changing local pack for a VCS record
    Anchor
    move a vcs record
    move a vcs record


    If a version was

    Moving a VCS record

    If a version has been created in a wrong local pack by mistake (for example, in a default local the default local pack), then you can move it to the required local pack. For this, please complete the steps below:

    1. Navigate to Configuration → VCS Records.
    2. Find a record to recover. You can use list search or the Condition Builder.
    3. Open the record you need.
    4. Click the magnifier icon Image Removed Image Added by the Local Pack field and choose the desired local pack.
    5. Click Save or Save and Exit to apply changes.

    Local

    Pack Merging 

    pack merging 
    Anchor
    merge local packs
    merge local packs


    Sometimes you need to combine two or more local packs together, for example, in case of team development. Merged local packs speed up implementation process and help to arrange updates and development in one pack.

    Info

    Before merging local packs, make sure that:

    • Both local packs
    must be
    • are in the Completed state.
    • Both local packs
    must
    • belong to the same application.

    To merge local packs, please complete the steps below:

    1. Navigate to Configuration → Local Packs.
    2. Choose local packs you need to merge by selecting the appropriate checkboxes, then click the Merge button.
    3. Fill in Define the name and description of the consequent local pack.
    4. Click Merge.

    As a result:

    • A new local pack is created. It contains last latest versions of the VCS Record (sys_vcs_record) from merged local packs.
    • This new local pack state is In Progress.
    • The original local packs are removed.
    • If any versions were referenced to original local packs and didn't get into the resulting one, then this reference is reset.
    Local Pack Exporting
    • VCS records will have the name of the merged local pack in the Local Pack field (instead of removed one).

    Exporting a local pack
    Anchor
    export a local pack
    export a local pack


    After you completed collecting record versions, you need to export the changes for further import to other instances. For this, please complete the steps below:

    1. Navigate to Configuration → Local Packs.
    2. Find the local pack to export. You can use list search for boxes or the Condition Builder.
    3. Open the desired local pack.
    4. Change the state value to Completed.

      Info

      The local pack in the Admin Preferences menu will change to the default pack.


    5. Export the local pack as a .SOP file:
      • at the top of the form, click Export Local Pack.
        OR
      In
      • in the hamburger menu
      Image Removed
      • Image Added, select Export → As a New Application
    Note

    Use this option cautiously. In case the local pack contains updated vendor records, it may cause collisions while updating the system.

    We recommend using the Export Local Pack option.


    Image Added

    Info

    The downloaded .SOP file will be named automatically as this: Local Pack name_2021-12-31 18:00:00

    • Datetime format is YYYY-MM-DD.
    • The timestamp indicates the datetime when the local pack was transferred to the Complete state.
    • The time is displayed according to the locale of the user who exported the file. That is, if the local pack was transferred to the Complete state at 12:00:00 UTC, then for a user from UTC+3 the file will have the 15:00:00 timestamp.
    • If the local pack name contains the symbols listed below, they will be replaced by the underscore symbol ( _ ):

      Code Block
      \, /, :, *, ?, ", <, >, |


    .SOP file export comparison


    Export Local Pack

    Export → As a New Application

    Protection PolicyDoes not change.

    The policy will be changed to Protected or Open depending on the protected.essences property:

    • if the table defined in the Table Name field is included in the property, the policy will change from Changed to Protected
    • if such a table is not included in the property, the policy will change from Changed to Open
    DescriptionUse this export for minor record version changes.

    Use this export for local pack containing a huge number of record versions.

    Note

    Do not use the option Export → As a New Application for local packs containing vendor records. It may cause collisions while updating the system. Instead, use the Export Local Pack option.


    As a result, for all configuration records, which versions are contained in the local pack, the current version (Is Current IS Yes) will be downloaded.

    If there is no current version for a configuration record in the local pack, then the last version that was created will be downloaded as current. This version also will be current when the local pack will be uploaded on the other instance.

    Download

    your local pack straight away after the job is done; otherwise, the versions stored in it may go out of date.

    Tip

    It is a good practice to download

    Tip

    It is a good practice to:

    Give a relevant name to the local pack after exporting, for example:

    GoodNew Incident States.sop
    Bad

    task 1.sop

    2020-08-06_08-47-19_159654161718816631.sop

    Snapshots


    Snapshots restore record versions in the following cases:

    • a record lacks current versions
    • the current version of a record is outdated – when the JSON Copy of this record version has later date than the Updated at field of the record itself.

    In version control systems (VCS), snapshot is the fixed system or database status description.

    There are two ways to create a table snapshot:

    • via table managing form (table configuration)
    • with server-side API class SimpleVcs.
    TipRole required: admin
    • .

    Option 1


    1. Navigate to to System Definition → Settings → All Tables.
    2. Using the search bar and/or a Condition Builder, find the table for which you want to create a snapshot, and navigate to it.
    3. Open the hamburger menu and navigate to Configure → Table.
    4. Click the Create VCS snapshot button 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 TRUEthe Is VCS Enabled checkbox is selected).

    Option 2


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

    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.

    Any completed local pack can be rolled back. Rollback will restore the versions of all the records in this local pack as they were before the start of the update collection within this local pack, or before committing this local pack.

    Deleted records will be restored, and created records will be 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 had any other version.
    Excerpt

    Rollback a local pack

    Any completed local pack can be rolled back. Rollback will restore the versions of all the records in this local pack as they were before the start of the update collection within this local pack, or before committing this local pack.

    Deleted records will be restored, and created records will be 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 had any other version.

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

    1. Navigate to Configuration → Local Pack.
    2. Click on the local pack you need to rollback and navigate into it.
    3. Click Rollback Preview to preview the list of the records that are going to be restored.
    4. Review the contents of the local pack, fix possible collisions if required. After fixing the collision, complete the steps below:
      1. Navigate to Configuration → VCS Preview Log.
      2. Click on the record that was causing the collision.
      3. In the State field, select the Allowed value.
      4. Click Save or Save and Exit to apply changes.
    5. Click Rollback to restore records to the previous version.
    6. Resolve the issues encountered.

    Info

    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.

    Rollback of any local pack is an operation that shouldn't be invoked without an emergency need. Use it cautiously.

    Note

    Do not rollback the Default 1 local pack without an absolute necessity; otherwise, your SimpleOne instance configuration may be damaged.

    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:

    The example script below makes snapshot of all versioned tables within the current application:

    Code Block
    languagejs
    themeEclipse
    titleTable Shapshot Script
    linenumberstrue
    const table = new SimpleRecord('sys_db_table');
    table.addQuery('is_vcs_enabled', true);
    table.addQuery('sys_id', '!=', '999999999999999998'); // exclude REM
    table.selectAttributes('name');
    table.query();
    while (table.next()) {
      const vcs = new SimpleVcs();
      const versionCount = vcs.createTableSnapshot(table.name);
      if (versionCount > 0) {
        ss.info(`${table.name.padStart(80, " ")}: ${versionCount} versions created`);
      }
    }
    


    /

    Update

    Rollback result

    A new tableThe table is dropped from the database, deleting any data from it.A new fieldThe field is dropped from the database, deleting any data from it.A deleted fieldThe field is restored to the database, but the original data is lost.A record is insertedThe record is deleted.A record is deletedThe record is restored with its original data.


    Table of Contents
    absoluteUrltrue
    classfixedPosition
    printablefalse

    >>> Рабочее название: Exporting a configuration pack <<<