Background #
This document assumes that you are familiar with the functionality of the Apsona Document Generator.
Overview #
A common use case for document generation is to produce a .docx or .pdf file containing a simple list, such as a contact list, a staff directory or an event list. Below is an example screen shot of a staff directory.
Some more examples:
- Contact lists: You might need a list of your contacts in the New York area, with their names, email addresses and phone numbers, because you’re visiting New York and you want to meet with them.
- Upcoming events: You want to produce a list of upcoming events to send to the members of your church or religious congregation.
- Board members: You need a list of the officers on each one of your advisory boards, along with their titles, interests and contact information.
In each of these cases, you would probably want your document template to contain a header area describing the content (e.g., “Contacts in New York” or “Church Events September 2016”) and a list area that contains the actual rows of data.
Notice that we want part of the text in the header area to be dynamically generated. For example the text “New York” must be replaced by whatever city you want to visit, and the “September 2016” must really be the month for which you’re producing the event list. But as for the list itself, you would want data from any old generic report. In the context of the Apsona document generator, this means that there cannot be any sort of linkage or lookup relationship between the data in the list and the data in the header.
Procedure #
To create such a document, you would perform the following steps.
- Create a “detail report” that produces the list of rows to be merged into the document as your data, e.g., your list of contacts or events. You can create multiple reports and merge them all into one document.
- Create a “header report” that produces just one row, to use as generator for your document’s header. To ensure that it generates just one row, set its record range to “1 to 1”, as in the screen shot below. See the screen shot below.
- Create and run a new merge action from the report or single record of step 2 above. In this merge action, use the detail reports of step 1 above as data source for the sublist, and make sure that the “None” choice is selected for every linkage option.
As an example, below are screen shots of a template and the resulting document.
If you like, you can download the Apsona Item package for example merge action that produces this list. This package contains the two reports, the document template and the merge action illustrating the idea. You can import this item into your org as described elsewhere.
How this works #
To cater to such a situation, Apsona’s document generator recognizes the following special case. Ordinarily, as discussed elsewhere, the document generator requires a valid linkage between the “top-level” data and the “sub-list” data. Such a linkage ensures that a sub-list contains only the data valid for a particular top-level record. But we cannot provide a valid linkage in a situation where we simply want a report to be merged, unconstrained, into a sublist. So Apsona’s code makes a special case if all these conditions hold:
- the data source for the top-level records produces either no records or just one record;
- every sub-list’s data source is marked with a linkage of “None”; and
- every sub-list is produced by either a report or a multi-step report, i.e., none of the sub-lists uses a raw Salesforce object as data source. (This last constraint ensures that you will have applied a suitable filter in your report to whittle down the data to show in the generated document.)
Under these conditions, the document generator simply merges all the data records from the sublist reports into the document, without considering the linkages, based on the assumption that the sublist reports will enforce any necessary filter criteria for the list.
