Skip to main content
Version: 12.x (Current)

Configuration

In order to configure the Form Service with the Console you need to deploy two services, Form Service Backend and the Form Service Frontend. Both are available in the Marketplace.

  1. Create the Form Service Backend to serve the APIs needed for the correct functionality of the Form Service Frontend. To create the Form Service Backend you can search for it in the Console Marketplace. Choose a name for the new service (e.g. form-service-backend).

  2. Create the /api/v1/forms endpoint for the newly created microservice. The endpoint of this microservice must be exactly this one because the Form Service Frontend will use this path as prefix for the API calls to the Form Service Backend.

The Form Service Backend exposes the GET /builder/config and GET /visualizer/config endpoints used to configure the Form Service Frontend. These endpoints return the configurations in JSON format.

The microservice requires the FORM_SERVICE_CONFIG_PATH environment variable to specify the path where the JSON is stored. If no path is defined a default configuration will be used. The default config has only the formSchemasCrud, formSchemaMapCrud and formDraftsCrud fields with default values. See the following sections for further details about these parameters.

To configure the Form Service Backend service with the Console, follow these steps:

  1. Create the service Form Service Backend, available as ready-to-use plugin in the Marketplace;
  2. Add a custom configuration:
    • select the configuration Type as ConfigMap;
    • insert the configuration Name;
    • specify the Runtime Mount Path (e.g. /home/node/app/form-service).
  3. Add a new JSON file specifying its Name (e.g. config.json). The file content is the Form Service Configuration JSON and details about it can be found in the following sections.
  4. Add the environment variable FORM_SERVICE_CONFIG_PATH with the full path of the file created in the previous step (e.g. /home/node/app/form-service/config.json).
  5. Create the required CRUD collections and configure the environment variables accordingly

The following sections provide a reference guide to all the available configuration options.

danger

At the moment, in order for the basic styling of the Form Service Frontend to work properly, the Form Service Backend endpoints must be exposed on the / (root) path. If the Form Service Backend is exposed on a different path that isn't / (i.e. /my-path/...), in order for the styling to work, a path rewrite must be performed at the API Gateway level.

Environment variables​

NameRequiredDefaultDescription
HTTP_PORTNo3000The port exposed by the service.
LOG_LEVELNoinfoThe level of the log: trace, debug, info, warn, error, fatal.
FORM_SERVICE_CONFIG_PATHYes-Path of the config map file containing the main service configuration.
CRUD_PATHNocrud-serviceInternal path of the CRUD service.
DRAFT_COLLECTION_ENDPOINTNo/collection-draftCRUD collection containing the forms drafts.
ENABLE_VERSIONINGNofalseIf the form data versioning is enabled.
LOOKUP_CACHE_TTLNo600Time To Live (TTL) for the lookup cache entries, expressed in seconds. 0 means data never expires.
LOOKUP_CACHE_CHECK_PERIODNo300Time in seconds between expiration checks and deletion of expired keys in the lookup cache.

Service configuration​

The Form Service Configuration is a JSON object with the following root properties.

NameTypeRequiredDefaultDocumentationDescription
themingObjectNo-themingContains the theming information. This property can be used to customize the Form Builder CSS.
formSchemasCrudstringNo/form-schemasform schemas CRUD endpointThe endpoint used by the Form Service Backend to perform CRUD operation with the forms created with the Form Builder.
formSchemaMapCrudstringNo/form-schema-mapform schema map CRUD endpointThe endpoint used by the Form Service Backend to link form data submitted with the Form Visualizer with form schemas created by the Form Builder.
formDraftsCrudstringNo/form-draftsform drafts CRUD endpointThe endpoint used by the Form Service Backend to perform CRUD operations on drafts.
formMetadataObject[]No-form metadataThe additional metadata shown in the Form Builder and required by the CRUD to save the Forms created with the Form Builder.
formSubmitUrlsObject[]No-form submit urlsContains the list of URLs that can be used to perform Form submission. The Form Builder will show the available URLs if the array is provided, otherwise a text field will be shown to allow user to provide the URL.
formVisualizerOptionsObjectNo-form visualizerThis object contains the Form Visualizer Frontend options. Specifically, it allows you to define a value for configurable properties in the Form Service Frontend (such as the autosave time range, export options...). Note: these options do not affect Form.io properties.
formBuilderOptionsObjectNo-form builderthis object contains the Form Builder options to customize the Form Builder interface such as the components available to the user and the fields shown in their settings.
formBuilderCustomPropertiesObjectNo-form builderthis object contains customization properties for the fields in the builder that are not strictly related to the form.io builder.
defaultClientTypestringNo-Contains (from version 1.2.0) the default client type that will be forwarded to other platform services when the client type header is not provided from the frontend service (defaults to formService).
isMessagingAvailablebooleanNo-notificationsIt's a toggle switch to enable notifications via the messaging service as soon as the form is submitted. Available starting from version 1.9.0.
messagingOptionsObjectYes if isMessagingAvailable is true-notificationsThis object contains options to configure notifications via the messaging service. Available starting from version 1.9.0.

The JSON file is structured like the following example:

{
  "theming": {
    "primaryColor": "#22f184"
  },
  "formSchemasCrud": "/form-schemas",
  "formSchemaMapCrud": "/form-schema-map",
  "formDraftsCrud": "/form-drafts",
  "formMetadata": [],
  "formSubmitUrls": [],
  "formVisualizerOptions": {},
  "formBuilderOptions": {}
}

Theming parameters (theming)​

This part of the configuration object allows the customization of the Form Builder UI colors. At the moment the following parameters are supported:

  • primaryColor
    • type: string;
    • required: false;
    • description: the primary color that is applied to the Form Builder items and buttons, accepted values are 3, 6, or 8 digits Hex and CSS color keywords;
    • default: the micro-lc primaryColor if the Form Builder is used as micro-lc plugin, otherwise the formio.js stylesheet is used.

Here an example of a theming object to add in Form Builder configuration JSON:

  "theming": {
    "primaryColor": "#22f184"
  }

Form Schemas CRUD endpoint parameter (formSchemasCrud)​

This parameter is the CRUD endpoint used in the Form Service Backend to perform CRUD operations on the forms created with the Form Builder. It can be any CRUD endpoint. The default value is /form-schemas.

The properties of the CRUD are:

  • name, of type string;
  • formSubmitUrl, of type string, which specifies the url that will be used for Form submission;
  • formSchema, of type object, which is the property where the configured Form JSON will be saved;
  • formVisualizerOptions , of type object, which is the property where the form options JSON, will be saved;
  • formAvailabilityDate (optional), of type string, which is the date when the form will be available.
  • formExpirationDate (optional), of type string, which is the expiration date of the form.
  • formExpirationMessage (optional), of type string, which is the expiration message of the form.
note

The formVisualizerOptions property allows the definition of Form.io options related to the form schema, for instance, translation options. These options are then used by the Form Visualizer.

This feature is available from Form Service Backend v1.2.2.

In addition, you have to also add to your CRUD properties for the additional Form metadata, defined in form metadata parameters section.

This example show how to use the formVisualizerOptions parameter in the form_schema collection to specify the language for the visualizer in the Form Service Frontend.
"formVisualizerOptions": {
  "language": "it",
  "i18n": {
    "it": {
      "next": "Avanti",
      "previous": "Indietro",
      "submit": "Conferma",
      "error": "Si prega di correggere gli errori seguenti prima di inviare.",
      "invalid_date": "{{field}} non è una data valida.",
      "invalid_email": "{{field}} deve essere un indirizzo email valido.",
      "invalid_regex": "{{field}} non corrisponde al modello {{regex}}.",
      "mask": "{{field}} non corrisponde alla maschera.",
      "max": "{{field}} non può essere maggiore di {{max}}.",
      "maxLength": "{{field}} deve essere più breve di {{length}} caratteri.",
      "min": "{{field}} non può essere inferiore a {{min}}.",
      "minLength": "{{field}} deve essere più lungo di {{length}} caratteri.",
      "pattern": "{{field}} non corrisponde al modello {{pattern}}",
      "required": "{{field}} è obbligatorio"
    }
  }
}

Form Schema map CRUD endpoint parameter (formSchemaMapCrud)​

This CRUD endpoint is used by the Form Service Backend to link form data (submitted with a Form Visualizer) to their form schemas, created with the Form Builder. The default value is /form-schema-map.

The mandatory properties of this CRUD are:

  • formDataId, of type string, the ID of the submitted form data;
  • formSchemaId, of type string, the ID of the form schema saved in the formSchemasCrud endpoint.

In addition (from Form Service Backend v1.1.1), you can add the following optional property:

  • options, of type object, to save an additional JSON of options to further customize the visualization of a submitted form in the Form Visualizer. The available options can be found in the form.io documentation.

The options can be updated for example updated with a POST decorator after the submission of a new form.

caution

The Form Service Backend PUT /visualizer/forms/:id endpoint will reply with an error while attempting an update of a submitted form with "readOnly": true property in the Form Schema map options.

Form Drafts CRUD endpoint parameter (formDraftsCrud)​

This parameter is the CRUD endpoint used in the Form Service Backend to perform CRUD operations on drafts. It can be any CRUD endpoint. The default value is /form-drafts.

The main properties of the CRUD are:

  • data, of type object, which contains the data saved on the draft;
  • formSchemaId, of type string; the ID of the form schema;
  • stableFormId, of type string; The ID of the stable form of the draft.

Form Metadata parameters (formMetadata)​

This config section specifies the optional metadata of the Forms created with the Form Builder. An array of form field objects must be defined with the following properties:

  • name, the name of the field;
  • type, right now the only supported one is string;
  • label, the label you want to show for this field.

Here an example of an additional category field:

  "formMetadata": [
    {
      "name": "category",
      "type": "string",
        "label": "Category"
    }
  ]

Form submit urls parameters (formSubmitUrls)​

This config section specifies the URLs available to the user to specify where the Form data will be saved upon submission. An array of submit url objects must be defined with the following properties:

  • id;
  • submitUrl the submission URL;
  • label: it is not mandatory, it allows to define a user friendly name that will be displayed in the Form Builder as select entry (if missing the submitUrl will be used).

Here an example of two endpoints:

  "formSubmitUrls": [
    {
      "id": "satisfaction-survey",
      "submitUrl": "http://crud-service/satisfaction-form-submissions",
      "label": "CMS - Satisfaction surveys"
    },
    {
      "id": "screening-questionnaire",
      "submitUrl": "https://www.external-service.com/screening-form-submissions",
      "label": "App - Screening questionnaires"
    }
  ]

The user of the Form Builder will see a dropdown menu with the specified options. If the array is empty or the formSubmitUrls is not provided, a text field will be used.

caution

The submit urls can be either provided with the CRUD Service or with custom APIs, but it's important that they expose the following methods:

  • GET /{id}: to return the submitted data of a form by ID;
  • GET /export: to return all the submitted forms data as newline-delimited JSON;
  • POST /: to save the data of a new submitted form filled by a user;
  • PATCH /{id}: to update a submitted form by ID;
  • DELETE /{id}: to delete a submitted form, it is required to allow rollback when inserts in the formSchemaMapCrud fail;

More details on the submit URLs APIs can be found at this page.

Form Visualizer Options parameters (formVisualizerOptions)​

This part of the configuration object allows the customization of the Form Visualizer.

Here you can find an example of a formVisualizerOptions object:

{
  "autosaveIntervalValueMs": 5000,
  "messageToBeShownOnExpiredForm": "This form is expired!",
  "exportFields": [
    "_id",
    "__STATE__",
    "createdAt",
    "creatorId",
    "updatedAt",
    "updaterId",
    "formSchemaId"
  ],
  "exportLookups": {
    "formSchemaId": {
      "lookupDataSource": "http://crud-service/form-schemas",
      "lookupKey": "_id",
      "lookupValue": "{{name}}"
    },
    "patientId": {
      "lookupDataSource": "http://crud-service/users",
      "lookupKey": "_id",
      "lookupValue": "{{firstName}} {{lastName}}"
    }
  },
  "exportRedirects": [
    {
      "submitUrl": "http://form-data-manager/forms",
      "exportUrl": "http://crud-service/forms"
    }
  ]
}
note

The value of the auto save interval must be set in milliseconds (from 1 second to 48 hours)

note

There is a default value for messageToBeShownOnExpiredForm which is This form is expired!.

Export fields (exportFields)​

info

v1.7.0. This setting is available only since version 1.7.0

When you export the form data to a CSV, the CSV file includes all the fields available in the current version of the form schema. If you want to include additional fields available in the response of the GET /export endpoint, you must add the field names in this configuration options. These fields are mapped to CSV columns before the form data in the exact same order as they are provided in the configuration. If the form data is stored in a CRUD collection, you may want to include its predefined properties.

Export lookups (exportLookups)​

info

v1.7.0. This setting is available only since version 1.7.0

When you export form data by calling the GET /visualizer/forms/export endpoint, you can configure the Form Service Backend to resolve the value of a CSV column through a CRUD lookup. For example, you may want to replace the form schema ID with the name of the form as shown in the Microfrontend Composer.

To configure the lookup you must assign to the exportLookups field an object value, whose properties correspond to the names of the CSV columns you want to perform the lookup on (formSchemaId in the example above). Remember, you must use the colum name exactly as it appears on the CSV, so for nested fields you should use the outerField.innerField notation.

Each lookup must have the following properties:

  • lookupDataSource: the URL of the external data source, which must expose a GET /export endpoint compatible with the CRUD Service;
  • lookupKey: the data source field to perform the lookup on, searching for the record matching the column value;
  • lookupValue: the value to replace the column value with, must be a string with placeholders enclosed between double curly braces; each placeholder must refer a data source field and will be evaluated at runtime and replaced with the corresponding value.

To see how it works, let's suppose we have a CSV with a single row looking like this:

"_id","formSchemaId","data.birthDate","data.birthPlace"
"6246b2aff30214fb40d3e86d","62162180544cea83e8e130e7","2000-06-15","Rome"

If you configured the Form Service Backend as shown above the lookup algorithm will search for a record with the _id field (the lookup key) equals to 62162180544cea83e8e130e7 (the column value). If the data source contains the following record:

{
  "_id": "62162180544cea83e8e130e7",
  "name": "Medical History 2023"
}

the lookup algorithm would find a match and resolve the name placeholder with Medical History 2023, the value of the corresponding record field, resulting in the following CSV:

"_id","formSchemaId","data.birthDate","data.birthPlace"
"6246b2aff30214fb40d3e86d","Medical History 2023","2000-06-15","Rome"
danger

If, for any reason, a lookup on a form field fails, the service ignores the error and simply leaves the existing value unmodified.

Export redirects (exportRedirects)​

info

v1.7.0. This setting is available only since version 1.7.0

If you are exporting form data associated to a schema with a submitUrl pointing to an external service which does not expose a GET /export but acts as a proxy towards a CRUD or service with a compliant API, you can configure a redirect, specifying the following properties:

  • submitUrl: the original submit URL, must match exactly a lookup lookupDataSource;
  • exportUrl: the redirect URL, that is going to be used in place of the submitUrl to call the GET /export endpoint (the /export path is appended at runtime, must not be included in the exportUrl).

So, if we have a redirect configured as follows:

{
  "submitUrl": "http://form-data-manager/forms",
  "exportUrl": "http://crud-service/forms"
}

the Form Service Backend, when encounters a lookup with submitUrl equals to http://form-data-manager/forms, sends a GET http://crud-service/forms/export request to fetch the lookup data.

Form Builder Options parameters (formBuilderOptions)​

This part of the configuration object allows the customization of the Form Builder interface by providing the components you wish to add to the builder and customize the options available in their settings.

You can use the formio.js examples and documentation for more details on how you can customize the form builder. The formio.js sandbox is a great tool to test the results of your Form Builder Options JSON.

Here you can find an example of a formBuilderOptions object that can be used in the sandbox mentioned above:

 "formBuilderOptions": {
  "builder": {
   "basic": {
    "ignore": true
   },
   "advanced": {
    "default": false,
    "components": {
     "email": false,
     "signature": true,
     "file": true,
     "recaptcha": true,
     "resource": true
    }
   },
   "premium": {
    "default": false,
    "ignore": true,
    "components": {
     "custom": false
    }
   },
   "customBasic": {
    "title": "Basic Components",
    "default": true,
    "weight": 0,
    "components": {
     "textfield": true,
     "textarea": true,
     "email": true,
     "phoneNumber": true
    }
   },
   "custom": {
    "title": "User Fields",
    "weight": 1,
    "components": {
     "firstName": {
      "title": "First Name",
      "key": "firstName",
      "icon": "terminal",
      "schema": {
       "label": "First Name",
       "type": "textfield",
       "key": "firstName",
       "input": true
      }
     },
     "lastName": {
      "title": "Last Name",
      "key": "lastName",
      "icon": "terminal",
      "schema": {
       "label": "Last Name",
       "type": "textfield",
       "key": "lastName",
       "input": true
      }
     },
     "email": {
      "title": "Email",
      "key": "email",
      "icon": "at",
      "schema": {
       "label": "Email",
       "type": "email",
       "key": "email",
       "input": true
      }
     },
     "phoneNumber": {
      "title": "Mobile Phone",
      "key": "mobilePhone",
      "icon": "phone-square",
      "schema": {
       "label": "Mobile Phone",
       "type": "phoneNumber",
       "key": "mobilePhone",
       "input": true,
       "prefix": "IT",
       "modalEdit": true
      }
     }
    }
   }
  },
  "editForm": {
   "textfield": [
    {
     "key": "display",
     "ignore": false,
     "components": [
      {
       "key": "placeholder",
       "ignore": false
      },
      {
       "key": "tooltip",
       "ignore": true
      },
      {
       "key": "prefix",
       "ignore": true
      },
      {
       "key": "persistent",
       "ignore": true
      }
     ]
    },
    {
     "key": "api",
     "ignore": true
    },
    {
     "key": "data",
     "ignore": false,
     "components": [
      {
       "key": "multiple",
       "ignore": true
      },
      {
       "key": "persistent",
       "ignore": true
      }
     ]
    }
   ]
  },
  "i18n": {
   "it": {
    "Component": "Componente",
    "Validation": "Validazione",
    "Search field(s) ": "Ricerca campi",
    "Help": "Aiuto",
    "Label": "Etichetta",
    "Position for the label for this field.": "Posizione dell'etichetta per questo campo.",
    "Preview": "Anteprima",
    "Advanced Logic": "Logica Avanzata",
    "Actions": "Azioni",
    "Save Logic": "Salva Logica",
    "Description for this field.": "Descrizione per questo campo",
    "Input Field": "Campo d'inserimento",
    "Custom Default Value": "Valore predefinito personalizzato",
    "An instance of": "Un'istanza di",
    "The current component JSON": "Il JSON del componente attuale",
    "The following variables are available in all scripts": "Le seguenti variabili sono disponibili in tutti gli script",
    "Save": "Salva",
    "Cancel": "Annulla",
    "Remove": "Rimuovi",
    "Key": "Chiave",
    "Value": "Valore",
    "Change": "Cambia",
    "Type to search": "Digita per cercare"
   }
  }
 }

Form Builder Custom Properties parameters (formBuilderCustomProperties)​

From version 1.9.0 it is possible to add other properties for customizing the form builder. The properties that can be set are the following:

  • formExpirationDateFormat: the date format shown in the expiration datepicker. Default is YYYY-MM-DD.
  • formAvailabilityDateFormat: the date format shown in the availability datepicker. Default is YYYY-MM-DD.

Default client type parameter (defaultClientType)​

From version 1.2.0 the service checks if the CLIENTTYPE_HEADER_KEY environment variable is already available in the request's headers. If missing, this parameter allows the customization of the client type that will be forwarded to other platform services. The default value is formService.

caution

An API Key with the default value (or a value of your choice) must be created and enabled in the Console in order to ensure the service's functionality.

CRUD collections​

All the following CRUD collections are required.

form_schemas​

In order to perform CRUD operations on the forms created with the Form Service, we recommend to create a CRUD named form_schemas.

The required properties (specified in the form schemas CRUD endpoint parameter section) of the CRUD can be imported downloading this json file. If any, you need to also add the additional form metadata parameters.

You also need to expose a new endpoint /form-schemas following this guide. You can use a different name paying attention to change the formSchemasCrud parameter accordingly. The type of this endpoint is CRUD.

form_schema_map​

This CRUD is required and used by the Form Service Backend to link form data (submitted by a Form Visualizer user) with forms created with the Form Builder.

The required properties (specified in the form schema map CRUD endpoint parameter section) of this CRUD can be imported downloading this json file.

If you want to use the default value of the formSchemaMapCrud you need to expose this CRUD with the /form-schema-map endpoint. Any other endpoint must be specified in the configuration JSON.

form_drafts​

This CRUD is required and used by the Form Service Backend to store draft data (inserted by a Form Visualizer user).

The required properties (specified in the form drafts CRUD endpoint parameter section) of this CRUD can be imported downloading this json file.

If you want to use the default value of the formDraftsCrud you need to expose this CRUD with the /form-drafts endpoint. Any other endpoint must be specified in the configuration JSON.

Once the Form Service Backend is configured you can continue setting up the Form Service Frontend following this guide.

Other configurations​

Form export lookup cache​

info

v1.7.0. This feature is available only since version 1.7.0

When you call the GET /visualizer/forms/export endpoint to export form data and you have configured some lookups (see section Export lookups), the service uses an internal in-memory cache to store the information required to resolve the lookups, to avoid making a lot of HTTP requests to the external systems. For example, if we had to perform lookups on 3 columns on 100 forms, this may result in up to 300 HTTP requests.

danger

Since the service fills the lookup cache with the data required to resolve the lookups, if the data source contains a lot of records, you may notice a high RAM usage that could cause the containers to crash if the service is not configured appropriately.

You can set the expiration and check period for the lookup cache using the environment variables LOOKUP_CACHE_TTL and LOOKUP_CACHE_CHECK_PERIOD, see the environment variables section for more details.

Form data versioning support​

From version 1.5.0 the Form-Service Backend supports the versioning of the form data, by including the parameter _v to the request performed to retrieve form data. The _v is an optional query parameter of the GET /visualizer/forms/{id} called by the Form-Service Backend.

In order to forward the _v to the service in charge of managing the form data, the ENABLE_VERSIONING environment variable must be set to true. If not specified, the _v parameter will not be included in the request performed to retrieve data, since, by default, the ENABLE_VERSIONING variable is set to false.

danger

Since the crud-service does not support document versioning, it will not accept the _v parameter, leading to a 400 Bad request error. When the submit_url is a crud-service endpoint, the ENABLE_VERSIONING cannot be set to true.

More in general, the ENABLE_VERSIONING variable cannot be set to true when the submit_url refers to endpoints which do not support the versioning of data and/or when the inclusion of an unknown parameter can leads to error replies.