1. Metrics
  2. Total Summer

Metrics

Total Summer

Keeps a running total in stub.metrics by adding or subtracting a value from stub.data each time an action runs. Useful for totals, balances, quantities, scores, and financial rollups.

Basic usage

Each time the action runs, add the value of stub.data.order_total to stub.metrics.counters.lifetime_order_value.

loading...

If stub.data.order_total is 25 on the first run and 10 on the second, the stub ends up with:

loading...

Metrics run at the end of the action, after fields have been merged and tasks have run. The value in stub.data therefore includes anything this action collected or saved.

Parameters

metrictype
required
string

Must be total_summer.


params
required
object

The parameters for the metric.

Show child attributes
fieldname
required
string

The name of the metric in stub.metrics. The running total is stored at stub.metrics.<category>.<fieldname>.
Dots create nested objects, so orders.value is stored at stub.metrics.counters.orders.value.


value_field
required
string

The key in stub.data that holds the number to add or subtract, e.g. order_total reads stub.data.order_total.
This is a top-level key only. Dot paths such as order.total are not resolved.


operator
optional
string

The arithmetic to perform.

Options: addition subtraction

Default: addition


default_amount
optional
number

The starting total, used only when the metric does not exist on the stub yet.

Default: 0


category
optional
string

Groups the metric under stub.metrics.

Default: counters

WARNING

Make sure the value in stub.data is stored as a number. Values that arrive as text, such as "10", are joined onto the total as strings instead of being added. A missing value produces NaN.
Use the Save Data task with "datatype": "number" to convert the value first.

NOTE

The existing total is converted to a whole number before each calculation, so decimal amounts lose their fractional part on the next run. For example, adding 2.5 twice gives 4.5, not 5. If you need decimals, store amounts in the smallest unit (for example, cents).

INFO

amount_field_name is the deprecated name for value_field and still works. Use value_field in new templates.

Examples

Decrease a balance

Start a stub's credit balance at 100 and subtract stub.data.credits_used each time the action runs.

loading...

If stub.data.credits_used is 30, the result is stub.metrics.balances.credits_remaining: 70.


Only add when a condition is met

Metrics support conditions. This adds the refund amount only when a refund was approved.

loading...