When generating Word or PDF documents from Salesforce data, the most common need is to generate one or more documents from a single template, replacing the place-holders
in the template with data from Salesforce. This would apply, for instance, when generating an invoice, a proposal or a thank-you letter. Apsona's document generator
provides full support for this case, as documented elsewhere
But there are cases where you would want to use multiple input templates, and have the system select the one to use based upon the data being used to
generate the document. For example, suppose you wish to generate acknowledgement letters for the contacts who participated in your school fundraiser, but the template varies depending
on whether the contact is a parent, a student, a faculty member or a member of the school board. You would still want to generate (in one batch) the letters for all the
participants, but you would want the system to select the appropriate letter style and content, depending on the type of contact.
Here are a couple of approaches to address this situation.
Approach 1: multiple conditionals
If you had a common header and footer for all the different letter types, and you just want to vary the body of the letter depending on the contact, you could create a
single template that conditionally generates the appropriate letter body depending on the contact type. You can use Apsona's IF-THEN directives
for this purpose, via a
large IF-THEN-ELSE structure that checks the letter type. Below is a depiction of such a template.
Approach 2: conditional templates
For the more sophisticated cases, Apsona supports for "conditional templates" - one or more additional templates, along with the criterion to use when selecting
each of those templates. The panel in the right part of the screen shot below shows the fields you need to specify when using conditional templates.
Specifically, you provide:
- The "condition field" - a source data field whose value will determine the template to use. In the above example, the condition field might be the Contact Type
field. If you're merging directly from an object, this field is one of the object's fields. If you're merging from a report, this field is one of the report's fields.
- A list of values and associated templates, so that for each source record whose condition field has one of these values, the corresponding template will be used to
generate the document.
In the screen shot above, we have selected the Record type field as the condition field, so that field's value is used to select the template.
Therefore, the template selection logic will be applied for each data record being used for the merge, as follows:
- If the Record type is
Board Member, or
Parent, the template used will be
Thanks for attending -
Thanks for attending - Board Member or
Thanks for attending - Parent, respectively.
- If the Record type is not any of the above, the template used will be
Thanks for attending the fundraiser, which is specified in the "Document template
to use" selector. We call this the "default template" since the logic falls back to this template if the record's field doesn't match any of the specified data values.
When you have many conditions
The screen space for working with conditional templates is limited, in that it shows about five rows at a time. And this is inadequate when you have lots
of different conditions. In these cases, you can use the pop-out icon in the conditional templates panel so that it uses more screen space. See the
Notes on Approach 2
- The list of fields in the "Condition field" selector includes only text and picklist fields; other field types are not supported.
- Sometimes you'd want to "bucket" your data records in your report, or otherwise determine the template for each record based on a calculation on the fields of the
record. For such needs, you can create an Apsona report containing a calculated column whose value determines the template, and use this field
as the condition field.
- If you choose "separate files" for the Output structure (see screen shot above), you can set the header and footer of each output file separately, i.e., whatever
headers and footers are set in the specific conditional template will be used for the record generated by the template. (E.g., you can have separate header and footer
styles for each type of attendee, in the above example.) But if you use either "page breaks" or "paragraph breaks," the generated output will use the default template's
header and footer across all the generated pages.
- Along the same lines, if you choose a single file for output, either with paragraph breaks or page breaks, the document generator will try to use the styles in the
default template to apply to the entire document. So in this case, if your conditional templates include images or additional styling beyond what's in the default
template, Microsoft Word may fail to open the file, and produce a popup error such as the one below, asking whether to recover the content of the document.
The workarounds are:
- use Approach 1 described above, so that you use just one template file for all your documents; or
- use "separate files" as the output structure when producing multiple documents; or
- allow Word to recover the content and save the result.