Pseudo-fields

Pseudo-fields are a special kind of field that you create yourself. You can use these fields to define calculations, complex expressions, text editing functions, date & time calculations etc. They're similar to formulas, but have their own advantages.

Not sure whether you need a formula or a pseudo-field? The difference is explained here.

Concept

Here's how you use pseudo-fields in Smart Flows:

Define a new pseudo-field.
Choose whether it'll be text or a number.
Define its value.
Map the pseudo-field.

In step 3, you can use other fields' values so that your pseudo-field is actually a modification of other fields' values. For instance, you can use a pseudo-field for:

Calculating totals, subtotals and percentages.
Editing names in full caps (JOHN) to make them less shouty (John).
Defining a new constant value for use in your templates.
Creating complex, multi-conditional conditions.

The possibilities are endless as you can combine all fields and all functions the template builder has to offer.

Resultsets

Besides text and number, there's actually a third type of pseudo-field: Resultsets. You can read more about Resultsets here.

Setting up pseudo-fields

Creating a pseudo-field

To create a pseudo-field, follow these steps:

In the data set tab of the pane, select the parent element of the new pseudo-field. The pseudo-field will become a child element of this element:

In the screenshot above, the new pseudo-field will become a child element of product.

Select the Add pseudo-field button:

This opens a window where you can define your pseudo-field:

Give your pseudo-field a display name, which automatically creates an internal name:

Choose whether the pseudo-field should output a number or text. This is important as choosing text will not allow calculations and you will not get the desired result.

The next step is to define your pseudo-field's value as an expression, in the large text box. You can insert functions by clicking the Insert Function button and following the wizard, or you can just type them...

...and you can insert fields' values by clicking Insert Field and choosing the field you wish to insert at the place of the cursor:

Adding another field:

Our expression now calculates the sum of the description and the quantity fields. Obviously, there's a lot more you can do with expression. This page has more information about how to use them.

Once you've validated your expression (you can check whether your expression is valid by clicking the Validate button), select OK to save your pseudo-field.

Now you'll see the new pseudo-field in your data set, in blue as opposed to green:

You can now map this field like a regular field. Once you've mapped it, you can style and format that mapping, also like a regular field.

Editing a pseudo-field

After you've created a pseudo-field, you can still edit it. Follow these steps:

In the data set tab of the pane, select your pseudo-field:

Select the Edit button:

Now the pseudo-field window opens where you can edit your pseudo-field's settings. Make the desired changes and select OK to save them.

What's nice about this 'after-edit' is that you can map your field multiple times and then change the value for all those fields at once. This is a major difference with formulas - the differences are explained here.

Removing a pseudo-field

If you no longer require your pseudo-field, you can remove it by following these steps:

In the data set tab of the pane, select your pseudo-field:

Select the Remove button:

Confirm the removal.

Your pseudo-field is now gone.

Context-aware pseudo-fields

When creating a pseudo-field, there is a setting called Context-aware:

Enabling this will make the pseudo-field context-aware, which means that its value is calculated each time it is used, within a certain context, instead of just once at document generation time. The typical example of this is calculating subtotals in groups. To illustrate this, take a look at the following example:

We have a very simple data set, with multiple products that each have a name, price and type. We've put them in a table like this, with a loop over the products on the second row to show all of them.

Note: that we've added a total pseudo-field, that is simply the sum of all the price fields. We end up with this:

The calculation is correct, which is great. Now let's put a group around that according to the type of the product so that we end up with 3 tables.

And here's the result:

The totals are wrong - because the total pseudo-field was NOT set to be context-aware. Its value is calculated once, before the grouping is applied. So, check the context-aware box...

...and you'll notice the result coming out correctly:

Great! So, whenever you want to use groups and calculations, you should make the pseudo-field context-aware. There may be other scenarios where context-aware is the desired setting, so give it a try if your pseudo-field does not produce the expected result.

Common pseudo-field uses

Since you define pseudo-fields yourself, you decide how to use them. But there are some uses that we encounter more often:

Calculations on recurring elements

You can use pseudo-fields to perform calculations on recurring elements by defining a single (recurring) element as the only argument of certain functions.

For instance:

sum(${/warehouse/product/quantity}) will return the sum of all the quantity fields in the data set.
avg(${/warehouse/product/quantity}) will return the average of all the quantity fields in the data set.
max(${/warehouse/product/quantity}) will return the maximum of all the quantity fields in the data set.

This feature is often used on quotes or invoices, where a total price (sum of all the prices of all the products) has to be calculated.

Nested pseudo-fields

You can use pseudo-fields in other pseudo-fields, allowing you to set up a tree structure. The following example explains this:

You want to make an invoice. Your data set contains a recurring element Product, which has the fields Unit price and Quantity.
You set up pseudo-field A under Product (so each product has its own pseudo-field A) that calculates Unit price * Quantity (unit price multiplied by quantity).
You set up pseudo-field B on the same level as Product (so there is only one pseudo-field B) that calculates sum(pseudo-field A).

Now you can use pseudo-field A in a loop over Product, to show each product's subtotal. Then, outside of the loop, you can map pseudo-field B to show the full total.

Concatenation

You can use the concat() function to put text fields together, so that you only have to map the pseudo-field instead of having to map the fields separately. For instance, you can put the FirstName and LastName fields together.

This also saves time on formatting, as you only have to format one mapping.

Understanding the Key Differences Between Formulas and Pseudo-Fields in Template Builder

The Template builder add-in gives you the possibility of using calculations/text editing functions in your templates. There are 2 ways of doing this:

By using a Formula
By using a Pseudo-field

Both these features allow the same calculations, but there are a few differences that you should know about.

Properties

Formulas are intended to provide a fast means for calculating something. They offer the same powerful expressions and functions as pseudo-fields, but they are a bit easier to insert. Pseudo-fields, on the other hand, are newly created fields in your data set, which can then be referred to later on. Setting them up takes a bit longer than setting up a formula, but because you define a field, you can use that in other calculations, or use it multiple times in your template.

Advantages

Formulas are fast to set up.
You can map pseudo-fields in different places in your document.
You can sort your loops on pseudo-fields that are defined in that loop.
You can refer to previously created pseudo-fields in further calculations.

Especially the last bit here is important: being able to refer to previously created pseudo-fields allows chain calculations, such as the following example:

Use multiple pseudo-fields to calculate multiple subtotals,
Calculate the sum of all those pseudo-fields in a new pseudo-field,
Subtract a customer discount from that sum and show it as the grand total by using another pseudo-field.

This is just one example that shows why pseudo-fields are useful, since you can't do this with formulas without defining the same calculations multiple times.

Suggested use

Use formulas when you only require one calculation that you won't need anywhere else - be it in your template or further calculations.
Use pseudo-fields when you want to re-use the calculated value in further calculations or when you want to use the calculated value in multiple places in your document.

How to use them

Inserting a formula

Place your cursor where you want to insert the formula,
Select the formula button in the ribbon,
Type in your expression or use the expression wizard,
Set your formula's formatting,
Select OK to finalize everything.

Inserting a pseudo-field

In the pane's data set tab, select the pseudo-field's parent field (the pseudo-field will be created as a child element of this field),
Select the Add pseudo-field button in the pane's data set tab,
Set your pseudo-field's settings, such as the name, the type and most importantly: the calculations,
Select OK. A new field has now been created under the selected parent field,
Place your cursor where you want to insert the pseudo-field,
Double-click the field in the pane's data set tab to insert the field in your template.

Editing a formula

In the pane's mapping tab, double-click the formula you want to edit. A window will pop up,
In this window, in the Field Selection section, hover over the value and select the pencil that appears,
This opens the expression editor where you can change your formula.

Editing a pseudo-field

In the pane's data set tab, select the pseudo-field you want to edit,
Select the Edit pseudo-field button in the pane's data set tab,
This opens the pseudo-field window which includes the expression editor where you can change your formula.