Forms

As a part of a Flow signing process, participants can be requested to fill information into author-configured forms.

Forms are configured in the Create Instance end-point. Form configuration consists of two parts:

• A forms entry describing the fields that should be displayed on the form, along with field validation properties.
• A form step in the process entry which references the form description, and determines when and to whom should the form be displayed.

Participants can be prompted to fill-in a form at any stage of the signing process. form steps can be freely mixed with document signing and other actions using the parallel and sequential step combinators.

Since forms can be used in processes without documents, starting a process with an example form is very easy. One call to the Create Instance end-point is sufficient. Here is a Create Instance payload example of a simple process with a single form:

{
  "title": "Process with a Form",
  "documents": [],
  "participants": [
    {
      "label": "alice",
      "name": "Alice Newman"
    },
  ],
  "forms": [
    {
      "label": "simple-form",
      "schema": {
        "type": "object",
        "properties": {
          "nickname": {
            "type": "string",
            "minLength": 2,
            "maxLength": 50
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        },
        "propertyOrder": ["nickname", "email"],
        "required": ["email"]
      }
    },
  ],
  "process": {
    "type": "sequence",
    "steps": [
      {
        "type": "form",
        "form": "simple-form",
        "participant": "alice"
      }
    ]
  }
}

If Alice visits the Flow process, they are presented with this form:

After Alice submits the form, the process is completed.

Form Results

Form results can currently be obtained in two ways:

• In the Event log tab on the Process page
• In a form_filled Callback

For now, the results of filled-in forms cannot be reused in subsequent steps of the Flow process.

Form Features

Forms are described in a dialect of JSON Schema.

The root of the JSON schema must be an object with these properties:

• properties: a dictionary with the schema definitions of the form fields as described below.
• propertyOrder: list defining the order in which the fields will be displayed. It uses the keys from the properties dictionary.
• required: list of fields the participant is required to fill-in. It uses the keys from the properties dictionary.

Each form field has a title that describes its value. It can either be given in the title annotation of the field, as described below, or, as a fallback, it is automatically derived from the key of the field schema in the properties dictionary. Schema keys given in camel case are converted to space-separated capitalized words when used as field titles. For example, the schema key "companyName" is converted into "Company Name" field title.

Given this form schema:

{
  "type": "object",
  "properties": {
    "companyName": {
      "type": "string"
    },
    "companyDescription": {
      "type": "string"
    }
  },
  "propertyOrder": ["companyName", "companyDescription"],
  "required": ["companyName"]
}

the resulting form looks like this:

Field schemas

Values in the properties object contain JSON schemas of the respective form input fields. The usage is inspired be Schemas in the JSON Forms project.

The following sections detail available field schema definitions.

Text field

Text field is identified by the string type:

{
  "type": "string"
}

String fields support the following validation properties:

• minLength: minimum number of characters.
• maxLength: maximum number of characters.
• format: text format description. Currently supported values:
  • email: validates that the value is an e-mail.
  • date: shows a date picker.

Numerical fields

Integral and floating-point number input fields are identified by the types integer and number, respectively.

Both types of numerical fields share the same validation properties:

• minimum: inclusive minimum value.
• maximum: inclusive maximum value.
• exclusiveMinimum: exclusive minimum value.
• exclusiveMaximum: exclusive maximum value.

The integer type additionally supports a multipleOf property, which restricts the valid values to multiples of a given number.

Boolean fields

Boolean fields are identified by the boolean type. They are displayed as check-boxes.

{
  "type": "boolean"
}

Field annotations

Each form field can optionally be annotated with additional properties:

• title: short description of the form field.
• description: lengthy explanation of the purpose of the field.
• default: value used if the form field wasn't filled-in.

For example, a form with an annotated text field can be defined as follows:

{
  "type": "object",
  "properties": {
    "diet": {
      "type": "string",
      "title": "Dietary restrictions",
      "description": "Tell us if there's anything that you cannot eat.",
      "default": "Nothing"
    }
  },
  "propertyOrder": ["diet"],
  "required": []
}

It results in the following form being shown to the participant:

Larger Form Example

This example shows a form schema with multiple fields of different types:

{
  "type": "object",
  "properties": {
    "fullName": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "dateOfBirth": {
      "type": "string",
      "format": "date"
    },
    "age": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "exclusiveMaximum": 150
    },
    "vegetarian": {
      "type": "boolean"
    }
  },
  "propertyOrder": ["fullName", "email", "dateOfBirth", "age", "vegetarian"],
  "required": ["fullName", "email"]
}

The resulting form looks like this:

After submitting the form, the following entry is added to the Event log in the Process page: