Assembling and exporting local packs

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 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:
   • restoring records (optional)
   • moving records (optional)
2. Merging several local packs (optional).
3. Exporting a .SOP file.

Team Development

In SimpleOne, 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 pack. You can see the process in the scheme below:

Briefly, 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 separate local packs.
2. When assembling is over, these local packs must be merged into the final one.

Create a local pack 

To create a local pack, 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.

VCS Local Pack form fields

Managing VCS records

Configure the set of record versions in the VCS Records related list to build the local pack. 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 are marked with the Is current checkbox selected. Thus, restoring is available only to the VCS records with the cleared Is Current checkbox.

To restore a record version, 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.

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

Removing a VCS record

VCS records cannot be deleted; therefore, they are moved to the default local pack. If 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, perform the following steps:

1. Navigate to Configuration → Local Packs.
2. Open the local pack containing the VCS record you need to move.
3. Scroll down to the Related Lists area and open the VCS Record tab.
4. Select a record or records to be moved using the checkboxes and click Move to Default.
5. 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 ID as the selected ones are moved to the default pack, too. That is, all previous and current versions of the same record are moved.

Changing local pack for a VCS record

If a version was created in a wrong local pack by mistake (for example, in the default local pack), then you can move it to the required local pack. For this, 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 by the Local Pack field and choose the desired local pack.
5. Click Save or Save and Exit to apply changes.

Local pack merging 

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.

To merge local packs, complete the steps below:

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

As a result:

• A new local pack is created. It contains 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.
• VCS records will have the name of the merged local pack in the Local Pack field (instead of removed one).

Exporting 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 boxes or the Condition Builder.
3. Open the desired local pack.

4. Change the state value to Completed.

   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 the hamburger menu , select Export → As a New Application. 

.SOP file export comparison

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.

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.

Option 1

1. Navigate to System 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 at the right top. This button is visible only when the versioning for this table is on (the Is VCS Enabled checkbox is selected).

Option 2

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

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

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`);
  }
}

/