Flow content data format
Describing flows using JSON
Last updated
Was this helpful?
Describing flows using JSON
Last updated
Was this helpful?
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 , 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.
notfications for deployments will contain the flow content as a flowContent property.
In the tab of a variant, flow content for previously-deployed variant revision can be obtained through the Studio UI.
In the ,
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.
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.
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.
id: An optional string property that provides an internal identifier for the group.
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 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.
The question object will also contain a nested options object containing settings specific to certain question types.
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.
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.
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.
The top-level variables key contains information about variables that are not themselves collected by questions, but take their value from elsewhere.
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
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.
The message can be a bit terse, but can be used to determine where in the data structure the problem lies:
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.
enabledWhen: If set, the condition under which the group is enabled or visible. See below.
Variables under the external key describe that can be passed in as URL parameters, POST bodies, or defaulted to a constant value.
The api and calculated keys describe and , respectively.
is represented in the flow content data structure as .
If you provide an invalid flow content, you will receive a response with a 400 status code, and a error message as the message field of the response JSON.