---
title: Document variables and data sources
description: >-
  How variables, smart tables, formats, and empty-value rules fill a Smart
  Document with student, program, cohort, time-tracking, and institution data.
sidebar:
  order: 4
  label: Document variables
---

**Document variables** are placeholders you insert in the TipTap editor with **Insert → Variable** (or by typing `@` or `/`). When a document is generated, each variable is replaced with real data for that user, module, curriculum, room, or certificate.

:::tip
Choose a user in **As user:** and turn on **Show sample data** in the toolbar. The variables then show real values while you write.
:::

## Why it matters

Variables keep one template valid for everyone. If the data behind them is complete and correct, generated documents need no manual fixing. If it is not, gaps appear in letters and contracts.

## Before you start

| Requirement | Detail |
|---|---|
| **Feature and permission** | **Smart Documents** (FuxamCMS package) and `read-write:settings-service-contracts`. |
| **Data maintained** | The fields you want to use are filled in on user profiles or records. |
| **Custom columns** | Create [custom columns](/docs/fuxam-web/base/user-management/custom-columns) before you use them as variables. |
| **Test user** | A user or module version to preview with. |

## What variables can show

Variables are grouped by where their data comes from. The groups you see depend on the object type.

| Source | Examples |
|---|---|
| **Assigned student** | Name, contact details, and your institution's custom columns |
| **Institution** | Institution name and details |
| **Study program** | Program and cohort data ([Study programs and cohorts](/docs/fuxam-web/cms/programs-and-planning/study-programs-cohorts)) |
| **Admission** | Application data |
| **Tuition** | Tuition and fee data |
| **Signature** | Signature blocks |
| **Time tracking** | Values for a time-tracking period ([Time tracking](/docs/fuxam-web/cms/time-tracking)) |
| **Module, Curriculum, Room** | Fields of the chosen record for those object types |
| **Certificate** | Course-completion data for certificate templates |
| **Exam legal document** | Exam-related legal document data |

## Formatting and empty values

Select a variable in the text to open **Variable settings**.

- **Format**: **Text**, **UPPERCASE**, or one of several date and date-and-time formats.
- **When empty**: **Hide** the value, show a dash (—), or show **Fallback text** you write yourself.
- **Styling**: show the value in bold when data exists.

## Smart tables

**Insert → Smart table** fills a table automatically from a data source and adapts to each user when the document is generated. Data sources include **Study plan**, **User courses**, **Appointment overview**, **Workload**, and **Time tracking**. Module templates offer **Parent Module and Submodules**. If no source suits the document type, the dialog says so.

Saving is blocked while a smart table data source needs fixing.

## Time-tracking periods

Templates with time-tracking variables need a period. Set it with **Time tracking settings** in the ⋯ menu of the template. When someone adds the document, they pick the period if it is required.

## How to check your data

1. Open the template in the editor and choose a user in **As user:**.

2. Turn on **Show sample data** and read every variable.

3. For empty values, fix the profile data, or set **When empty** on the variable.

4. Repeat with a second user whose data is incomplete.

## Best practices

- **Set "When empty" on every optional variable.**
- **Use custom columns for institution-specific data**, and name them clearly.
- **Keep dates in one format** across your documents.
- **Preview with several users**, including one with gaps.
- **Only include data the reader may see.** See data protection in [Smart documents](/docs/fuxam-web/cms/smart-documents).

## Common pitfalls

| Pitfall | How to avoid it |
|---|---|
| Blank value in the output | Fill the profile field or set **When empty**. |
| Variable missing in the list | Check the template's **Object Type**. |
| Wrong date format | Set the **Format** in **Variable settings**. |
| Smart table blocks saving | Choose a valid data source for the table. |
| Time-tracking values empty | Choose the period in **Time tracking settings** or when adding the document. |

## FAQ

**Can I use my own custom columns?**

Yes. Custom columns from [User Management](/docs/fuxam-web/base/user-management/custom-columns) appear as variables for User templates.

**What is the difference between a variable and a form field?**

A variable is filled automatically from data. A form field is an input someone types into when they complete the document.

**Why does the variable list look different between templates?**

The list depends on the **Object Type** of each template.

**Can a form field start with a value?**

Yes. Use **Prefill from variable** on the form field. It is filled when the assignee opens the document, if their draft is empty.

## Related pages

**[Edit a document](/docs/fuxam-web/cms/smart-documents/edit-a-document)**

Insert variables in the editor.

**[Custom columns](/docs/fuxam-web/base/user-management/custom-columns)**

Add your own data fields.

**[Time tracking](/docs/fuxam-web/cms/time-tracking)**

Where time-tracking data comes from.

**[Use a document template](/docs/fuxam-web/cms/smart-documents/use-a-document-template)**

Generate documents.
