Often times you need to edit the contents of a template based on information from the record. Or you may want to choose a whole other template all together, based on information from the record. Apsona provides three different ways to accomplish this, each with pros, cons, and ideal use cases.
Option 1: Use our Conditional Template feature. Use this feature when you want to set up different templates, and have Apsona choose the right one based on a field value. This is the least technically complex method. You just need to include a single field in your data source that will be the "decision-making" field. If field is X, choose Template A, if field is Y, choose Template B, and so on. This method works best with "multiple file outputs"
- Pros:
- It's a simple and user-friendly way to set up a dynamic merge process.
- It allows your templates to remain simple, not requiring IF/THEN statements to be embedded in the templates themselves
- Cons:
- You need to use only 1 field to make your template choice. If you require complex logic to choose a template this method may not work. But we do have a workaround that we'll explain in option 3.
- If you use this method with 'single file output', and your various templates have very different formatting from each other, you may get inconsistent results and the formatting may change unexpectedly. This is because Word is trying to take potentially conflicting page layouts and formatting, and combining them into one output.
Option 2: Add IF/THEN statements to the template itself. Use this method when you want to make small changes to text within a single template. If field A has Value Y, include this paragraph, image, table, etc. Otherwise don't.
- Pros:
- This method allows you to avoid creating and managing multiple templates
- You can create a cascading statement to cover multiple conditions. For example you can say, if Field A is value Y then show Text 1, Else If Field A is Value X then show Text 2, Else If ...
- Cons:
- These IF/Then statements must be created as merge fields and require a specific syntax and structure. Our documentation lays out the method, but small typos or misteps in the creation can lead to errors.
- IF/Then statements can not include AND logic or OR logic so they may not meet the complex logic needs you have for your use case.
Option 3: Use Apsona's Calculated fields in your data source. This is our most recommended method due to its flexibility of use. Click here to learn how to add calculated fields to an Apsona Single Step report. Click here to learn how to add them to a Multi-step report. Click here for a deep dive into how Calculated fields work and what options you have with them.
Calculated fields are essentially javascript-based formula fields. They are built directly in our reporting tool so that you don't have to clog up your object with one more formula. If you want to dynamically choose a template, as in Option 1, but you need to use more complex logic to choose the right template, you can insert a calculated field and add as much logic as you need to provide that single 'decisioin-making' value to choose the right template with our Conditional Templates feature. If you want to dynamically display alternative text within a single template, as in Option 2, you can add both the logic and the resulting text within the Calculated field. This will display the actual resulting text in the report itself. In your template, you can avoid the complexity of building If/Then statements, and simply merge those calculated fields directly.
- Pros:
- Because these are javascript-based, Calculated fields are the most flexible option, allowing you to use as much complex decision-making logic as you need.
- You can see the resulting text before you run your merge. This helps to troubleshoot issues without having to run the merge and scour through the results
- Cons:
- Calculated fields are only availabe in Apsona reports so if your merge action is based on an object (ie: ran from the Tools menu) you can't utilize calculated fields
- Since Calculated fields are based on Javascript, they are extremely powerful and flexible, but you may have to spend some time researching how to write the javascript statements so that they work correctly. We have great documentation linked above, and you can search the internet for javascript support, but if javascript is new to you, this approach may take a bit longer to build and test.