Outlay Functions

The outlay figures behind every expenditure, meaning actuals, forecast and planned budget values, are available to expenditure expressions through the outlay functions. They arrive as ready-made presets: you pick one from the autocomplete, save, and the value appears on every expenditure. Underneath the presets sits one generic function with three parameters, so combinations that are not offered as presets can still be written by hand. This page lists the presets with the exact formula each one inserts, gives the accepted value for every argument, and explains how the time windows resolve.

What are the outlay functions? NEW IN 5.3.5

An outlay function reads the outlay rows behind one expenditure and sums them over a time window. One generic, parameterised function does all of it. Three things vary:

The presets are fixed combinations of those three. They exist so that nobody has to know the parameter model to get a working value.

Which outlay presets are available?

Seven presets, each of the first six in a cash and an accrual variant. The formula column is what the autocomplete inserts into the expression field when you pick the preset.

📌 Note: The two planned presets still pass a scenario argument, and it is always stitched. The argument is required by the function signature, but it selects nothing, because planned outlays carry no actual, forecast or stitched distinction.

Two words carry a fixed meaning across the preset names, so you can read any of them without checking this table:

• Outlook means stitched: actuals up to the forecast date plus forecast from it.

• Forecast always means forecast rows only.

What does the generic function look like?

Every outlay preset except the pending transactions one is a call to the same function. Arguments are separated by semicolons and each value is quoted:

GetOutlays("data";"window";"scenario")
GetOutlays("data";"window";"scenario";"basis")

Pending transactions use a separate function, whose single argument is the basis:

GetPendingTransactions("cash")
GetPendingTransactions("accrual")

💡 Tip: You rarely need to type any of this. Insert the closest preset from the autocomplete and edit the argument you want to change. The syntax above is here so you can read an existing expression, and so you can build a combination that has no preset.

What is the difference between a preset and a function?

The two appear as clearly separated groups in the suggestion list, because they are used differently:

• A preset is a ready-made complete expression. Picking one inserts every parameter already set. There is nothing to fill in, and you can save straight away.

• A function is a building block. You combine it and fill in its parameters yourself.

Any valid combination of outlay data, rows read and time window computes, even when it is not offered as a preset. A year-to-date window over forecast rows is a working expression, for example, although it is not a preset because the resulting number is easy to misread. An invalid combination fails validation with a message naming the problem.

To build a combination that has no preset, insert the closest preset and edit its parameters in the expression field. The parameters of an inserted preset stay editable, and the autocomplete descriptions name each one.

💡 Info: The outlay presets are suggested only when Applicable to request type is set to Expenditure on the property you are editing. On a capex or global property the suggestion list shows the general function library without them.

How do the time windows resolve?

Every time window resolves against the forecast date on the parent capex request, never against today's date.

• The current fiscal year is the fiscal year containing the forecast date. This is the full_year window.

• Year to date runs from that fiscal year's start up to the forecast date. This is the ytd window.

• From the forecast date forward runs from the forecast date to the end of the investment. This is the remaining window.

• Whole investment ignores year boundaries entirely. This is the lifetime window.

📌 Note: Stored values must never depend on the clock, because nothing recalculates simply because time has passed. A value anchored on today's calendar date would go stale silently. The forecast date is therefore the single time cursor of the whole feature. It moves only when a period close advances it, or when someone moves it manually, and both of those recalculate every value that resolves against it.

The boundary rule

The forecast date splits every expenditure's timeline in two. Months before the forecast date are actual territory. Months from the forecast date forward are forecast territory. Every function applies this same boundary, which is what makes a stitched window unambiguous.

Example. The forecast date on a request is 1 May 2026 and the fiscal year runs January to December. On an expenditure in that request:

• YTD actual spend sums actual rows for January to April 2026.

• Remaining forecast sums forecast rows for May 2026 onward.

• Full-year outlook sums actual rows for January to April 2026 plus forecast rows for May to December 2026.

• Full-year budget sums planned rows for January to December 2026.

Cash and accrual variants

Each of the six outlay presets comes in a cash and an accrual variant, listed separately in the autocomplete. Internally these are the same function with a different basis, reading the cash or the accrual outlay data.

An accrual variant is named after its cash counterpart with (accrual) appended, and its formula is the cash formula with a fourth argument added. So YTD actual spend (accrual) inserts:

GetOutlays("post_decision";"ytd";"actual";"accrual")

Pending transactions follow the same idea through their single argument, so the accrual variant is GetPendingTransactions("accrual").

🔧 Configuration: The accrual variants are offered only while the accrual to cash setting is enabled on your installation. With that setting off, the suggestion list shows the cash variants only.

Current period pending transactions

Transaction amounts for the current period that have not yet rolled into actuals were previously invisible on the expenditure grid. This preset sums them, in whichever of the cash or accrual perspectives matches.

It reads transaction records rather than the planned and actual outlay values the other presets use, which is why it has no row selection and no window beyond the current period. That is also why it uses its own function, GetPendingTransactions, with the basis as its only argument.

📌 Note: Only expenditures carrying an external ID can have transactions. An expenditure with no external ID shows blank. One that has an external ID but no pending transactions in the period shows zero.

How do you build a variance or a consumption metric?

Derived metrics need no dedicated feature. They are expressions that combine outlay presets with the ordinary arithmetic and function library, so you write them the same way you write any other calculated property.

Written out, budget variance is:

GetOutlays("post_decision";"lifetime";"actual") - GetOutlays("pre_decision";"lifetime";"stitched")

The two variance metrics above are written so that a positive value means overspend, matching the convention used in the worked examples elsewhere in this documentation. Pick one direction and use it in every variance property, because a column whose sign means different things in different properties is worse than no column.

💡 Tip: Wrap every division in SafeDivide and give it a fallback. An expenditure whose approved amount is zero or empty, which is normal for anything still in pre-decision, would otherwise break the whole column.

When is a value blank, and when is it zero?

• Zero means the function applied, but its window summed nothing.

• Blank means the function does not apply to that expenditure. An actual-outlay function on an expenditure still in pre-decision is blank, as is a delta row with no approved amount, or a pending transactions function on an expenditure with no external ID.

Where do the outlay functions not work?

• On capex and global properties. The outlay functions are parsed on expenditure properties only in this version. An outlay function written into a capex request expression is not calculated. Existing expressions on capex and global properties are unaffected.

• Row selection on planned values. Planned outlays carry no actual, forecast or stitched distinction, which is why pre_decision accepts only stitched. Extending row selection to planned values is a later phase.

• Currencies other than the request currency. All outlay values are computed in the request currency.

Related pages

• Calculated Expenditure Fields: creating the property that holds an outlay expression, and what triggers a recalculation.

• Property Expression Functions: the full function library, including SafeDivide, IfEmpty and Switch.

• Expressions in Properties and Investment Models: expression syntax rules and troubleshooting.

• Expenditures: the outlay data these functions read, and the forecast date.