Using multiple templates for document generation

Overview #

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. Supported fields have either a string or a picklist data type. 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 FacultyBoard Member, or Parent, the template used will be Thanks for attending - FacultyThanks 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.

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. In particular, text area and description fields 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.

Powered by BetterDocs