Skip to main content
Version: 🚧 Next

Form definitions

Business goal​

A form definition, also referred to as a questionnaire, bundles questions to get answers from counterparties. In the application, forms are used in two ways:

  • in an information exchange flow: to gather information from an external counterparty.
  • as a dossier questionnaire: to gather information from an internal counterparty.

🎯 Functional documentation​

For a generic information exchange, one form can be configured on the level of the dossier definition. An information exchange is driven by a flow definition where several flow steps are configured. Each flow step that relates to questions corresponds to one or more sections from the form definition (using the SUBSEGMENT).

A form consists of sections, and each section contains questions. Each question can have a different representation for its answer, such as boolean (yes/no), text, numeric, single- or multi-selection, or a country. A question can be displayed based on a condition related to the answer of a previous question. Similarly, an entire section can be hidden or displayed based on a condition on a previous question's answer or based on customer-specific logic using a ConditionalSectionClass.

Harmoney also supports MIFID questionnaires with dedicated flow steps and SUBSEGMENTS:

  • GOALS
  • FINANCIAL_SITUATION
  • KNOWLEDGE

The following elements are available for these types of forms:

  • Profilers: These are business logic units that analyze a form's answers to create a profile, such as Conservative, Balanced, or Dynamic.

⚙️ Configuration​

Creating a Form Definition​

To create a new form definition, provide the following required fields:

  • Identifier: Unique lowercase string using only letters and underscores (e.g., client_onboarding). Must match the pattern ^[a-z_]+$.
  • Default Language: Primary language for form content.
  • Title: Name displayed in the default language (e.g., "Client Onboarding Form").

💡 Note: The identifier must follow the pattern ^[a-z_]+$ and cannot contain spaces or uppercase letters.

Form sections​

Form definitions are structured into sections, each containing questions.

Sections are linked to specific flow steps in a flow definition via the subsegment field. The subsegment field can be configured on the section and in the settings of any *_QUESTIONS flow step.

Internal questionnaires are completed by FSP users. Use the subsegment AML_DEFAULT on the sections of the form definition and configure the form definition on the FSP definition.

Section settings​

General

  • identifier: needs to be unique.
  • subsegment: the flow step you want the section to appear in.
  • sorting: the flow definition sorting mainly defines the order of the flow. The sorting here can only impact sorting within the same subsegment.
  • title: the title of the section.
  • description: a description displayed for this section. By default, the description is added in the pdf, unless the pdfDescription is filled in.
  • title info-box: the displayed title of the info-box which is by default collapsed.
  • description additional info-box: the text available once the info box is expanded.
  • PDF description: a text available in the PDF.
  • conditional class: allows defining the visibility dependency this section should comply to.

Conditions

  • define the section visibility dependency based on a question in the form.

Section questions​

You can create new questions or import existing questions.

Create questions​

  • identifier: needs to be unique.
  • question text: the label you need for the question.
  • answer type: the type of answer you want provided, eg. autocomplete, boolean, text area,...
  • test type: applies only for MIFID.
  • mandatory question: flag whether the question needs to be answered or not.

Import questions​

When importing questions, the toggle copy question should be enabled if you don't want to copy the answer. Say this question has been answered by the counterparty before, if you don't copy the question, the answer that was once provided will also be copied.

Editing questions​

Questions can be edited on Question level. Within the form definition, you can define sorting of questions, parent questions and conditional visibility of questions.

Nested questions​

Questions can be nested below other questions. Questions can also be nested below choices of a question (only for answer types SINGLESELECT and MULTIPLESELECT).

Conditional questions​

Questions can be conditionally displayed based on the answer to another question. This can be configured via the admin UI. In the form editor, edit a question and click on the tab Conditions. Here you can select a question and define the value or choice identifier that must be entered or selected for the question to be displayed.

warning

Conditions can only be applied to questions of the same section.

Conditional Sections​

Sections can be conditionally displayed via a dependency on another question. This can be easily configured via the admin UI. Edit a section and click on the tab Conditions. Here you can select a question and define the value or choice identifier that must be entered or selected for the section to be displayed.

Additionally, sections can be conditionally displayed based on a custom implementation of the ConditionalSectionClass interface.

The generic HarmoneyConditionalSectionClass implementation can be configured for many use-cases. This can be done using the following settings:

Settings Configuration

Examples

Filters:

  • The dossierFilter field allows you to specify conditions based on the dossier.
  • The associatedPartyFilter field allows you to specify conditions based on the association between the current party and the dossier. This filter is only relevant if the subject of the section is a party! If the filter is defined and the subject is the dossier, the section will never be displayed. More details and examples for this filter can be found here.

Example: Show section when dossier is an insurance dossier, and the current party is an ubo of the client of the dossier with uboType: owner.

{
  "dossierFilter": {
    "equals": {
      "fieldPath": "type",
      "value": "INSURANCE"
    }
  },
  "associatedPartyFilter": {
    "associatedPartyTypes": {
      "clientOwners": {
        "filter": {
          "equals": {
            "fieldPath": "uboType",
            "value": "owner"
            }
          }
        }
    }
  }
}

Translations​

In the Translations tab, you should add all languages that the form needs to support. Importing and exporting translations can also be performed here.

Enabling the form​

  • You have to link the form to a dossier definition in case of an information exchange.
  • You have to link the form to an FSP-definition in case of a dossier questionnaire.

Best Practices​

  • Use consistent identifiers: Follow the lowercase_underscore pattern for all form definitions.

Reference​

The import envelope of a form definition. This is the shape of the JSON file that importing a form definition accepts and that exporting one produces.

FormDefinitionExportDTO​

Settings Configuration

Examples