# Flow content data format

### 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](https://github.com/formsort/api-examples/tree/main/answers-pdf-service), building internal review UIs, or importing long or complex forms.

### Where to Access Flow Content

Flow content is available in several places:

* [**Event subscriptions**](https://docs.formsort.com/event-subscriptions): Available in the `flowContent` property of event payloads.
* **Studio UI**: View past `flowContent` revisions in the History tab of a variant.
*  [**Admin API**](https://docs.formsort.com/formsort-admin-api/admin-api):
  * 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.

```json
{
  "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](#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.

{% hint style="danger" %}
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.
{% endhint %}

### 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](https://docs.formsort.com/response-data-collection-and-management/variable-schema/external-answers) that can be passed in as URL parameters, POST bodies, or defaulted to a constant value.
* The **`api`** and **`calculated`** keys describe [API variables](https://docs.formsort.com/response-data-collection-and-management/variable-schema/api-answers) and [Calculated variables](https://docs.formsort.com/response-data-collection-and-management/variable-schema/calculated-answers), respectively.

{% hint style="info" %}
It is not currently possible to import API or calculated variables. They are present in exports for reference
{% endhint %}

### Conditional logic

[Conditional logic](https://docs.formsort.com/conditions-and-logic) is represented in the flow content data structure as [a MongoDB query](https://www.mongodb.com/docs/manual/reference/operator/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](https://docs.pydantic.dev/latest/) 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
```

{% hint style="info" %}
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.
{% endhint %}

## 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.