Document variables and data sources
How Smart Document variables resolve student, program, cohort, date, and institution data when Fuxam fills a PDF template.
A smart document is only as accurate as the data behind each mapped field. This chapter explains conceptually how variables work: what kinds of information you can pull onto a PDF, where that information lives in Fuxam, and how to design mappings so enrollment letters, contracts, and certificates stay trustworthy.
For the click-by-click mapping and generation steps, see Use a document template. For uploading a template, see Create a document.
Why it matters
Registrars and student services are asked for “official” wording that matches what the university records show. When a PDF field points at the wrong data source — or at a custom column that was never filled — the letter looks professional but is factually wrong. Understanding data sources reduces blank fields, mismatched cohort names, and rework during intake peaks.
How it fits
Mapped fields connect Settings → Documents templates to live records in User Management, Study programs and cohorts, Academic structure, and optionally Time tracking.
Key concepts
| Term | Meaning |
|---|---|
| Variable / mapped field | A placeholder on the PDF assigned to a Fuxam data key in the document editor. |
| Data key | The chosen attribute (name, email, custom column, module field, and so on). |
| Object type | Scopes which keys exist: User, Module, Curriculum, Room, or Certificate. |
| Fields count | On the templates table, the number of fields you mapped on the template. |
| Live resolve | At generation, Fuxam reads current values from the record — not from a spreadsheet attached to the PDF. |
Data source groups (User-type templates)
Most institutional letters use User object type. Think in four groups:
1. Student identity and contact
Typical sources include the person’s name, primary email, and contact details maintained on the user profile (including addresses and phone numbers where your institution stores them). These fields answer “who is this document about?”
| Example on the letter | Usually comes from |
|---|---|
| Full name | User profile name |
| User email | |
| Postal address | User address / contact details |
| Phone | User phone / contact details |
Keep identity fields current in User Management before high-volume generation days.
2. Institution-specific attributes (custom columns)
Custom columns (also called user data fields) hold values that are not part of the generic account — matriculation or student ID numbers, external system IDs, scholarship flags, visa categories, and similar. Once defined, those fields appear as mappable keys for User-type templates.
| Example on the letter | Usually comes from |
|---|---|
| Student / matriculation number | Custom column (or ID-type column) |
| Department code or campus flag | Custom column |
| Scholarship or funding marker | Custom column |
3. Program, cohort, and study context
Enrollment confirmations and study contracts usually need academic context: study program name, cohort or intake, curriculum assignment, and related status. That context is maintained through Study programs and cohorts and surfaces on user records used at generation time.
| Example on the letter | Usually comes from |
|---|---|
| Study program name | Program / enrollment context on the user |
| Cohort or intake label | Cohort membership |
| Curriculum reference | Curriculum assignment linked to the program path |
Wrong cohort membership is a common root cause of “correct PDF layout, wrong program title.” Fix enrollment first, then regenerate.
4. Dates and periods
Dates appear in three flavors:
| Kind | Examples | Notes |
|---|---|---|
| Profile or custom dates | Enrollment date stored as a custom column | Resolved like any other custom field |
| Academic / study timeline dates | Term or study-plan dates your institution maintains | Keep timelines accurate for attestations that cite study periods |
| Time-tracking periods | Hours and absences for a selected range | Prompted at generation (or a configured default such as previous month); computed on the server — see Time tracking |
You cannot override computed time-tracking totals from the generation dialog; correct the underlying time entries or choose a different reporting period instead.
Non-user object types
| Object type | Data universe | Typical letter |
|---|---|---|
| Module | Module version metadata from Modules | Module description sheet |
| Curriculum | Curriculum and program structure from Curricula | Curriculum overview |
| Room | Room and location attributes from Rooms | Facility / exam room sheet |
| Certificate | Course-completion certificate fields | Completion certificate — see Study contracts and certificates |
Pick the object type that owns the data. Do not create a User template and expect full module-version catalogs inside it.
How mapping works in practice
Design the PDF with clear empty regions for dynamic text (name, program, dates).
In the document editor, place a field on each region and assign a data key from the list available for that object type.
Optionally add field conditions so sections show or hide based on template rules — keep conditions simple.
Save. Confirm the templates table Fields count matches the placeholders you intended.
Generate for a known test user (or object) and read every filled line against the profile.
Worked examples (guidance)
Enrollment confirmation
Typical mappings: student name, student ID (custom column), program name, cohort, current term or study period, institution letterhead already baked into the PDF background.
Study contract
Typical mappings: identity and address, program and cohort, tuition-related fields when tuition management is enabled, signature or fillable regions for the student. See Study contracts and certificates.
Time summary
Typical mappings: name plus time-tracking period fields. At generation, choose the reporting range (or accept the default). Totals come from tracked entries — not from typing hours into the PDF.
Course-completion certificate
Typical mappings: student name, course or certificate title, issue date. Object type is usually Certificate when that feature is enabled.
Data quality checklist before go-live
| Check | Why it matters |
|---|---|
| Custom columns filled for the pilot cohort | Prevents blank student IDs |
| Cohort membership correct | Prevents wrong program titles |
| Sample users from more than one program | Catches mapping assumptions that only work for one path |
| Time entries complete (if used) | Prevents zero-hour summaries |
| Self-service roles reviewed | Students should only unlock low-risk templates |
Data protection notes
Mapped variables often surface personal data on a downloadable PDF. Prefer:
- Only the fields the letter’s purpose requires
- Generation and download limited to roles with document permissions
- Careful use of self-service for templates that include addresses or ID numbers
- Clear retention practice for files left on the Documents tab
Broader context: Smart documents overview and Permissions and features.
Common pitfalls
| Pitfall | Result | What to do |
|---|---|---|
| Mapping before custom columns exist | Key missing or always empty | Create columns, populate, then map |
| Assuming Word merge fields survive PDF upload | Nothing to bind | Place fields in the Fuxam document editor |
| Mixing object types conceptually | “Why can’t I see module fields?” | Recreate with the correct object type |
| Trusting an old PDF after a data fix | Letter shows stale values | Regenerate after correcting the profile |
FAQ
Can one field show data from two sources?
Each placed field is assigned one data key. If you need a composite line (for example name plus ID), use separate fields on the PDF or maintain a single custom column that already holds the combined value.
Do API data fields and handbook custom columns relate?
Yes in concept: institution-defined user data fields (custom columns) are the same class of attributes staff maintain in User Management and can map onto user-type templates. Keep values accurate in the profile; generation reads what is stored there.
Why did two students get different blanks on the same template?
Mappings are shared; values are per person. One student may lack a custom column value or cohort assignment that another has.