Configure an internal form

Abstract

Learn how to configure an internal form by defining a form schema, pages, and fields, setting labels and localization, configuring the submit button, and referencing the form from a workflow.

Internal forms are used in assessment workflows to collect information from users inside the platform or to require a review or approval before an assessment can continue. You configure internal forms separately from workflows, then reference them using an internal forms step.

This topic explains how to configure an internal form and link it to a workflow.

Create an internal form schema file

Define each form in its own JSON or Jsonnet file. Form schemas are versioned and managed independently of workflows.

Start with a simple top-level structure:

{ 
 "version": "v1", 
 "content": {  
  "id": "sample-review-form"
 }
}

Define the form title

Set a title to display at the top of the form. Titles support localization for each of Moody's for Compliance's supported languages. Learn more about translation.

"title": { 
 "type": "custom", 
 "content": {  
  "en": "Status review",  
  "de": "Statusüberprüfung",
  "es": "Revisión del estado",
  "fr": "Examen du statut",
  "it": "Aggiornamento sullo stato"
 }
}

Add pages to the form

Forms are split into pages. Each page contains a list of fields.

"pages": [ 
 {  
  "id": "sample-review-form-page-1"
 }
]

Use page IDs consistently. You reference them later when defining page context.

Add fields to a page

Each page includes one or more fields that define the information the user must provide.

Every field should include:

id: A unique identifier, used to access submitted values later in the workflow.
field_type: Controls how users provide their input. The following field types are supported:
- textarea: Collects free-form, multi-line text input from the user.
- radio: Displays a list of options for the user to select a single value. Each option defines a returned value and a label shown to the user.
- multi_select_checkbox: Displays a list of options from which the user can select one or more values. Each option defines a returned value and a label shown to the user.
- number: Collects numeric input. Optionally, define a min_value or max_value to constrain acceptable input.
label: Defines the question or instruction shown to the user. Labels are defined per field and support localization.
description: Optional supplementary help text shown with the field. Use this to clarify what's expected.
placeholder: Optional hint text displayed inside the input control. Applies to input types such as textarea.
default_value: An optional value that is pre-filled when the form loads.
validation: Optionally, use the validation property to make a field mandatory by setting required to true.

"fields": [ 
 {
  "id": "reason-field", 
  "label": {
   "type": "custom", 
   "content": {  
    "en": "Please outline the investigation you have conducted.",  
    "fr": "Veuillez décrire l'enquête que vous avez menée." 
   }
  }, 
  "field_type": {
   "type": "textarea"
  }, 
  "validation": []
 },
 {
  "id": "procedure-check", 
  "label": {
   "type": "custom", 
   "content": {  
    "en": "Would you like to proceed?",  
    "fr": "Souhaitez-vous continuer ?" 
   }
  }, 
  "field_type": {
   "type": "radio",
   "content": {
    "options": [
     {
      "value": "yes",
      "label": {
       "type": "custom",
       "content": {
        "en": "Proceed",
        "fr": "Procéder"
       }
      }
     },
     {
      "value": "no",
      "label": {
       "type": "custom",
       "content": {
        "en": "Reject",
        "fr": "Rejeter"
       }
     }
    ]
   }
  }, 
  "validation": [
   { "required": "true" }
  ]
 }
]

Configure the submit button

Set the text shown on the submit button. The button text supports localization.

"submit_button": { 
 "text": {  
  "type": "custom",  
  "content": {   
   "en": "Submit",   
   "fr": "Soumettre"  
  } 
 }
}

Define optional page context

Page context links a form page to the output from one or more workflow steps. This controls what extra information is shown next to the form page in the platform.

"context": { 
 "page_contexts": {  
  "sample-review-form-page-1": ["risk"] 
 }
}

Context is optional. Leave it out if the form doesn't need additional information.

Reference the internal form from a workflow

After defining the internal form schema, you can reference the form from a workflow using an external step with the internal_forms connector.

"review_form": { 
 "arguments": ["start"], 
 "expression": {  
  "evaluator": "Jaq",  
  "expression": "0" 
 }, 
 "destination": {  
  "type": "External",  
  "connector": "internal_forms",  
  "config": "import 'sample-review-form.jsonnet'" 
 }
}

When the workflow reaches this step:

A task is created for the user.
The workflow pauses.
Submitted form values become available as step output.