Flow content data format
Describing flows using JSON
Overview
Formsort flows can be built entirely within the Studio, which provides an intuitive UI for managing your form logic and layout. However, advanced users may want to work directly with the underlying flow content data—a structured JSON format that mirrors the Studio’s interface. Accessing this format can be useful for tasks like auditing questions, generating PDFs, building internal review UIs, or importing long or complex forms.
Where to Access Flow Content
Flow content is available in several places:
Event subscriptions: Available in the
flowContent
property of event payloads.Studio UI: View past
flowContent
revisions in the History tab of a variant.Fetching a variant revision includes a
flowContent
property.Importing a flow requires providing a
flowContent
object.
Structure Overview
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 ofquestion
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 ofredirect
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 likeselect
andboolean
: 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 questionThe required properties are the same as with standard questions.
These each can take an optional
options
object thatmultiSelect
: 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
andcalculated
keys describe API variables and Calculated variables, respectively.
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
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.
Last updated
Was this helpful?