Document variables and data sources
How variables, smart tables, formats, and empty-value rules fill a Smart Document with student, program, cohort, time-tracking, and institution data.
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.
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 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) |
| Admission | Application data |
| Tuition | Tuition and fee data |
| Signature | Signature blocks |
| Time tracking | Values for a time-tracking period (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
Open the template in the editor and choose a user in As user:.
Turn on Show sample data and read every variable.
For empty values, fix the profile data, or set When empty on the variable.
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.
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 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.