For documents with variable information that frequently changes, what you need is a way to generate dynamic content for each recipient and transfer data directly from Full Fabric to the final doc, as that will let you push out hundreds of letters for the effort of one. The solution is using merge fields, and that's what this article is about.

(Pshhh, have you read our introductory article to Letters? If you haven't, check it out here, but if you have, proceed in peace. 🙏 🏳 )

In this article

(click to jump to topic)

What are merge fields and field references?

A merge field is a tag representing a field in Full Fabric that will get replaced with the field’s content when a letter is generated for a profile. The letter itself is composed in Microsoft Word – thus, the latter uses merge fields to map data stored within Full Fabric into your .docx document in order to create personalized documents. Merge fields are inserted inside the MS Word document through Word's Mail Merge feature (after which they take their name).

As for field references, they're the "codes" that represent every mappable field and piece of information in Full Fabric. Some tags are standard (for example, today's date, program name, profile photo, etc.), but the majority owe their existence to a custom schema field and only exist as long as the field does. They're also system-generated. So, for instance, suppose that you open an application template and create the questions Citizenship, I have a dual citizenship and Second citizenship, like so:

Then, for every new question, the system will automatically generate a corresponding "code", although it's not visible on the schema itself. That code is part of the field reference. When you delete a field, the respective tag is rendered useless.

How to export your school’s field references for consultation and understand what they’re for

The first step for generating letter templates is creating a Microsoft Word document that contains mail merge fields named with the appropriate field reference. Full Fabric provides a list of field references for easy searching. To access it:

     1) Click the gear in the top-right corner and then General settings
     2) Open the Documents tab
     3) Press Download field references

You'll get a multi-page file that looks something like this:

The file was designed to be self-explanatory, so every tag has a description. The Description is on the left while the Name of the reference field is on the right. That said, some of the field references in the file are not meant for letters, so please just consider these four sections: GENERAL, PROFILE, PROGRAMME and CLASS.

The category PROFILE consists of the schema-centric fields we previously talked about, and will, therefore, differ for every school (unless they chance to coincide); but the fields under GENERAL, PROGRAMME and CLASS are fixed.

Please notice that every field reference has a prefix identifying the area that it's tied to. Hence, the correct and complete structure is always:

Additional substitution tags

Our team has recently come up with a new batch of merge fields not yet included in the aforementioned file, so we're listing them here. They concern alternate date formats, as the default is "mmmm d, yyyy", and payment plan information.

➜ Specify the language format of date merge fields:

British English: =profile.__dob.long.en_GB (example: 27 July, 1994)

Danish: =profile.__dob.long.da_DK (example: 27. juli 1994)

Dutch: =profile.__dob.long.nl (example: 27 juli 1994)

French: =profile.__dob.long.fr_FR (example: 27 juillet 1994)

German: =profile.__dob.long.de_DE (example: 27. Juli 1994)

Spanish: =profile.__dob.long.es_ES (example: 27 de julio de 1994)

➜ Specify the date format of the current day:

=today_as_ddmmyyyy

=today_as_yyyymmdd

➜ Specify the date format of the class start and end dates:

=class.start_date_as_yyyymmdd

=class.end_date_as_yyyymmdd

=class.start_date_as_ddmmyyyy

=class.end_date_as_ddmmyyyy

➜ Specify the date format of a birth date in the profile Info tab:

=profile.__date_of_birth_as_ddmmyyyy

=profile.__date_of_birth_as_yyyymmdd

➜ Incorporate payment plan data into letters:

=payment_plans

=payment_plans_with_discounts

Some reference fields are identical. How can the system know which value to retrieve?

Good catch, buddy! 👏 If you don't know what we're talking about, it's this:

 The tags under PROGRAMME and CLASS are the same for every program and class:

That's not a problem though, because when you generate a letter for a profile or for a group of profiles, you have to link it to a program, a class and an application template, which is discussed in another article.

What if there are conditions, deadlines, costs or other details in the letter that are mutable?

Whenever a letter contains bits of information that may change over time, you don't have to revise and reupload the Word document whenever an update is due. Instead, you can actually convert the "intel" into custom merge fields. Since merge fields are named after field references, what follows is that you need to create input fields in a special schema called Ask representing the changeable details you wish to divulge in the letter; and as a result, the act of generating a letter will prompt a pop-up window with those same input fields, so that you may fill them with the latest data. To display the information where in the letter you want it, just place the respective merge fields into the .docx document as you normally would.

To access the Ask schema:

     1) Tap the gear in the top-right corner and then General settings
     2) Open the Documents tab, which will land you in the Letter Templates tab
     3) Click the gear next to the desired letter template and then Schema

In the image above, two questions were created: Deadline for paying 1st tuition fee and Amount. You can see their field codes in light grey: __deadline_for_paying_the_1st_tuition_fee and __amount.

Meanwhile, getting back to the field references file, you can now make sense of the following item:

As the prefix indicates, it's related to the Ask schema. So, going by the structure that's given, you just have to replace the word condition with the field code, like so:

ask.__deadline_for_paying_1st_tuition_fee
ask.__amount

Then, when you add the Ask merge fields to your Word document, upload it to Full Fabric and generate a letter, you'll get a pop-up window like this:

The outcome being that the inputted values (15-11-2019 and $1000, in the example above) will replace the tags in the letter. 👍 So convenient, right?!


_________________

PUBLISHED: June 22, 2020
LAST UPDATED: July 6, 2022 at 8:22 p.m.

Did this answer your question?