Flow content data format

Describing flows using JSON

About flow content data

Most of the time, flows are edited within the Formsort Studio, which provides lots of tooling for creating, updating, and managing form flows.

However, access to a structured data format for flows is helpful for a few different use cases

• Capturing the specific questio

• Building a rendering service, such as generating PDFs from form submissions, where you need to know not only the answers that the responder submitted, but the structure of the form.

• Building internal UIs for reviewing changes to forms

• Importing large amounts of different forms, or very long single forms, which would take a long time to accomplish when inputting data manually.

Where flow content can be found

• Event subscription notfications for deployments will contain the flow content as a flowContent property.

• In the history tab of a variant, flow content for previously-deployed variant revision can be obtained through the Studio UI.

• In the Admin API,

  • retrieving data about a specific variant revision will contain a flowContent property.

  • importing a flow will take a flowContent to determine what content should be present within the newly-created flow.

Overall structure

The structure of this JSON format reflects closely the UI of the Formsort studio, wherein questions are contained within steps (which are usually displayed as a single page), which are themselves contained withing groups.

{
  "groups": [
     {
       "steps": [
         {
           "questions": [
             {}
             // ... more questions
           ]
         },
         // ... more steps
       ]
    },
    // ... more groups
  ],
  "variables": {
    "external": {},
    "calculated": {},
    "api": {}
  },
}

Groups

A group is a collection of steps (pages) that contain questions presented to the responder. Each group is designed to organize related questions for better flow and user experience. The structure and requirements for groups are as follows:

• label: (Required) A required string property that serves as the identifier or title for the group. This label is primarily for organizational purposes and may be shown to the responder in certain configurations.

• steps: (Required) An array of objects, each representing a step within the group. This is a required property, where each step contains a set of questions or content to be presented on a single page.

• enabledWhen: If set, the condition under which the group is enabled or visible. See conditional logic below.

• id: An optional string property that provides an internal identifier for the group.

Steps

Steps organize the questions and content into individual pages or segments of the flow.

• questions (Required): An array of question objects to be shown within this step. This array structures the questions that the responder will encounter on a single page or segment of the questionnaire.

• label: If set, provides a label or title shown to the responder at the top of the step. This offers additional context or instructions for the questions within this step.

• enabledWhen: If set, specifies the condition under which the step is enabled or visible, using MongoDB syntax for conditional logic based on answer variables.

• redirects: If set, contains an array of redirect objects that define conditional navigation paths upon the completion of the step. Each redirect can specify a URL to which the responder will be sent, based on answers within this step or previous steps.

• id: An optional identifier for the step, facilitating reference and navigation within the flow.

Questions

Questions capture and define individual questions within a step. Each question object may vary in properties based on its type, but common aspects include:

• type (Required): Specifies the type of question (e.g., boolean, select, text). This property determines the structure and behavior of the question.

• label (Required): The text displayed to the responder as the question. It should clearly describe what is being asked.

• schemaKey: (Required for non-informational types). If set, a string that specifies the variable name under which the answer will be stored, corresponding to the answer in the JSON schema.

• id: An optional identifier for the question, allowing for internal reference.

• enabledWhen: If set, the condition under which the question is enabled or visible. See conditional logic below.

• choices (Required for question types that pick between choices like select and boolean: Defines the set of options from which the responder can choose.

• optional: If set, indicates whether the responder can skip the question without providing an answer.

Question options

The question object will also contain a nested options object containing settings specific to certain question types.

Confirm questions

• confirmationText: If set, specifies the text shown next to the checkbox or confirmation control. This text is meant to clarify the action or choice for the user.

Select questions

• multiSelect: If set, allows multiple choices to be selected. The answer will always be stored as an array if this is true.

• randomize: If set, the choices presented to the responder will be randomized in order before being displayed.

• dynamic: If set, indicates that the choices are calculated at runtime, either through an inline calculation or an API lookup, allowing for dynamic updates based on previous inputs.

Grid questions

• subQuestions: The set of nested questions that are contained within the grid question

  • The required properties are the same as with standard questions.

  • These each can take an optional options object that

    • multiSelect: Similar to SelectQuestion, if set, this allows multiple selections within a sub-question. The answer is stored as an array.

Not all properties available within the UI are present in the flow content. If there is something missing that is critical to your use case, please contact the team using the in-app chat and we can make an addition request.

Variables

The top-level variables key contains information about variables that are not themselves collected by questions, but take their value from elsewhere.

• Variables under the external key describe External variables that can be passed in as URL parameters, POST bodies, or defaulted to a constant value.

• The api and calculated keys describe API variables and Calculated variables, respectively.

It is not currently possible to import API or calculated variables. They are present in exports for reference

Conditional logic

Conditional logic is represented in the flow content data structure as a MongoDB query.

The field names represent answers collected within the flow.

In this sample flow content, the responder is asked whether they have a cat, and if they do, the cat's name is asked

{
  "groups": [
    {
      "label": "Pet Information",
      "steps": [
        {
          "questions": [
            {
              "type": "boolean",
              "label": "Do you have a cat?",
              "schemaKey": "hasCat",
            },
            {
              "type": "text",
              "label": "What is your cat's name?",
              "schemaKey": "catName",
              "enabledWhen": {
                "hasCat": {
                  "$eq": true
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Validation errors

Formsort itself will always generate valid flow contents.

When using the Admin API to import flow content, the flow content format is validated before importing to ensure that it conforms to the specification.

If you provide an invalid flow content, you will receive a response with a 400 status code, and a Pydantic error message as the message field of the response JSON.

The message can be a bit terse, but can be used to determine where in the data structure the problem lies:

# 1 validation error for ImportFlowArgs
# flowContent.groups.0.steps.0.questions.0.text.label
#   Field required [type=missing, input_value={'schemaKey': 'first_name', 'type': 'text'}, input_type=dict]
#     For further information visit https://errors.pydantic.dev/2.4/v/missing

Imported flow contents may still display validation errors within the studio itself, such as dependency errors, where an answer is used before it is collected. These must be resolved before you can deploy the flow.

Detailed field reference

A detailed field reference can be found by calling the Admin API's /spec endpoint, which will return an OpenAPI specification of the input fields, along with descriptions of their usage.