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.
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
).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:
- Create the service Form Service Backend, available as ready-to-use plugin in the Marketplace;
- 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
).
- Add a new
JSON
file specifying its Name (e.g.config.json
). The file content is the Form Service ConfigurationJSON
and details about it can be found in the following sections. - 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
). - Create the required CRUD collections and configure the environment variables accordingly
The following sections provide a reference guide to all the available configuration options.
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
Name | Required | Default | Description |
---|---|---|---|
HTTP_PORT | No | 3000 | The port exposed by the service. |
LOG_LEVEL | No | info | The level of the log: trace , debug , info , warn , error , fatal . |
FORM_SERVICE_CONFIG_PATH | Yes | - | Path of the config map file containing the main service configuration. |
CRUD_PATH | No | crud-service | Internal path of the CRUD service. |
DRAFT_COLLECTION_ENDPOINT | No | /collection-draft | CRUD collection containing the forms drafts. |
ENABLE_VERSIONING | No | false | If the form data versioning is enabled. |
LOOKUP_CACHE_TTL | No | 600 | Time To Live (TTL) for the lookup cache entries, expressed in seconds. 0 means data never expires. |
LOOKUP_CACHE_CHECK_PERIOD | No | 300 | Time 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.
Name | Type | Required | Default | Documentation | Description |
---|---|---|---|---|---|
theming | Object | No | - | theming | Contains the theming information. This property can be used to customize the Form Builder CSS . |
formSchemasCrud | string | No | /form-schemas | form schemas CRUD endpoint | The endpoint used by the Form Service Backend to perform CRUD operation with the forms created with the Form Builder. |
formSchemaMapCrud | string | No | /form-schema-map | form schema map CRUD endpoint | The endpoint used by the Form Service Backend to link form data submitted with the Form Visualizer with form schemas created by the Form Builder. |
formDraftsCrud | string | No | /form-drafts | form drafts CRUD endpoint | The endpoint used by the Form Service Backend to perform CRUD operations on drafts. |
formMetadata | Object[] | No | - | form metadata | The additional metadata shown in the Form Builder and required by the CRUD to save the Forms created with the Form Builder. |
formSubmitUrls | Object[] | No | - | form submit urls | Contains 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. |
formVisualizerOptions | Object | No | - | form visualizer | This 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. |
formBuilderOptions | Object | No | - | form builder | this 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. |
formBuilderCustomProperties | Object | No | - | form builder | this object contains customization properties for the fields in the builder that are not strictly related to the form.io builder. |
defaultClientType | string | No | - | 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 ). | |
isMessagingAvailable | boolean | No | - | notifications | It'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. |
messagingOptions | Object | Yes if isMessagingAvailable is true | - | notifications | This 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.
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.
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.
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"
}
]
}
The value of the auto save interval must be set in milliseconds (from 1 second to 48 hours)
There is a default value for messageToBeShownOnExpiredForm
which is This form is expired!
.
Export fields (exportFields
)
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
)
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"
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
)
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 theGET /export
endpoint (the/export
path is appended at runtime, must not be included in theexportUrl
).
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
.
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
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.
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
.
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.