Versioning

Overview

Versioning (also known as SmartVersioning) is a SmartSimple feature that facilitates the creation of concurrent versions of applications and forms while utilizing a shared set of underlying fields. 

Versioning allows for the storage of multiple versions of the same list of fields in a single location without necessitating alterations to the content of previous versions or the need for a test-to-production environment. This feature enables you to test and utilize a new version prior to its deployment.

The Versioning process begins with a core field set that encompasses all fields from all applications, allowing you to select the specific fields desired for any new version you are developing. You may add as many fields as necessary for your master baseline copy. When you are prepared to create a new version of an application or form, Versioning captures a snapshot of your core field set, which serves as a copy of all custom fields and their respective settings. This snapshot constitutes the baseline that will serve as the foundation for your new version.

Benefits of Versioning:

• Significantly decreases the effort required to manage changes in forms and applications.
• Facilitates the easy creation, modification, and testing of forms prior to deployment.
• Maintains the values and appearance of previous forms, enabling System Administrators to access earlier versions of forms in their original format.
• Configuration of the Versioning setting in your system requires System Administrator privileges.

Configuration - Essentials

How Versioning Works

Versioning commences by capturing all underlying fields that constitute an application or form; this comprehensive set of fields is referred to as the "baseline." The baseline encompasses all fields across all application and form versions. The initial step in utilizing Versioning is to create a new "version," which involves assigning a Name, Description, selecting the Application Name and Entity that encompasses the field set, and taking a Snapshot of the field set to establish the baseline. 

Please follow the steps below to create the baseline. 

Create a New Version

System Administration (gear icon) >> Tracking Applications >> [Edit] *UTAname >> Level 1/2/3 (tab) >> SmartVerioning

Any existing versions that have already been created in your system may be listed here. If you wish to edit these versions, simply click the pencil icon located to the left of each version name.

1. To create a new version, click the + icon located in the upper left corner. 

2. The New Version form will be displayed. Complete the fields in this form.

• It is mandatory to complete at least the Name and Description fields to save a new version.
• Tip: Providing clear and appropriate titles/descriptions for versions will be highly beneficial. For instance, distinctly naming the baseline version will help differentiate it from any subsequent versions (e.g., Baseline General Application). It may also be advantageous to adopt a standard naming convention, such as naming application and form versions based on their respective time periods (e.g., 2016 Q1 General Application) to easily identify when the versions were created.
• Tip: Using period-based dates such as Up to 2020 Budget Manager is particularly beneficial for future-oriented Versioning; label the Version accordingly to indicate that it will not be activated until the appropriate time arrives. 

6. After you have completed the information in the fields, click the Save button. 

Create a Baseline

Once you have created and Saved a new version, the page will refresh to display the date and time stamp of the creation/modification, the name of the creator/modifier, and the Version Objects section. In the Version Objects section, we will capture the snapshot that constitutes the baseline field set for this version.

1. Click on the Select Application field - a drop-down list of available applications within the system will appear.

Select the application for which you would like to save a version of its fields. 

2. After selecting an application, click on the Entity field, which will open a drop-down list of the associated entities with that application. All Level 1, Level 2, and Level 3 entities will be available. 

Select the specific entity level of your application to form the field set that you wish to capture. 

Note: If no specific level is selected, the system will default to the Level 1 of that application. For example, it will default to Budget if the application in question is the Budget Manager. 

3. Once both the Application Name and Entity have been selected, click the button on the right side: Take Snapshot. 

4. A confirmation pop-up message will appear. Click Yes.

5. After confirming, the Version Objects section of the version form will refresh and display the time and date stamp of the snapshot. 

The details highlighted in red comprise the snapshot you have taken - all fields included with that application and entity level at the time of the snapshot constitute the baseline. 

• Note: You may wish to capture field sets from Level 1, Level 2, and Level 3. In this case, you will repeat the aforementioned steps to create additional Version Objects lines to capture any further objects, activities, or transactions.
• Tip: It is beneficial to repeat the process and capture field sets from all levels of an application, especially if they are interrelated.
• Note: A snapshot does not imply that the version is active; the version will not be activated (meaning it will not be utilized in relation to the field set of that version) until you activate the version in your system.

Finding the Current Version

Having followed the procedures outlined in the preceding sections, you have successfully enabled Versioning within your system and created your initial snapshot. By default, your Current version is your baseline version. You can verify the current version utilized in your system at any time by adhering to the steps below: 

1. Navigate to the desired entity whose Version you wish to confirm. 

Note: You can access any UTA by clicking the 9-square menu icon in the upper right corner and selecting the UTA name under the heading Applications.

2. Click on the UTA settings icon - the gear icon - which will grant you entry into Configuration Mode. 

3. Scroll down to the subheading Features and Options. 

4. Locate the Current Version field, which will display the current version of that UTA.

Note: To modify the current version, click on the dropdown menu and select the new version you wish to activate, then click the "Activate" button, followed by clicking the Save button at the bottom of the window.

Custom Fields and Versioning

Once Versioning is enabled for a UTA object, the list of Custom Fields associated with that object will also indicate an Active Version in the upper right corner of the page. 

1. After navigating to the desired UTA, click the gear icon above its name to enter Configuration Mode.

2. Click on the tab corresponding to the level of object for which you have enabled Versioning. 

3. Click on the hyperlink labeled Custom Fields.

At the top of the list of custom fields, you will find the Version combo box. 

The Version combo box contains the name of the version of the application or form you are currently editing. This field allows you to switch between the different concurrent versions that are available. Here is where you will alternate between the baseline application version, the current application version, and the new application you are developing and testing.

The individual Custom Field Setting page will also indicate the Active Version at the top alongside a Version combo box.

Additionally, there will be a Set button that allows users to edit fields in a specific version, and a Diff button that enables users to compare fields between one Version and another.

Editing Fields in Versions

1. Navigate to the desired UTA.

2. Click on the gear icon above the UTA name, which will direct you to the UTA settings

3. Click on the relevant tab for Level 1, Level 2, or Level 3 entity associated with the UTA. The levels are organized sequentially - the first tab following the General tab represents the Level 1 Entity, and so forth. 

4. Click on the Custom Fields hyperlink. 

5. From the Version drop-down option in the upper right corner, select the Version whose fields you wish to edit.

The list of Custom Fields displayed will vary depending on what has been saved as the field set for the selected Version. 

6. To edit a specific field, click the pencil icon to the left of the custom field name.

You will be directed to the Custom Field edit page for that field. Make any necessary modifications to the version you are working on.

• Please note that these edits will only impact the current version you are editing - which can always be identified by the text box in the upper right corner - unless you are making changes to the baseline version.
• For further information on editing a Custom Field, please refer to our Custom Fields - General Settings page. 

Deleting Fields in Versions

It is imperative to always verify the version you are currently editing. Exercise caution when removing fields from the baseline version, as doing so will result in the deletion of those fields from all associated applications and forms. Subsequent snapshots taken will not include the deleted fields. Furthermore, removing fields from the baseline will eliminate your ability to reference those fields and their corresponding values, thereby negating the use of previously stored values.

In contrast, deleting fields from versions that are not the baseline will only remove those fields from the specific version you are editing; they will remain intact in other versions.

To delete a field, select the checkbox next to the desired field(s) for deletion. A trash can icon will then appear in the top row of buttons. Clicking this icon will initiate the deletion of the selected fields.

• Please remember that you can always identify which version you are in by referring to the Active Version text box located at the top right of your page.
• To delete an entire version (not merely an individual field), this action can only be performed when there are no fields associated with it.

Comparing Fields in Versions

1. Navigate to the desired UTA.

2. Click on the gear icon located above the UTA name.

3. Select the appropriate tab for Level 1, Level 2, or Level 3 entity associated with the UTA. The levels are organized sequentially; the first tab following the General tab represents the Level 1 Entity, and so forth.

4. Click on the Custom Fields hyperlink.

5. Click the pencil icon to edit a specific Custom Field.

6. The details of the Custom Field will be displayed. In the top right corner, the Active Version is shown. To the right of the Version field box, select the Diff. button.

7. A modal window will appear, allowing for Version Comparison, displaying the custom field settings for two different versions side-by-side.

To switch between the versions you wish to compare this custom field against, simply select different versions by clicking into each Version field.

Creating a New Field

The best practice for creating new fields is to initially add them to the baseline version. This ensures that the new field becomes available to all versions once an updated snapshot is taken.

1. Navigate to the desired UTA.

2. Click on the gear icon above the UTA name.

3. Select the appropriate tab for Level 1, Level 2, or Level 3 entity associated with the UTA. The levels are organized sequentially; the first tab following the General tab represents the Level 1 Entity, and so forth.

4. Click on the Custom Fields hyperlink.

5. Click on the '+ icon' on the left-hand side to create a new field.

6. Fill in all the required fields to create your new field. For further details on creating custom fields, please refer to Custom Fields – General Settings.

Adding All New Fields to an Existing Version

If you wish to perform a mass update of fields to an existing version, you can do so by updating the Version Snapshot. This will refresh the field sets that comprise the selected version and will include any newly added fields to the baseline since the last snapshot.

For details on how to take a snapshot, please see Create a Baseline.

Add or Update Individual Fields to a Previous Version

There are instances when a user may desire to implement a new custom field in a previous version, or they may wish to modify an individual field without creating a snapshot that could inadvertently apply undesired updates to other fields in that older version.

To accomplish this, please adhere to the following steps: 

1. Navigate to the desired UTA.

2. Click on the gear icon located above the UTA name, which will direct you to the UTA settings.

3. Select the appropriate tab for Level 1, Level 2, or Level 3 entity associated with the UTA. The levels are arranged sequentially; the first tab following the General tab represents the Level 1 Entity, and so forth. 

4. Click on the Custom Fields hyperlink.

This will display the list of Custom Fields.

5. Select at least one custom field for which you wish to apply its updated modifications to a previous version. If no fields are selected, the Copy to Older Version function will not be available.

6. Click the Copy to Older Version option, represented by a two-page icon located on the top row of buttons.

7. A modal window will appear, allowing you to select which version you wish to apply this updated field to.

8. Click the Submit button.

The modal window will refresh, and a confirmation message of Update Completed will be displayed if the field was successfully updated to the older version(s).  It is not possible to copy a Version ''into ''a core field-set; this is a unidirectional process.

Viewing Changes to the Application/Form

The modifications made to a version view can be observed by opening the application or form and selecting the appropriate form document.

1. Navigate to the desired UTA.

This can be accomplished by clicking the 9-square menu icon in the upper right corner of your page and selecting the UTA under the heading Applications.

2. Open the desired application or form.

3. From the Version drop-down menu in the upper right corner, select the version you wish to view. 

Switching between the different versions will enable you to easily transition between the existing form and your modified version, allowing you to monitor the changes from the applicant's perspective.

Activating a New Version

1. Navigate to the desired UTA.

This can be achieved by clicking the 9-square menu icon located in the upper right corner of your page and selecting the UTA under the heading Applications.

2. Click on the gear icon located above the UTA name, which will direct you to the UTA settings in Configuration Mode.

3. Select the appropriate tab for Level 1, Level 2, or Level 3 entity associated with the UTA. The levels are arranged sequentially; the first tab following the General tab represents the Level 1 Entity, and so forth, in chronological order.

4. Under the subheading Features and Options, locate the Current Version field.

5. Click on the drop-down menu of available versions and select the version you wish to activate for your UTA.

6. Click on the Activate button to the right of this field.

7. A confirmation message will appear; click Yes. 

8. Once the version has been activated, another confirmation message will appear indicating that the activation was successful. Click OK.

Note: Once an application or form is activated, all new submissions will be associated with the current version; however, previous submissions will retain their original version information. 

Batch Updating Records to Versions

To update multiple applications and forms to a new version, begin by creating the new version, and then utilize the batch update feature to update as many applications and forms as desired.

1. Navigate to the desired UTA.

This can be achieved by clicking the 9-square menu icon located in the upper right corner of your page and selecting the UTA under the heading Applications.

2. Check the box on the right of each application you wish to bulk update.

3. Click on the Batch Update icon located in the upper right corner of your page.

The Batch Update modal window will appear.

4. On the left side, you can select which fields you wish to update. Upon selecting a field, its options will appear on the right side. You can either select from the drop-down menu or utilize the binocular icon to search for the options available for batch updating the records for each field. 

5. Once you have completed selecting your batch update options, click the Update button at the bottom of the modal window. 

Custom Batch Update

Adjacent to the Batch Update button is a down arrow button that provides access to the Custom Batch Update. The available options include creating a Copy of the applications as well as modifying the status of the applications.

If you select Batch Update Copy, a confirmation message will appear to verify your intention to copy and initiate the workflows associated with all selected records.

If you opt for the second option (Approved), you will execute the Batch Update to modify the status and trigger the workflows associated with all selected records.

• In this example, a UTA with grants as the Level 1 Entity can be selected and batch Approved so that the status of each grant selected is changed to approved simultaneously.
• Upon successful record updates, the list will refresh, and a pop-up notification will appear at the top of your screen confirming the number of records that have been updated.
• Note the Approved status of the record that was successfully updated. This record will also now appear in the second tab, within the list of Approved grants.

Configuration - Advanced

Conditional Versioning

Conditional Versioning enables the display of a tailored version of an application or form to specific users based on predefined conditions.

Conditions may encompass (but are not limited to):

• Geography
• Role
• Organization type
• Record type
• Age
• Conditions may also be established based on the individual fields that constitute an application or form. Any field can serve as the basis for a condition.

Each version includes a Condition field. In the example below, the condition evaluates the value entered in the Country field against the current user's profile, and the current version will only be displayed if the Country is not set to Canada.

Reporting with Versions

Once multiple versions have been created, you can select which version to include in your Reports by navigating through the available versions.