Context
When you build an event form, you should spend time ensuring that the form meets the required specifications and that it works as expected. However, changes to the specifications might be needed and you find that the original format of the form isn’t suitable anymore. You could create new form to match the updated specifications but if the changes required are minor and continuity of the data is important, it can be better to update the existing form. Doing so will mean that other features such as dashboards, favorite events, notifications and roles can still reference the same event form and that the historical data trail is confined to the one event form, rather than being spread across the Smartabase site.
The major consideration when deciding whether to update an event form is whether any data will be lost. When data is saved to an event form, it is saved to a particular field name or an option name. If that name is changed or deleted without proper precautions, any data saved to the original field or option name is lost.
For this tutorial, we’ll be referring to an event form that is used to collect information about a student’s practicum placement. The event form contains a Dropdown field with a list of discipline areas for the student’s placement and a second Dropdown field with a list of sub-disciplines, depending on the discipline area selected. In this scenario, the workflow is currently in use and a large amount of data has been saved to the form.
A recent change to the curriculum means that some updates to the discipline areas are required:
- Students can now select Public health as a discipline area.
- The Nutrition discipline area is no longer available to students.
- The OH&S option should be changed to Occupational health and safety to be consistent with the other options (i.e. no abbreviations) and be more informative to students.
Additionally, there is currently no intentional sorting order for the options and arranging them in alphabetical order may assist students in selecting the appropriate option. The table below shows the current list of discipline areas compared with the updated list, with the new option shown in green text, the archived option shown in red text and changes shown in orange text.
Current discipline areas | Updated discipline areas |
Exercise physiology |
Education |
A second Dropdown field named Sub-discipline has options which are conditional based on the discipline area selected. The sub-disciplines for each discipline are listed in the table below.
Discipline area | Sub-disciplines |
Education |
Primary institution |
Exercise physiology |
Public hospital |
Occupational health and safety |
Process documentation |
Public health |
National organization |
Research |
Masters |
Sport science |
Physiology |
Goals
The first goal of this tutorial is to update the options in an option-type field within an event form without losing any existing data. The second goal is to update corresponding fields, performance standards, performance alerts and dashboard settings that are dependent on the options.
Outcomes
For this tutorial, you can choose to build your own version of this form from a blank template or you can import the event form attached in the Resources section below.
You may also like to enter some sample data to replicate the scenario of updating records that already contains data. We have provided some sample data for the event form in the Resources section below.
Listed below are the outcomes that you will achieve in this tutorial:
- Generate a back-up copy of the data (optional).
- Update options for a field.
- Update other features that reference the option names.
Outcome 1: Generate a back-up copy of the data (optional)
To reduce the risk of data loss if you make a mistake with the process below, you can generate a back-up of the data. To do this, follow the steps below.
- Log into Smartabase Online.
- Ensure you have a group loaded that contains all user accounts where data for this form would be saved. If this is not available, you can create a group in the administration interface which contains all user accounts.
- Generate a report for the event form.
- Hover over the Export button above the report and select Excel from the dropdown list.
- In the pop-up window, choose the Full export option to include all fields in the export and select Create Excel report.
Outcome 2: Update options for a field
This outcome consists of three components as listed below. These components can be resolved in any order, but we will follow this sequence of events:
Add new options
- Log into the builder interface.
- Go to the Event forms tool and open the event form that you will be using for this tutorial. If you are using the event form provided in the Resources section, the event form is named Practicum placement details.
- Select the Dropdown field named Discipline area.
- In the Option properties, add a new option named Public health. This could be added to the end of the list or within the list; since we want the options to be displayed in alphabetical order, we will add it underneath OH&S. Select Update to save your changes.
- Go to the Scoring properties and provide a score for the new option if applicable. There are no scores attached to the discipline areas so this can be left blank. Select Update to save any changes you have made to the scores.
- In the Option properties, add a new option named Public health. This could be added to the end of the list or within the list; since we want the options to be displayed in alphabetical order, we will add it underneath OH&S. Select Update to save your changes.
- Select the Sub-discipline area field and go to the Option properties. At the bottom of the list, add the new option followed by a colon (Public health:) and enter National organization and State organization as options beneath it.
- Preview the event form to ensure that the sub-disciplines are displayed when Public health is selected.
- Save the event form. A confirmation message may appear as a pop-up window with a warning that the Discipline area and Sub-discipline fields have been changed. As long as none of the other options were changed, you can select Confirm save and data will not be lost. A second pop-up warning will also ask you to confirm the update.
Update existing options
- Go to the Event forms tool on the builder interface.
- Search for the Practicum placement details form and select the Migrate option(s) button to the right of the form name.
- Two pop-up windows will appear to confirm that no other migrations have recently been run. If this is not the case, select OK for both messages.
- The next pop-up window will allow you to select a field to migrate options. Select Discipline area from the dropdown list, then click Select field.
- Change the OH&S option to Occupational health and safety.
- Select the Migrate button.
- Check your email inbox (the one associated with your Smartabase account) and wait for an email notification that your migration is complete.
Do not open and edit the event form prior to this or you risk data loss for that option.
- Once you have received the email notification, refresh the builder interface.
- Go to Smartabase Online (refresh the page if it was already open) and run a report to check that the records which previously had OH&S selected now have Occupational health and safety selected.
- Refresh the builder interface and open the form in the Event forms tool.
- Select the Sub-discipline area field and go to the Option properties. Change OH&S: to Occupational health and safety: to reflect the new option name.
This name does not need to be migrated because it is a conditional option field and it won’t have any records saved with OH&S:.
- There are no calculations in the Practicum placement details form which reference the OH&S option name specifically but if there were, you should update the equations as required and resave the form from the Event forms tool.
You can change the conditional options (i.e. options followed by a colon) within the Options properties because these are not directly selectable and therefore do not have data saved to them; however, do not change the option names themselves as this will result in data loss.
Rearrange existing options
As long as the option names are not changed, they can be rearranged without causing any data loss.
- Go to the Event forms tool in the builder interface and open the Practicum placement details form.
- Select the Dropdown field named Discipline area.
- In the Option properties, rearrange the options to appear in alphabetical order. Select Update to save your changes.
There are no scores assigned to these options but if there were, you would need to go to the Scoring properties and update the scores for the options. - Save the event form.
Archive obsolete options
Removing the Nutrition option from the list will ensure that it cannot be selected going forward, however any historical records with this option selected will return a blank value for the field as the data will be lost. Instead, we recommend archiving the option so that it is available in records created prior to a specific date and not available in records entered after this date.
- Go to the Event forms tool in the builder interface and open the Practicum placement details form.
- Add a Date calculation and name it Date of record. In the Calculation properties, configure the calculation to return the Event date of the record.
- Add an Option calculation and name it Discipline areas version.
- In the Option properties, enter Version 1 and Version 2 as option names.
- In the Calculation properties, enter the following equation:
if(Date of record < 1654646400, "Version 1", "Version 2")
Where the number refers to the epoch timestamp of the date that the option list will change. In this example, Jun 8 2022 at 12:00 am GMT+10 is when the change is occurring and it has an epoch timestamp of 1654646400. You can calculate the Unix epoch time using a website such as https://www.epochconverter.com/ - This field can be hidden using conditional visibility in the Visibility properties or hidden in the Advanced properties.
- Select the Discipline area field and select the Option properties.
- Shift the options down a line and add Version 1: as the first line.
- Next, add Version 2: to the bottom of the list and duplicate the list of discipline area options.
- Remove the Nutrition option from the list of options below Version 2:.
- Select the Update button to save your changes to the options.
- In the Advanced properties, set the Conditional option property to the Discipline area list field.
- Save the event form.
- Use the Resave option in the Event forms tool to run the calculations.
- Wait until you receive a confirmation email, then run a report on Smartabase Online to confirm that the records have been updated.
Following any field updates, anyone who is using the Smartabase Athlete app in offline mode or using the Smartabase Classic app should be advised to log out and log back into the app using online mode so that the updates can be synchronized to their device.
Outcome 3: Update other features that reference the option names
Option names may be specifically referred to in other areas of the Smartabase site. Therefore, it may be necessary to update settings in other areas of the site when updating or adding new options for a field. Some features that may require updates include the following:
- Performance standards: select an appropriate color for the new option and any other options without colors assigned.
- Performance alerts: remove any alerts that might have been created to alert people when a student logs work in the Nutrition discipline. If required, add an alert for anyone who needs to be notified of work in the Education discipline.
- Rulesets in dashboards: select an appropriate color for the new option.
- Pie/donut chart widgets which have custom colors set for each category: update the custom categories with the new option and a color, and remove the obsolete option as a category.
- Select box widgets with a custom default value: if required, update the custom options or the default value for the widget.
- Data filters on widgets where the filter uses a custom value based on the option name: if required, update the custom field within the filter.
For more information on how to edit these settings, refer to the help articles related to each tool.