Layout Management Overview

In the past, customers with multiple variations of the same form needed to create completely new layouts for each variation, resulting in repetitive work. Once those layouts were created, there was no straightforward way to organize and find in the Layouts table. Then, when it was time to create a release, the versioning of each of these separate layouts could cause confusion about which versions should be included.

We created our Layout Management feature to address these concerns.

In particular:

• You can add variations to a Structured layout, eliminating the need to create a new layout and draw bounding boxes for forms that are very similar to ones you've already created layouts for.

• The system will group all variations of a Structured layout together as a single layout, making it easier to find and organize your layouts on the Layouts page.

• All fields created across a Structured layout's variations will be added to the layout's shared field list. When creating new variations, this list will be available to you in the Layout Editor.

• You can customize certain field settings, like Data Type and Supervision, for individual releases by creating field customizations.

• With the introduction of "working versions," you no longer need to create a draft for a Structured or Semi-structured layout you would like to edit. This change helps to streamline the layout-editing process and simplify versioning.

• We've introduced change-management features to help you understand who has made changes to your layout and how those changes affect layout variations and field customizations.

Content of a layout

Layouts can now have the following components.

Layout variations

Each layout now consists of at least one layout variation. If you have many forms for the same purpose that are very similar (e.g., HCFAs, tax forms) but would ordinarily require separate layouts, you can create a single Structured layout with multiple variations. After you create an initial layout with one of the forms, you can then add a variation for each instance of the form you want to process in Hyperscience. When creating a variation, all of the layout's fields and their metadata appear in the field list, and you have the option of copying bounding boxes from an existing variation.

For more information, see Adding a Variation to a Layout.

Shared field list

The shared field list for a Structured layout consists of all the fields that appear in at least one of the layout's variations. This list is available in the layout editor and can also be accessed from the layout details page. If you want to change a field's settings across a layout's variations, you can make those edits in the shared field list.

More information about the shared field list can be found in Editing a Structured Layout Variation.

Field customizations

If you want to change a field's settings for a specific release, you can create a field customization that captures those changes. You can then include that customization when creating the release, and your customization will be applied to all instances of that field in the release's layout variations.

To learn more, see Creating Field Customizations.

The diagram below shows the differences between Structured layouts in v28.2.0 and Structured layouts in previous versions.

Features by layout type

The features available in each type of layout are as follows:

Other changes in Layout Management

In addition to these changes to layouts, you’ll notice differences in other parts of the user experience after upgrading, as described below.  

Layout Library

In the Layout Library, Structured layouts that have at least one committed version will have a drop-down list of the variations included in the layout.

Clicking on a variation name opens a read-only instance of the Layout Editor, allowing you to view more information about the variation and its fields. To make changes to the variation, you need to click on the variation's name on the layout details pages.

Layout details page

Clicking on a layout's name in the Layout Library opens the layout details page for the layout.

We've reorganized the layout details page:

• The "General Information" section now appears in the right-hand sidebar.

• We've added Layout Variations and Version History tabs:

  • Clicking the Layout Variations tab takes you to the layout details page, which contains a list of the layout's variations.

  • The Version History tab has a list of all the committed versions of the layout and provides details about each one.

Each Structured layout has an additional tab called Fields and Customizations. This tab contains the layout's shared field list, along with any field customizations that have been created for the layout.

If there are open changes to a Structured or Semi-structured layout, a “Currently Editing” card will appear across all tabs on the layout details page, as described in the Change management section.

Versioning

We've replaced "drafts" with "working versions." There is always one working version for each layout that's ready for you to make changes to. You no longer need to create a new version of the layout if you want to edit the layout. Before you make changes to it, the "working version" matches the most recently committed version of the layout.

Versioning happens at the layout level. Even if a committed change affects only one layout variation, it will still be saved as a version of the layout.

You can restore previous versions of a layout. If you have changes to the working version that have not yet been committed, you will need to either commit those changes or discard them before you can restore a previous version. When you restore a previous version, the working version will match the state of the restored version at the time it was committed.

To learn more about layout versions, see What is a Layout Version?, Editing and Finalizing a Layout Version, and Archiving and Restoring Layouts.

Change management

"Committing changes" has replaced "locking" as the way to finalize changes to a version and make it available for use in a release. The "Currently Editing” card gives details about the changes to the working version that haven't been committed yet. You can see who else has made changes to the working version, the number of affected layout variations, the number of affected field customizations, and when the last change was made. You also have the option of committing the changes or discarding the changes.

If you commit the changes, the working version will become the latest committed version and a new working version will be created automatically. Before committing your changes, you'll be asked to name the version and add any comments about it. You will also be shown which variations will be affected when you commit your changes.

If you discard your changes, the working version will revert to match the latest committed version. If you have not yet committed any changes to the layout variation, you will not have a committed version to revert back to, and you will not be able to discard your changes.

Any changes you make to a layout that's been included in a release will not affect the content of the release.

You can also commit changes while in the Layout Editor by clicking Commit Changes in the upper-right corner of the page.

Retrieving exported layouts

Layout exports are now asynchronous. When you export a release, you will receive a notification when your file is ready. To download the file, click Notifications then click the Download link for the release.

All exported layouts will be in a ZIP file, even if a layout has only one variation. To learn more about how exported layout files have changed, see Exporting and Importing Layout Versions.

Creating releases

Releases consist of committed versions of layouts. When creating releases, you can choose to include all variations of a layout, or you can select individual layout variations within that layout. If you've created field customizations for a layout, you can apply one of them to the release.

For more information, see Adding a New Release.

Your layouts after upgrading to v28.2.0 or later

After upgrading to v28.2.0 or later from a previous version, each of your layouts will be converted to a layout with a single layout variation. The system does not do any merging of similar layouts or layout variations, and there are no tools in the application to do so.

To make the merging of layouts possible, we’ve created a script that allows you to group individual layout variations into a single Structured layout. To use it:

1. Download the script that is located at the bottom of this article.

2. Place the script file at forms/form_extraction/management/commands/merge_layouts.py. The file’s directory should be under /var/www/ in your instance’s application directory.

3. To run the script with manage.py, use Docker commands or SSH onto the instance.

The merging process works as follows:

1. You specify the UUIDs of the layouts you want to merge.

   • The first UUID in the list is the UUID of the target layout. The layouts listed after it will become variations of the target layout.

   • Fields that are the same across the layout variations will be merged in the shared list of the target layout, but the bounding boxes from each variation will be retained.

   • If field dictionary IDs are the same, the fields will be merged.

   • If there are no field dictionary ID matches, the field attributes will be compared. The field attributes are:

     • name

     • data_type_id  

     • output_name

     • supervision

     • required

     • routing

You can choose which field attributes will be compared and which will be ignored by the script. field_dictionary_id cannot be ignored, and field dictionary IDs will always be compared before field attributes. If there is no field_dictionary_id match, then the field attributes you’ve chosen will be compared.

An example command is shown below:

formuser@testing-nikim01:/var/www$ /var/www/venv/bin/python 
/var/www/forms/forms/manage.py merge_layouts 
7ec84b32-3138-4221-976b-26122e892f38 
ea6b642c-1d98-44b4-b4eb-fdb303ea434e --ignore_fields supervision

In this example:

• The layout with UUID 7ec84b32-3138-4221-976b-26122e892f38 is the target layout.

• The layout with UUID ea6b642c-1d98-44b4-b4eb-fdb303ea434e will become a variation of the target layout. For each field in this layout:

  • Note that the supervision value will be ignored during the merging process (--ignore_fields supervision), but all the other field attributes available for comparison will be considered.

  • If the field_dictionary_id of the field matches the field_dictionary_id of a field in the target layout, those two fields will be merged.

  • If the field_dictionary_id of the field does not match the field_dictionary_id of any field in the target layout, the script will find the field’s name, data_type_id, output_name, required, and routing values. If all of these values match those of a field in the target layout, those two fields will be merged.

We recommend downloading all of your layouts before running the merging script, as there is no option to undo your changes. You can always upload your layouts and merge them until you get the desired merged layouts.

Here are a few example scenarios, with matching field attributes bolded and non-matching attributes shown underlined:

Example 1

• You’re merging two layouts.

• There is no field_dictionary_id match for one of the fields.

• You are comparing by name, data_type_id, and routing (specified in the script as --ignore_fields output_name, supervision, required).

Example 2

• You’re merging two layouts.

• There is no field_dictionary_id match for one of the fields.

• You are comparing by name, data_type_id, supervision, and routing (specified in the script as --ignore_fields output_name, required).

If you are merging two fields that have different attributes, the merged field will take the values of those attributes randomly from one of the merged layouts.