Creating Intake Form Versions

Intake Form Versioning Overview

Note: Effective-dated versions of intake forms are supported for Permits, Planning and Zoning, and Business Licenses.

Over the life cycle of an intake form, there are changes to business processes that may require you to create a new version of an intake form layout. For example, assume that a new mandate requires all commercial building permits to include information that tracks compliance with environmental regulations beginning at the start of a new year. In this case, you can create a new version of the form layout containing fields to capture the environmental compliance that becomes active on January 1 just as the new mandate becomes active. All new commercial building applications submitted on or after January 1, will use the new form layout version, while all applications submitted prior to January 1 will continue to use the previous version of the form.

With the versioning feature, you can keep previous versions of forms for historical reasons, have the current form live in production, and have future versions of the form ready to roll out on the specified effective date.

Only the layout of the form changes when creating a new version. The data from the transaction type entered on the Permit Type page, for example, is not included in the effective-dated version. While the layout of the form can change from version to version, the back-end custom object associated with the layout versions contains a superset of all the fields and elements used in all the versions of the form layout. For example, if a field is removed in version 3 of a form layout, that field still exists in the custom object for form layouts still using version 1 and 2. The custom object for an intake form is the database entity storing data as well as the REST endpoint for the intake form.

Because the custom object remains the same for all layout versions, no changes to reporting need to be made other than including any newly added fields to your report definitions. Likewise, if you have developed integrations for the custom object, the REST endpoint for an intake form remains the same for all versions. This is different to cloning an intake form, where you'd need to create new reports and integrations because the name of the underlying custom object changes.

For more information on cloning intake forms, see Cloning Transaction Type Definitions.

Creating a New Intake Form Version

When you create a new intake form, initially the default first version of a form is V1, with an open-ended effective date. If you want to make changes to these defaults, you need to make those prior to publishing the form for the first time. When you want to create the second version of a form, open the current version of the form and create the new version prior to making any changes to the existing form.

To create a new version of a form layout:

Open the existing intake form design, and before making any changes to it, select Manage Design > Manage Version.
On the Layout Version dialog box, click Show All Versions.
On the Layout Version page, click Add.
On the Layout Version dialog box, select a date for Effective Start Date.

The Effective End Date is always open-ended for a new version. If you create another version in the future, the end date for previous version becomes the start date of the new version minus one day. For example, if the start date for version 3 is January 1, 2023, then the end date for version 2 becomes December 31, 2022.

Note: You can't update the effective end date. It is always updated automatically.

Note: You can't create a layout version between the date range of two currently published versions.
For Layout Version, enter a value, such as V2, V3, and so on, according to your agency version naming conventions.

The default value is V1. The value can also be more free-form, such as Jan 2023 for proposition 5.

The value you enter must be unique from all other versions created for the current record type.
In the Description field, describe the changes made to the form for reference.
Click Save.

Note: The effective start date will be locked once you save.
Click Select Version to load the new version in the designer workspace.

Note: Only one draft version of an intake form can be open at a time in the Intake Form Designer workspace.

Understanding the Version Indicator

You can confirm the new version is loaded by viewing the version indicator text in the header of the form layout.

Form Layout Indicator

By default, the first version of a form layout is Version: V1 <current date> to 4712-12-31. Where 4712-12-31 is a random value far out into the future to indicate "open end date." The newest layout version always has an open ended effective date.

Managing Intake Form Versions

To manage intake form versions:

Open the existing intake form design, and before making any changes to it, select Manage Design > Manage Version.
On the Layout Version dialog box, click Show All Versions.
Use the Layout Version dialog box to view and manage your intake form versions.

Page Element	Description
Add	Click to add a new layout version.
Correction Mode	Displays only when signed in using a system administrator ID (PSC System Administrator Job Role). Enables you perform advanced administrative tasks when required, such as to delete expired layout versions if needed.
Effective Start Date	The date when this version of the intake form layout becomes active. If the form is published, the version becomes active just after midnight on the selected date.
Effective End Date	A read-only field displaying Open end date for all new intake form versions. The end date is automatically populated for a previous version once a new version has been created. The end date for a previous version becomes the start date of the new version minus one day. For example, if the start date for version 3 is January 1, 2023, then the end date for version 2 becomes December 31, 2022.
Layout Version	Displays the version entered when the layout version was created. Determine a naming scheme for your versions to create consistency. It can be V1, V2, and so on, or more free-form, such as Jan 2023 for proposition 5 mandate.
Description	Add the details regarding what was modified in each version for your agency’s reference.
Published State	Indicates the state of the layout version, which determines whether a form layout can be migrated to another pod, such as from the test pod to the production pod. N: The specific version was never published and will not be migrated. Note: You can't create a new version if the previous version hasn't been published. Y: The specific version is published and will be migrated. D: The specific version was published previously but it is now in Draft status with new changes. This version can be migrated because there is a published version of the form. Only the published version gets migrated.
Delete	You can delete versions that have not yet reached their effective end date. You can't delete versions that have already become inactive (expired) unless you have enabled correction mode. A version becomes expired when its effective date window is in the past. Note: In the event that you need to delete a version that has expired, enable the Correction Mode switch.
View More Details	Click to drill into the version and display the details for that version.

Understanding Which Layout Version Opens in the Designer Workspace

When you click Design Form on the record type page to open the form layout, a number of factors determine which layout version opens in the designer workspace.

Note: Always make sure you have opened the correct version of the layout that you want to view or modify before making changes.

If there is one or more draft version that has been published at least once, the version with the earliest effective start date opens.
If there is no draft version that has been published at least once, but there is one or more never-published versions open, the never-published version with the earliest effective start date.
When there are only published versions, the version that is currently effective opens.

Runtime Assignment of Layout Versions

The display and assignment of the layout version is automatic, and applicants aren't aware of the version they are interacting with, nor do they need to be aware of the version. Use the information in the following table to understand how layout versions are displayed and assigned at runtime.

Runtime Action	Layout Version Behavior
An applicant accesses an intake form to begin an application.	The most current effective layout version is displayed.
An applicant returns to a previously saved intake form.	The most current effective layout version is displayed, regardless of the layout version used initially, prior to the save.
An applicant submits the intake form.	The submitted intake form is stamped with the most current effective layout version at the time of submittal. All future access, updates, and workflows use the form layout version effective when the application was submitted.

Layout Version General Considerations

Typical reasons for creating a new version of a form layout include:

Adding or removing fields.
Configuring control display.
Making fields hidden from the public.
Setting existing fields to be required.

Other form element changes may not be incorporated into a specific version as they may not support the concept of effective dates. These cases may require additional consideration or modification to be fully unique with separate versions. Use the information in the table below to help your agency determine your layout version efforts.

Consideration	Description
Groovy	Groovy business logic applies to all layout versions unless you modify your code to incorporate built-in functions that enable you to specify specific versions, such as getLayoutVersion(). For more information on working with layout versions and Groovy, see "Running Groovy Depending on Layout Version" in Adding Logic.
Labels	Changing a label is applicable to all versions. If you change a label in a future layout version, it affects all previous versions once you publish that version.
Fees	Ensuring fee calculations remain consistent amongst multiple form layout versions requires additional considerations and modification. Review the section below titled "Layout Versions and Fee Schedule Considerations."
Record types	Only the form layout is versioned. Record type data, such as the permit type data or the planning and zoning application type data, are not included in a new version. Changes to the record type apply to all versions of the form layout, not to a specific version.
Workflow	Ensuring workflow remains consistent amongst multiple form layout versions requires additional considerations and modification. Review the section below titled "Layout Versions and Workflow Considerations."
Revert to Last Published	Applies only to the currently open layout version in draft mode.
Text Area and Help	Field types like text area and help use the built-in Rich Text Editor feature. The data contained in help and text area fields is not stored within the form layout so it is not included in the layout version. If you want to update help or text area content and you don't want the change to affect all form layout versions, remove the previous field and create a new field for the new form layout version.
Lookups	If you change the reference to the lookup associated a list of values field, that change affects all versions of the form. Note: Lookup values have effective start and end dates, which you can use to coincide with the effective dates of a layout version.
Decimal Places	Changes to the Decimal Places attribute for a number field apply to all versions. Note: To avoid loss of data, never decrease the decimal places for a number field on an active form in production.
Cloning	When cloning a record type and you've selected Clone Form Design when cloning a record type, only the most current effective layout version is cloned along with the record type. The version defaults to V1 with the same effective date as the cloned layout version, with an open-ended effective end date. You can't modify the effective start date of the cloned layout version. If you need to set a new effective start date, you can immediately create a new version of the cloned intake form and set the date as desired.

Layout Version Business License Considerations

In general, the versioning feature works the same for a business license form layout as it does for a permit or planning and zoning application. However, with business licenses you need to take into account the various filters being applied to the form elements, such as origination, amendment, and renewal filters.

When you establish a business license, you are storing the information entered through the origination filter. When you then initiate a renewal or amendment of the existing business license, the origination information is copied into the layout for that renewal or amendment. Origination, renewals, and amendments can all have slightly different form elements displayed because each filter may need to capture different information. On top of the filters, consider that between filling out an origination intake form and a renewal or amendment, there can be a new version of the form displaying new changes to the applicant.

For example, let's look at a few scenarios to help illustrate.

Scenario	Description
Applicant fills out an origination on V1 of a license type	Applicant views V1, enters all V1 origination information and submits.
Applicant fills out an origination on V1 of a license type as a new V2 becomes effective	If the applicant has already submitted the V1 version of the form, the information submitted remains V1. If the applicant has only saved the V1 version of the form, the next time they open the form, it will display the V2 version with the new changes active.
Applicant has submitted a V1 version of a license type, a new V2 version is now effective, and the applicant wants to either amend or renew the license.	Information from the origination is copied into the renewal or amendment application. V2 is active displaying all new or changed elements as required for either the renewal or amendment filter, while not displaying any elements that were removed, set to be hidden from pubic view, and so on. With fields set to be confidential, they will now be visible only to the applicant and agency users with the required security access.

Layout Version and Fee Schedule Considerations

Because fee schedules are also effective dated, you can coordinate changes to layout versions and fee models by aligning the effective dates. For example, assume you need to roll out a new version of form layout with fee increases beginning the first day of a new year.

In this case, you would:

Create a new effective fee schedule, with the same effective start date as the new form layout version.
Update the fee mappings page for the intake form to reference effective start date for that new fee schedule (and include any new field mappings, as needed).
Migrate your updated data using Functional Setup Manager and Configuration Set Migration from test to production pod prior to January 1.
On Jan 1, the new form rolls out live, referencing the updated fee schedule, which is also now live, because of the effective dates.

For more information on mapping intake form fields to fee decisions models, see Mapping Form Fields to Decision Model Attributes.

For more information on setting up fee schedules, see Setting Up Fee Schedules.

For more information on decision models, see Creating Decision Models for Fees.

Layout Version and Workflow Considerations

While workflow process definitions don't utilize effective dates, you can created incremental versions and coordinate the roll out of layout versions with updated workflow processes.

For example, assume that there is a new municipal ordinance requiring environmental impact inspections for all commercial building permits starting on January 1 of the new year. This new mandate requires you to add fields to the intake form to capture information related to the environmental impact as well as add a new human task to the underlying workflow process definition.

In this scenario, you would:

Create a new layout version of the intake form to include the new fields.
Create a new version of the associated workflow process definition to include the new human task.
Specify the new version of the workflow process definition from the Version drop-down list, in the Workflow Setup section of the Permit Type page.
Migrate your updated data using Functional Setup Manager and Configuration Set Migration from test to production pod on January 1.
On January 1, the new form rolls out live, referencing the updated workflow process, which is also now the effective workflow process for any intake forms submitted on or after January 1.

For more information on setting up workflow for a record type, see Workflow Basics.

Layout Version Test to Production (T2P) Migration Considerations

T2P Migration refers to migrating data from a testing or development pod to a production pod using Functional Setup Manager and Configuration Set Migration.

Note: The published state of the form, as displayed in the Published State column of the History Data grid on the Layout Versions dialog box indicates if a layout version will be migrated. Only published versions of the intake form are migrated from one environment to another using Functional Setup Manager and Configuration Set Migration.

For more information on migrating data using Functional Setup Manager and Configuration Set Migration, see Managing Transaction Type Configurations.

For more information on migrating data using the Intake Form Designer Export/Import feature, see Exporting and Importing Intake Forms.

Configuration Set Migration overwrites data on the target if the source and target share definitions. This is the main reason it is recommended to make changes only in source environments, such as the development environment, and to carry those changes through to the test environment (if present) and the production environment.

If the layout is already present in the target and the migration process is trying to add a new effective-dated row where the start date is less than the current date, you will see a message similar to the following in the migration logs, indicating there is a collision between objects shared between the source and the target environments.

JBO-Can’t create a current effective dated row: [LNP, LNP1PERMIT_c],in update mode, start date: 2022-05-05:….

This can occur in a number of situations, including the scenarios described in the following table.

T2P Scenario	Description
Grids	This is true for custom parent objects and child objects, such as grids. If the objects exist on both the source and the target environments, the two custom object names may appear the same, but they point to different physical tables (objects). When you try to run Configuration Set Migration it will fail to move the grids in this case. Until this issue is resolved, all migration will be blocked.
Expired Versions	The T2P migration will fail for an intake form layout version that: Is expired on the source environment (development or test). Has never been migrated to the source environment. An expired intake form means its effective date window is in the past. For example, assume you have these three layout versions on your test environment, and you are migrating to production on December 31, 2022. V1 <Jan 01 2021- Dec 31 2021> (Migrated) VTest <Oct 01 2021- Oct 31 2021> (Not Migrated) V2 <Jan 01 2022- Dec 31 2022> (Migrating) In this case, the migration will fail due to the VTest version. To resolve: Sign in using a system administrator ID (has the PSC System Administrator job role assigned). Open the intake form listed in the migration logs. Select Manage Design >Manage Version. Click Show All Versions. Turn on the Correction Mode switch. Delete the expired intake form layout version with the effective date window in the past as mentioned in the migration logs.

T2P Scenario

Description

Grids

This is true for custom parent objects and child objects, such as grids. If the objects exist on both the source and the target environments, the two custom object names may appear the same, but they point to different physical tables (objects). When you try to run Configuration Set Migration it will fail to move the grids in this case. Until this issue is resolved, all migration will be blocked.

Expired Versions

The T2P migration will fail for an intake form layout version that:

Is expired on the source environment (development or test).
Has never been migrated to the source environment.

An expired intake form means its effective date window is in the past.

For example, assume you have these three layout versions on your test environment, and you are migrating to production on December 31, 2022.

V1 <Jan 01 2021- Dec 31 2021> (Migrated)
VTest <Oct 01 2021- Oct 31 2021> (Not Migrated)
V2 <Jan 01 2022- Dec 31 2022> (Migrating)

In this case, the migration will fail due to the VTest version.

To resolve:

Sign in using a system administrator ID (has the PSC System Administrator job role assigned).
Open the intake form listed in the migration logs.
Select Manage Design >Manage Version.
Click Show All Versions.
Turn on the Correction Mode switch.
Delete the expired intake form layout version with the effective date window in the past as mentioned in the migration logs.

Layout Version Export/Import Considerations

The following scenarios illustrate the behavior of the Intake Form Designer export/import feature with regard to layout versions.

For more information on exporting and importing forms, see Exporting and Importing Intake Forms.

Source Environment	Target Environment	Export/Import Behavior
Multiple versions exist.	Intake form not present.	The currently effective layout version will be exported even if it's not published. So the version imported on the target will need to be published.
Latest version exported, but changes are ongoing.	Latest version imported prior to ongoing changes.	Changes to the same version, if no additional versions are made, then target layout version is overwritten by subsequent export/imports.
Initial version exported. New version created and exported.	Initial version imported. New version also created on target environment, prior to import.	Import of the layout on the target environment will fail. Importing layout versions does not support multiple versions on the target environment of the same form being imported. Note: All changes should be completed on the source environment, such as the development or test environment.
Export a record type where fee schedules are created for each layout version, with the fee schedule effective dates and mappings matching the layout version effective dates exactly.	Import.	Effective layout version with matching effective fee schedule and mappings will be exported and imported.