Steps and logic

A form is a list of steps. Each step is one screen the contact sees, holding the elements that collect data. Splitting a form into steps keeps each screen short and lets you skip whole sections that don’t apply.

Declaring a step

{
  "id": "company_information",
  "label": "Company information",
  "elements": [
    { "key": "company_name", "type": "text", "title": "Company name" },
    { "key": "vat_number", "type": "text", "title": "VAT number" }
  ]
}

Property	Type	Description
`id`	String	Identifier for the step.
`label`	String	Step name shown in the progress indicator. Optional.
`enabled`	Boolean	Whether the step is part of the form. Defaults to `true`.
`elements`	Array	The elements on this screen.
`meta`	Object	Free-form data attached to the step. Ignored by the engine.

Submitting a step

A step needs a way to move forward. You don’t have to declare it: when a step contains no submit element, one is appended automatically. Declare a submit element yourself when you want to control its caption:

{ "type": "submit", "label": "Continue" }

The automatic button is skipped when the last element of the step has submit_on_change: true — answering that element submits the step on its own. That is the pattern for a one-question step that branches the rest of the form.

Conditional steps

Wrap a step in an :if / :then block to include it only when a condition holds:

{
  ":if": { ":cmp": "{data.account_type}", ":eq": "business" },
  ":then": {
    "id": "business_details",
    "label": "Business details",
    "elements": [
      { "key": "company_registration", "type": "text", "title": "Registration number" }
    ]
  }
}

The same wrapper works around individual elements, so you can hide a single field rather than a whole screen. See Conditional elements. Conditions are written in penscript — the full operator list is in the logic reference.

Prefer a conditional step over a long screen of conditional fields. A contact who sees a screen half-empty because most of its fields were hidden reads it as a broken form.

Variables

Variables are values defined once and reused across the whole form — static constants, or values computed from answers.

Defining variables

Without dependencies, use an object:

{
  "variables": {
    "company_email": "support@company.com",
    "max_upload_size": 10485760
  }
}

When one variable depends on another, use an array — entries are resolved in order:

{
  "variables": [
    { "base_price": 100 },
    { "tax_rate": 0.2 },
    { "total_price": "{base_price} * (1 + {tax_rate})" }
  ]
}

Using variables

Reference a variable anywhere in the form with {variable_name}:

{
  "type": "paragraph",
  "content": "Any question? Write to {company_email}."
}

user, data, and any name starting with $ are reserved. Do not use them as variable names.

Next steps

Elements

Every element type and its options

Portal pages

Welcome, review and ending screens

Penscript

The expression language behind conditions and variables

Form templates

Back to form templates

Get Started

Workspace

Penbox Agent

Cases

Forms

Penscript

Declaring a step

Submitting a step

Conditional steps

Variables

Defining variables

Using variables

Next steps

Elements

Portal pages

Penscript

Form templates

​Declaring a step

​Submitting a step

​Conditional steps

​Variables

​Defining variables

​Using variables

​Next steps

Elements

Portal pages

Penscript

Form templates

Declaring a step

Submitting a step

Conditional steps

Variables

Defining variables

Using variables

Next steps