Custom Forms

Custom Forms are intended for customizations that go beyond the out-of-the-box usage. They extend the app's functionality, are highly flexible as they can be reused in various modules and are not affected by version upgrades. It also gives an option to Pricefx partners to build connected applications.

For example, you may want to calculate the CO2 emissions when creating Quotes. You can create an embedded custom object that can do that inside the Quoting module. 

Custom Form can be defined as a standalone object or can be embedded in a parent object (Quote, Agreement/Promotion, Rebate Agreement, Deal Plan, Compensation Plan, Action, a standalone Custom Object).

Each Custom Form can be considered a micro-app and typically has:

  • Configurable inputs and outputs.

  • Visualizations of outputs (charts, etc.).

  • Persistence. Unlike in a Dashboard, the inputs and calculation results are persisted.

  • Approval workflow (standalone Custom Forms only).

You can also watch a video introducing Custom Forms and their usage.

Create Custom Form Types

  1. Go to Administration > Custom Form Types and click New Form Type.

  2. In the dialog, fill in the following fields:

    • Name – Name of the Custom Form Type (required). The name cannot be changed later.

    • Label – Optional label of the Form Type.

    • Add translations for the label in singular and plural forms. The singular is used for button labels like Create New or Save. The plural is used in menu items, label/title of the list page and in breadcrumb navigation. You must enter at least the singular for the default locale (the one with null value in the Locale column).

    • Header Logic – Custom Form header logic that defines the inputs, calculations or a custom header. For embedded Custom Forms, it also defines the interaction with the parent object.

    • Workflow Logic – For standalone Custom Forms, select a workflow logic defining the approval process.

    • Embedded – Determine if the Custom Form will be standalone or embedded in a module.

    • Form type – For embedded Custom Forms, select the Form Types that will support this Custom Form. You can select multiple options.

    • Configuration – For standalone Custom Forms, add a JSON definition describing the content of the Custom Form – its steps and tabs. The editor will allow you to save a configuration containing only supported tabs. See the Knowledge Base article Detail Page Layout and Dynamic Tabs for details.

    • Module – For standalone Custom Forms, select a module in whose main menu you want to have this Custom Form available.

    • Module Category – Enables you to group different Form Types into one category, represented by a menu item, list page, etc.

    • User Group (View Details), User Group (Edit) – Optionally select groups for which this Custom Form Type will be visible/editable.

  3. Click Add to save it.

Create Standalone Custom Form

To create a new standalone Custom Form, follow these steps:

  1. First you have to locate the Custom Form Type on which you want to base your new Custom Form. You will always find it in the Module menu but the exact module under which it is listed is determined by the creator of the Custom Form Type.

  2. Once located, select the desired Custom Form Type from the menu.

  3. Click Create New [Custom Form Type Name] in the upper right-hand corner.

  4. In the dialog, fill in the following fields:

    • Label – The custom label for easy identification of the Custom Form.
      A unique name of the Custom Form is generated automatically.

    • User Group (View Details), User Group (Edit) – Optionally select groups for which this Custom Form will be visible/editable.

  5. Click Add.
    After the new Custom Form is created, its detail page is displayed.

Create Embedded Custom Form

Embedded Custom Forms are added as a tab to Quotes, Agreements/Promotions, Rebate Agreements, Deal Plans, Compensation Plans, Actions or can be embedded in a standalone Custom Form. The tab is configured in Quote Types, Agreement & Promotion Types, Rebate Agreement Types, Plan Types, Compensation Types or Action Types, in the JSON configuration.

The following example shows a part of the JSON configuration that adds an embedded Custom Form as a tab:

... "customObjectTest": { "icon": "custom-post-type", "name": "customObjectTest", "type": "customForms", "typeReference": "CFO_Embedded", "translationKey": "Custom object" }, ...

where

  • type indicates that the content of this tab will be supplied by a Custom Object Type

  • typeReference is the unique name of the Custom Object Type

Calculating Embedded Custom Forms

If your want your embedded Custom Form to be calculated at the moment when the parent object is created (because it has inputs or outputs that are rendered by the calculation logic), you need to pay attention to two things:

  • The calculation of an embedded Custom Form must be triggered by the parent object’s logic. Run the customFormApi.withId().recalculation().doRecalculate() method to do that.

  • The Create Option settings (Do nothing or Save and calculate immediately). Calculation of embedded Custom Forms depend on the settings of parent objects. If the parent object is a Quote, go to Configuration > Quoting General Settings and for the Create Quote Option select Save and Calculate new Quote immediately to recalculate the embedded Custom Form when creating a Quote. Settings for Rebate Agreements and Agreements & Promotions can be done on their respective Configuration pages.
    If your Custom Form is embedded in another Custom Form, go to Configuration > Custom Forms General Settings and for the Create Custom Form Option select Save and Calculate pre-phase for new Custom Form immediately.
    If you select the Do nothing option, you’ll get the NullPointerException error because the server doesn’t know the ID of the embedded Custom Form at that time when the prePhase of the header logic is run.

Custom Forms List (Standalone)

The location of the Custom Form list page depends on the admin who selected a module or module category under which the list page will be available. You can check this at Administration > Custom Form Type in the Module / Module Category column.

When you open a Custom Form list page, a table displays showing the list of all standalone Custom Forms based on that Custom Form Type that you are entitled to see.

Click on the Name or Label to display the Custom Form's details.

You can customize the structure and content of the Custom Forms table to suite your needs. You can:

  • Sort the table

  • Use a simple filter

  • Add/remove fields (columns)

  • Create advanced filters

  • Save your customized layout and filters as a preference

  • Add extra attributes (up to 30)

See the Common Table Actions section for details.

When you select a Custom Form, the following actions are available:

  • Create

  • Duplicate

  • Edit

  • Delete

  • Create new revision (Custom Forms in Approved status)

  • Submit / Withdraw / Revoke

Note: When you select multiple items and, for example, submit them, Custom Forms are processed synchronously, meaning each object is processed one after the other. This process differs from mass actions, as it doesn't initiate a background job.

Custom Form Detail (Standalone)

When you open a Custom Form, you can see that the content is organized into several tabs, just like a Quote, Rebate Agreement or other document.

The content of the Custom Form depends on what has been configured by the admin, however the inputs and calculation results are always on the Details tab. This tab can also have a header with graphical representation of data (with or without user inputs). Calculation results are displayed on a side panel which is collapsed when there are no results.

Depending on the configuration, there can be many more tabs (supported tab types are: Notes, Documents, Dashboard, Actions, Attachments, Embedded Custom Form, Configuration Wizard, Workflow, Workflow History), including dynamic tabs.

Field edits are saved automatically, you can update the calculation results anytime by clicking the Recalculate button.

The following action buttons are available in every Custom Form: Duplicate, Submit, Create New Revision, Revoke, Withdraw (depending on workflow status).

Approval workflow is supported for standalone Custom Forms – you can send your Custom Form for approval when it is ready. The current document and workflow status is displayed next to the Custom Form name.

Found an issue in documentation? Write to us.

 
Pricefx version 13.1