Overview #
This article assumes that you are familiar with the Apsona Document Generator.
There are occasions where multiple documents need to be generated, with minor variations, and the variations are based on data that isn’t in your Salesforce org, but rather is specified at the time of document generation. Here are two common examples:
- Text replacement: You want some custom text for the caption of your document – text that you provide, that isn’t available in your Salesforce database. And you want to change that caption each time you run a document generation action.
- Sublist filtering: You want to generate a document for an Account with its sublist of Opportunities, and you need to change the filter condition for the sublist – e.g., to limit them to those with a certain minimum amount you need – when you generate your documents. But you don’t want to have to modify either the merge action or the sublist report each time you generate them.
The Document Generator’s Run Parameters feature caters to these two situations. In the above examples, you might set up a run parameter named Report Caption, of type text, or one named Minimum Amount, of type currency. You can then provide values for the run parameters each time you run the merge action, and the Document Generator will take care of the rest.
Setting values for run parameters #
Right before you run a merge action, you can set a value for each of its run parameters.
- If you invoke the merge action through a button in a Salesforce page, the run parameters and corresponding data value boxes are available within the button’s popup.
- If you invoke the Merge/Mail popup to run a merge action, the run parameters will be available in the right part of step 1 of the wizard, as in the screen shot below. Notice the Run parameters panel on the right side.
- If you edit the merge action and step through it, you can set the values for run parameters in the last step, as in the screen shot below. Notice the Run parameters panel at the bottom. (To set the default value of a run parameter, you must use step 2 as described in the next section.)
Creating and managing run parameters #
The list of run parameters is available in step 2 of the merge action builder.
- To create a new run parameter, click the Add button, and in the resulting popup, provide the name and data type you want for it.
- You can optionally provide a pre-fill value. If you do, that value will be pre-filled into the data value box when the user runs the merge action.
- You can also provide an optional help text, which will show as a tooltip on the parameter when the user runs the merge action.
- To remove an existing run parameter, simply click the remove button that appears at the left when you hover over the run parameter.
See the animation below. Click the image to rerun the animation.
Mapping and filtering #
Once you have created a run parameter in step 2, it becomes available in a couple of places in step 3 (where you match your template’s fields with the available data fields):
- You can use it to map to any of your top-level merge fields, using the Run parameters section of the list of fields. This lets you map any of your top-level fields to a run parameter, and the user-specified value of that parameter will replace the merge field in the output document or email.
- You can use it to filter any sublist, via the Run Parameters tab in the sublist panel, as in the screen shot below. Note that the Run Parameters tab will appear only if you have specified at least one Run Parameter in step 2, i.e., merge actions without run parameters will not show this tab.
