Calculated merge fields allow you to use a scripting language (PHP) to perform calculations. Creating calculated merge fields is an advanced topic and requires a some understanding of computer programming and in particular PHP.  However it is fairly easy to create simple calculations by performing simple math on variables. 

A calculated merge field is typically used when you need to add a new field to a document that is based on a calculation of existing fields. For example if you have designed a workflow for a property settlement you may need to calculate the rates apportionment on settlement day by dividing the amount already paid by how many days the new buyer will benefit from those rates after settlement day.  This amount usually gets added to the final amount payable at settlement.  This is easily achieved with a calculated merge field.

Creating a new calculated merge field

From the top navigation bar go to Admin / "Document Templates" / "List of Merge Fields". This will show a list of all available merge fields in the system.  

Click the "Add Calculated Field" button above the list to create a new calculated merge field.

Testing your merge field

Calculated merge field will inherit the environment in which they run. So for example if they are placed in an action they will have access to the attributes of the action (action ID, action name, participants, custom data, etc). If they are used in an accounting invoice template then they will have access to the invoice details (line items, tax, totals, invoice number, etc).

You can test you merge field by selecting an action ID or sale/purchase ID (invoice) to run it against.

Once you have selected and action or invoice to test against you can click on "View Available Variables + Data" to see a PHP dump of the variable names and the data they contain.  If you are not used to PHP then this will look scary, but it really isn't that bad (see examples below on how to use this output).

Linking your merge field to document templates

Once you have created a calculated merge field you can use it in any document template just like any regular merge fields.  However if you plan to share you template with others by publishing it to the Actionstep App Store or making a private app then you will need to tell Actionstep which document templates contain your calculated merge fields.  This way Actionstep knows to package up your merge fields along with each template.  In the "Linked Document Template" section at the bottom of the calculated merge field form you can add a row for each template you want to link your merge field to.

Examples

Echo some text

This is not particularly useful but it gives you an opportunity to see how to set the output from your calculation. Use the "echo" command followed by some text or variable name and terminated by a semi-colon to set the output from your calculation.  Whatever you output will be inserted into documents where this merge field if used.  Here we simply insert the text "Hello world" into the document.  Click the "Run Test" button to see the output.

echo "Hello world";

Add line breaks

The new line separator is "\n" (backslash followed by "n").

Try this and then click "Run Test":

echo "Hello world";
echo "The world says hello back";

The output should look something like "Hello worldThe world says hello back".  Probably not what you intended. Add a new line either after the first phrase or at the beginning of the second phrase:

echo "Hello world\n";
echo "The world says hello back";

Run the test again and now the output will be on two lines - much better!

Some simple maths

Let's add 1 to the action ID to display the next action ID.  [[Action_ID]] is a standard merge field so it can be refereneced in the calculation by using it inside single quotes as follows:

echo "Current action id = " . '[[Action_ID]]' . "\n";
$next_action_id = '[[Action_ID]] ' + 1;
echo "Next action id = " .  $next_action_id;

Run a test. The output should look something like

Current action id = 25
Next action id = 26

Working with dates

Dates are stored in a universal notation in the database so you will need to use date functions to convert these to numbers before you can perform calculations on them, and then you will need to convert them back to strings to display them.  The online PHP manual has lots of good information on date functions.

In this example let's say we have a property transaction action type in which we have created some custom data elements to capture details of the settlement. You want to produce a document that includes a calculation of how many days are left until settlement. To see the available custom data variables click on "View Available Variables + Data". In this example there is a custom data field represented by the array variable name $conv_settlement_data. The first element of the array contains the value 2014-10-15 00:00:00 which is the settlement date for the action ID we have choses to test with.

...
   [$conv_settlement_interest_rate] => Array
        (
            [1] => 0
        )

    [$conv_settlement_settlement_date] => Array
        (
            [1] => 2014-10-15 00:00:00
        )
...

You could simply output the contents of this variable as follows

echo $conv_settlement_settlement_date[1];

To calculate the days between today and the settlement date we use the date_create() function to get today's date and then perform some date functions as follows:

$today = date_create();
$settlement = date_create($conv_settlement_settlement_date[1]);
$interval = date_diff($settlement, $today);
echo "There are " .  $interval->format('%d') . " day(s) left until settlement";

Working with custom data fields

As you saw in the previous examples you can use custom data fields in your expressions. To make this even easier we have create two special variable names which vive you direct access to single-row and multi-row data collection fields.

Accessing single-row data fields

$singleRowData['data-collection-name']['data-field-name']

Accessing multi-row data fields

$multiRowData['data-collection-name'][0…n]['data-field-name']