# Session Variables
**Session variables** are workflow-level key/value pairs that stay alive throughout a user's session. Define them once on the workflow's Settings tab and any component on any module can reference them.
## When you'd use session variables
* Pre-setting a default location, customer, or pricing context that the workflow uses across multiple pages.
* Carrying state between modules (e.g. a customer picked on one page is referenced on the next).
* Building dynamic content (e.g. a heading that says *Welcome, {firstName}*).
## How they work
A session variable has two parts:
| Part | What it is |
| ----------------- | ---------------------------------------------------------------------------------- |
| **Key** | The name you reference in components (e.g. `selectedCustomer`, `defaultLocation`). |
| **Default Value** | The value the variable starts with at the beginning of each user session. |
When a user runs the workflow, all defined variables are loaded with their defaults. Components on any page can read them. A component can also write a new value, and the new value carries forward to subsequent pages until the user logs out.
## Define session variables
{% stepper %}
{% step %}
### Open the workflow's Settings tab
**Workflow Builder** → click the workflow row → **Settings** tab.
{% endstep %}
{% step %}
### Scroll to Session Variables
The section is near the bottom of the Settings tab.
{% endstep %}
{% step %}
### Click + Add Variable
A new row appears in the table with empty Key and Default Value inputs.
{% endstep %}
{% step %}
### Fill in Key and Default Value
| Column | Notes |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Key** | The name. Use descriptive, no-spaces strings (`selectedCustomerId`, `defaultLocation`). |
| **Default Value** | What the variable holds at the start of each session. Leave blank if a component will set it before any other component reads it. |
| {% endstep %} | |
{% step %}
### Repeat as needed
Add as many variables as the workflow needs.
{% endstep %}
{% step %}
### Save
Click **Save All Settings & Variables** at the bottom of the Settings tab.
{% endstep %}
{% endstepper %}
To remove a variable, click the trash icon on its row, then save.
## Built-in template variables
In addition to your own session variables, components support **template placeholders** for current-context values. These work in text fields, headings, and labels.
| Placeholder | Returns |
| ------------------------- | --------------------------- |
| `{{user.name}}` | Current user's full name |
| `{{user.firstName}}` | Current user's first name |
| `{{user.email}}` | Current user's email |
| `{{subsidiary.name}}` | Current subsidiary name |
| `{{subsidiary.currency}}` | Current subsidiary currency |
Additional context-specific placeholders are available depending on the page (e.g. transaction details on an Order Form, product data on a Catalog page). Components that support placeholders show a hint or auto-completion when you type `{{`.
## How variables get used
Once a variable is defined, components on any page in the workflow can:
* **Read** it — display its value, or use it as a filter.
* **Write** it — store a value (e.g. a customer ID picked in an Entity Search) for other pages to use later.
Common pattern: a Customer Field on the Order Form sets `selectedCustomerId`; the Account page later reads it to display that customer's profile.
For per-component configuration of reading and writing variables, see the Page Builder docs for the specific component.
## Best practices
* **Use descriptive keys.** `selectedCustomerId` beats `custId` or `x`.
* **Set sensible defaults.** If a variable should always start with a value, set it here. Don't rely on a component to initialise it.
* **Avoid key conflicts.** Two pages using the same key for different purposes will fight. Prefix where needed (`dashboard_date`, `report_date`).
* **Prune what you don't use.** Variables persist for the whole session — keep the list to what's actually referenced.
* **Document them.** Keep a short note (in the workflow Description, or in your own runbook) of what each key represents. Saves a lot of debugging time.
## Common issues
| If you see… | Try… |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Variable shows as `{{keyName}}` literally | The component doesn't support template placeholders. Verify the field accepts dynamic text. |
| Variable is empty mid-flow | The variable wasn't set before being read. Set a Default Value, or order the pages so the writing component runs first. |
| Variable holds a stale value from earlier | A component is overwriting it unexpectedly. Trace which component writes that key. |
| New variable doesn't appear in components after saving | Refresh the Page Builder. The component palette caches variable definitions; reloading picks up the new one. |
## Related
Assigning Workflows
The Settings tab in full — where Session Variables live.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.in8sync.com/client-admin-guide/workflow-builder-overview/module-variables.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.