Standard Form Data Converter

GT eForms 3.50 introduced a new Helium form engine. The engine used prior to 3.50 is referred to as Standard. In order to convert a configuration-only Form Type built with Standard to use the new Helium form engine, a Helium Performance checkbox on the General Tab of the Form Type Setup is checked. Checking the Helium Performance checkbox changes the way the form transaction data is stored. Standard Form Types store form data in XML and Helium Form Types store form data in JSON. After converting a Standard Form Type with existing form transactions to use Helium Performance, the Standard Form Data Converter should be used to convert those existing Standard (XML) form transactions to the Helium JSON format to make them accessible.

NOTE

Use of this tool ensures proper conversion of form data from Standard to Helium. Prior versions of GT eForms had data loss and usability issues as a result of improper conversion. This tool prevents those issues from occurring and streamlines the process of converting form transactions to Helium. See Helium Form Conversion Notice for details.

Clients who have no Standard Form Types or transactions have no need for this tool.

Using the Tool

Navigation: Manage GT eForms 3.x > GT Utilities > Standard Form Data Converter

Information to guide you in your use of the Standard Form Data Converter.

Important Considerations

There are a few things to be aware of before using this tool.

1. Security: Only users who have the GT eForms Technician role will be able to access this tool.

2. Special circumstances: Form Types with custom segment code that uses a JoinToForm method to save the custom segment data to the form data (XML) will require specialized work for conversion. Please contact support@gideontaylor.com for assistance if the Form Type has code that saves custom segment data to the form data XML or you encounter errors that indicate you have this scenario.

3. Reversion: Should it become necessary to revert the changes from this process, clients should also contact Support. The data converted by this tool is backed up, and we can assist with recovering the original version if a reversion is necessary.

4. Converting a single form: This tool can be used to convert a single form transaction but the Form Admin Tool has also been updated to support converting a single form transaction. See the Form Admin Tool documentation for more details about this feature.

Providing a Run Control ID

A Run Control ID is an identifier for the process you are going to run with your configuration. It helps in tracking and managing the execution of the process. Each Run Control ID is unique and ensures that the process runs with the specified parameters.

Select an existing Run Control ID, or click 'Add a New Value' to provide a new Run Control ID.

If 'Add a New Value' is clicked, type in a new Run Control ID

Selecting form transactions for conversion

Once in the tool, select a Form Type and possibly other criteria to identify the set of form transactions to convert.

IMPORTANT NOTE

Only Form Types with Helium Performance activated will be available because this process only works on Form Types that have already been converted to use Helium Performance.

There are three filter options to find form transactions to convert.

• Filter Option 1 converts all form transactions for the selected Form Type.
• Filter Option 2 converts a single form transaction for the selected Form Type.
• Filter Option 3 converts form transactions for the selected Form Type based on advanced criteria.

The 'View Form IDs to be Processed' section (shown expanded in Filter Option 3 of the image above) shows the set of form transactions that will be converted.

NOTE

You must select at least one Form Status before running the process with the Advanced Criteria option selected in the Find Transactions By dropdown.

Field/Button	Use
Run Control ID (Read-Only)	A read-only display of the provided Run Control ID from the previous step.
Process Monitor (link)	Opens the Process Monitor
Run (button)	Begins running the conversion process via the Process Scheduler based on selected criteria
Form Type	Search for the Form Type you want to convert form transactions for.
Find Transactions By:	Select form transactions to convert. Options Include: 1) All Transactions 2) Single Transaction 3) Advanced Criteria
Max Transactions to Convert:	An integer value that limits the number of transactions for the tool to convert. The tool will always automatically select the oldest transactions available based on selected criteria. For example, entering a 5 will convert the 5 oldest form IDs that match all other provided search criteria.
Form ID	Single Transaction option: Select the Form ID of the transaction to be converted
Form Statuses to Include (section)	Advanced Criteria option: This section includes a list of form statuses to filter the form transactions to convert. If this section is showing, one Form Status must be selected before running the process.
Original Date - Start & End Dates	Advanced Criteria option: In the Original Date section, provide a date range to filter the selection of Form IDs by Original Date. Values can be provided in either, both, or neither of these fields.
Last Updated Date - Start & End Dates	Advanced Criteria option: In the Last Updated Date section, provide a date range to filter the selection of Form IDs by Last Date. Values can be provided in either, both, or neither of these fields.
Include Comment (checkbox)	Check this box to add a comment to the form comment log regarding the form's conversion from Standard/XML to Helium/JSON. Uncheck this box to not add a form comment.
Comments	Shows if the Include Comment checkbox is checked. A default comment is provided from message catalog 24842, 280 but you can specify a custom comment here or in the message catalog entry as needed.
View Form IDs (button)	Located in the expandable 'View Form IDs to be Processed' section, this button populates a Log field with a list of form transactions that fit the specified criteria before running the conversion process. Note: This tool will only convert form transactions that are stored in the Standard (XML) format.

Conversion Process

This section provides guidance to convert Form Types from Standard to Helium.

Conversion in non-production environments

We recommend running through the conversion process in non-production environments before running through the process in Production. This will provide a rough idea of the time it will take to convert. An early less-optimized version of the conversion process took one client about 0.5 sec per form transaction. The time required to convert will vary based on the number of form transactions, the size and complexity of the Form Type, and the environment's infrastructure.

Conversion in production environments

Users can continue to submit and act on new form transactions while a batch of prior transactions are being converted.

Testing and verifying the conversion

We have performed extensive testing of the conversion process to ensure that it is reliable and effective. Here is a high-level test outline in case you want to spot-check a few forms before and after converting the form transactions.

1. Open a form transaction in the Form Admin Tool
   1. Verify that any action items or attachments are visible on the appropriate page.
   2. Verify the 'Helium Performance' field on the 'Form List' page shows the correct value (Standard: N, Helium: Y)
   3. Verify the 'Form Data' shows the data in the proper format (Standard: XML, Helium: JSON).
2. Review the form data through the Form UI
   1. Access the form transaction through the View task to ensure that the data appears correctly in the configured segments, attachments, action items, and highlight/versioning.

Query Records

Open the Query Records tab of Form Setup and run Check Structure and Verify Data Sync to ensure that all Query Record data is properly synchronized after the conversion.

Running a Query Record Data Sync will only synchronize data for form transactions matching the form engine selected in the Form Type Setup. This means that Helium Form Types will only have query record data generated for form transactions submitted after converting the Form Type to Helium or converted using this tool. Standard form transactions for a Helium Form Type will be ignored until they are properly converted, which may cause the data to appear 'Out of Sync.'

Existing query record data for Standard form transactions will be unaffected unless a configuration change necessitates rebuilding the Query Record structure. If this does occur, use this tool to convert the form transactions and rerun the Query Record data sync to load the query record data for those form transactions.