Understanding Action Variables

 

---

Actions are a powerful and flexible way to transfer information outside of Allocadia. The following example is an email that would be triggered by the user when a Budget Item is ready for approval from an outside department, typically finance. 

This example uses variables from 3 different parts of Allocadia:

• User Details: 
  • The user who triggered the action is accessed through                                                             ${ user.firstName } and ${ user.lastName } 
• Activity Plan Details :
  • The Activity Plan (budget) name is accessed through ${ budget.name } 
  • Additionally, the Allocadia ID (budget ID) is used to create a link back to the item in Allocadia with ${ budget.id } 

• Item Details
• Items are Line Items, Placeholders, Categories and Sub-categories. The details of those items (aka. Item Details) make up most of the variables used within an action, for example ${ item.fyPlan } . Above, several different item variables are used in creating the email.

FORMATTING

The example above makes use of variable formatting for the "Payment Due By" field. In Allocadia this field is a date but the action needs to know the right way to format it for the email.

To format the date, it is passes through 2 filters. Filters process from left to right, with the result of each filter used by the next one.

In this case, the first filter ? date tells the action to only include the day details in the output and exclude the time.

The second filter ? string.full tells the action to format the date using a predefined 'full' format. In this case, the date would appear like "Friday, October 24, 2014" See the formatting section of the document for more details and other advanced formatting options.

VARIABLE GROUPS

The variables for an action are grouped into sections to make finding them easier as well as to indicate how they should be accessed from within an action template.

Budget - General

Contains variables describing the budget that the action is being executed for, including the name and currency.

Access these variables using the "budget" prefix. For example: 

${ budget. name }

Budget - Terms

Contains variables for the custom terminology of the budget the action is being executed for. This can be helpful if you have action templates that you may copy between budget hierarchies that have different terminology. 

Access these variables using the "budget.terms" prefix. For example:

${ budget.terms.lineItem }

Budget - Panels

Contains variables from both the Roll-up panel and the Budget panel for the Budget that the action is being executed for.

Access these variables using the "budget" prefix. For example: 

${ budget.q1FinanceTarget }

Item - General

Contains general variables about the item the action is being executed for. 

Access these variables using the "item" prefix. For example:

${ item.name }

Item - Details

Contains variables from the Details panel of the item the action is being executed for.

Access these variables using the "item" prefix. For example:

${ item.objective } 

Item - Grid

Contains variables from the Grid for the item the action is being executed for. The variable does not have to be visible on the users current view to be accessible, it only needs to be a grid column.

Accessing these variables using the "item" prefix. For example:

${ item.janPlan }

Totals at the budget level for variables in this category can be accessed using the "budget" prefix. For example:

${ budget. janPlan }

Item - Actuals

Contains variables from the Actuals panel for the item the action is being executed for.

Access to those variables requires a loop to access each of the Actuals for the item. For example:

<#list item.actuals as actual>

${ actual.amount }

${ actual. accountCode }

</#list>

Item - PO

Contains variables from the PO grid for the item the action is being executed for. 

Access to those variables requires a loop to access each of the POs for the item. For example:

<#list item.pos as po>

${ po.poNumber }

${ po.poAmount }

</#list>

User

Contains variables from the user that is executing the action. 

Access these variables using the "user" prefix. For example:

${ user.firstName }

Other

Contains variables that are unrelated to any other categories.

Access these variables directly. For example:

${ now }

Raw Variables

When accessing variables, the system will automatically format the variable for readable output. This means that, especially for numbers, the value may have extra characters that downstream systems can't handle.

For example ${ item.janPlan } might output $1,203,454.23. If the system you want to send the data to cannot handle the commas and the dollar sign, you can use raw variable values.

To use raw variable values, simply append "Raw" to the variable name. Following the previous example, ${ item.janPlanRaw } will output 1203454.23.

Multi-select Variables

For variables that can contain multiple choices (usually on the Details panel), the individual choices can be accessed either formatted or directly.

For example, this snippet will output all of the choices as a comma separated list:

${ item.multiChoiceVariable }

To access the same variable choices directly, the following structure can be used to output each choice:

<#list item.multiChoiceVariableRaw as multiselect>

${ multiselect.choice } ${ multiselect.percentage }

</#list>

Variable Information

In addition to the values for each variable, you can also access details about the variable itself.

The following information is available about each variable:

• columnId
• The ID for the related column that this data comes from. This is available for Grid, Details, Actuals and PO variables.
• name
• The display name for the variable.
• fromDate
• If the variable has a related column, this is the fromDate for that column as defined in column settings.
• toDate
• If the variable has a related column, this is the toDate for that column as defined in column settings.

Access these variables through the "variables" prefix. For example:

${ variables.janPlan.name }

Conditional

To output a section of a template based on the existence of a variable value, you can use the "if" statement. For example, the following section will be output only if "someVariable" has a value:

<#if (item.someVariable ?? )>

... Only shown if "someVariable" has a value

</#if>

ADVANCED FORMATTING

Many more formatting options are available by using the extensive library provided by the FreeMarker template engine. The FreeMarker manual is available at freemarker.org.

If you would like more information on action variables and FreeMarker formatting please read the following article: FreeMarker Template at a Glance