Forms 2.0

available from version 17.0

Introduced in version 17.0, Forms 2.0 is a unified input framework that replaces legacy static inputs and configurators with a single, flexible API for building forms anywhere in the application that uses inputs. Instead of duplicating logic in multiple places and switching between different input APIs, configuration engineers define one Form logic and attach it to the objects that need inputs.

The key design goals are:

• Single way of configuring inputs instead of separate static inputs and configurators.

• Better performance (smaller documents, fewer recalculations, lazy loading of value options).

• Cleaner, more maintainable Groovy code without “syntax check” / input-generation mode.

• Future-proof architecture that enables a UI form designer and richer layouts.

How Forms 2.0 Work

At the core of Forms 2.0 is a Groovy logic of type Form:

• The logic is defined in Logics > Calculation Logic > Form Logic and then assigned to an object’s calculation logic (e.g., Quotes header logic).

• When the logic runs, it injects a Groovy helper variable called form, which exposes a fluent API to:

  • Create inputs (user entries, options, matrices, etc.).

  • Update and remove existing inputs.

  • Control layout (rows, containers, modals).

  • React to user actions (validate, show messages, reload options).

The dynamic behavior of a form is executed on the client side (browser) as JavaScript, but configuration engineers never write JavaScript directly. Instead, they implement form events in Groovy; the backend then returns JSON instructions that Unity translates into JavaScript behavior.

Where You Can Use Forms

A single form logic can be assigned to multiple object types, wherever you need inputs. Typical assignments include:

• Price List line item

• Live Price Grid line item

• Quote header / Quote line item

• Agreement & Promotion header / Agreement & Promotion line item

• Rebate Agreement header / Rebate Agreement line item

• Compensation Plan header / Compensation Plan line item

• Dashboard

• Model Class (by selecting type Form)

• Custom Form header

• Other objects that support inputs

Some object types can even use two separate form logics, one for header-level inputs and one for line-item–level inputs.

This allows you to reuse the same form across multiple configurations and keep the UI layer decoupled from pricing/business logic.

Form Lifecycle and Phases

Form logic runs in three phases, controlled by the element’s calculation context. These correspond to the life cycle of a form instance:

1. Init

   • Purpose: Define the initial set of inputs for the object.

   • Called when:

     • A new object is created (e.g., new quote, new agreement).

     • A new line item is added.

     • A dashboard using the form is opened.

   • Behavior:

     • Replaces the old “input generation” / “syntax check” mode.

     • Should avoid (or strictly minimize) database queries to keep initial rendering fast.

     • Does not set value options for OPTION / OPTIONS inputs; these are loaded lazily.

2. ValueOptions

   • Purpose: Provide value options for OPTION and OPTIONS inputs.

   • Called by Unity asynchronously after the form is rendered, only when an input needs options.

   • Behavior:

     • Returns either:

       • A map of value → label, or

       • A list of values (if labels are not needed).

     • Options are not persisted on the object, which reduces object size.

     • Can provide labels localized to the end user’s language.

3. Action

   • Purpose: React to frontend events such as “onChange” or “onClick”.

   • Called whenever a user changes the value of an input that has dynamic behavior configured.

   • Examples of what you can do in this phase:

     • Reload value options for another input.

     • Add or remove inputs dynamically.

     • Change labels, default values, required flags, etc.

     • Show errors, warnings, or success messages to the user.

Together, these three phases allow you to build highly dynamic forms while only recalculating the parts that actually need to change, instead of re-running a full configurator.

Benefits Compared to Static Inputs and Configurators

Forms 2.0 addresses several long-standing limitations of the previous input approaches:

• Unified API

  • One consistent Groovy API buildFormInput() for all inputs instead of:

    • getInput() (static inputs),

    • addToConfiguratorEntry() (configurators),

    • addOrUpdateOutput() (header inputs).

• Performance and UX

  • Initial form is rendered fast using the Init phase.

  • OPTION / OPTIONS values are loaded lazily, on demand.

  • Value options are not stored with the object → smaller quotes, agreements, etc.

  • More advanced layouts (multi-column, collapsible sections, modal popups).

  • Only the affected part of the form is reloaded on changes.

• Cleaner logic structure

  • No special “syntax check” mode; form behavior is localized in a dedicated form logic.

  • Flatter, more readable Groovy without deeply nested configurator structures.

  • Easier to maintain, debug, and test.

• Future extensibility

  • Form definition is structured and layout-aware, which opens the door for a visual form designer.

Migration and Deprecations

Forms 2.0 is designed as the successor of configurators:

• Configurator-based inputs will not be supported for new Forms 2.0 usage.

• New implementations should use Forms as the standard way to define inputs and dynamic behavior.

• Over time, existing configurator-based solutions can be migrated to Forms to:

  • Simplify configuration.

  • Improve performance.

  • Avoid configurator-specific limitations and bugs.

When planning new projects or refactoring existing ones, consider Forms 2.0 as the default input mechanism.