> For the complete documentation index, see [llms.txt](https://help.allwage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.allwage.com/modules/time-and-attendance/custom-metrics.md).

# Custom Metrics

What custom metrics are, how to create one from conditions, measurements and formulas, custom aggregations for weekly or period totals, how they change payroll but not the Employee Overview's daily ho

A custom metric is a value AllWage works out for each employee from their time and attendance data, using rules set up for your business. For example, a metric can count hours worked on Sundays only, or hours on one activity on public holidays. Custom metrics are used in two places:

* **Payroll:** a [pay run template](https://help.allwage.com/modules/payroll/payrun-templates.md#link-a-metric-or-quantity) linked to the metric pays or deducts its value.
* **Reports:** you can show the metric's totals on the [Employee Overview](https://help.allwage.com/modules/time-and-attendance/reports/employee-overview.md) report or export its values (see [Export custom metric values](#export-custom-metric-values)).

AllWage also has **standard metrics** that every profile gets, such as weekday overtime and Saturday hours. [From daily hours to period totals](https://help.allwage.com/modules/time-and-attendance/how-hours-are-calculated.md#from-daily-hours-to-period-totals) lists what they count. Create a custom metric when no standard metric counts the hours the way your contracts need.

## Who sets up custom metrics

Custom metrics are managed on [**Manage > Custom metrics**](https://app.allwage.com/#/employees/custom-metrics). Users whose permissions include **Custom metrics** with write access can add, edit, duplicate and delete metrics, and **Custom aggregations** with write access does the same for aggregations. Owners and administrators have both by default. Other users with read access can view them.

AllWage support can also build a metric for you or change an existing one. [Contact support](https://help.allwage.com/fundamentals/support-channels.md) and describe what the metric must count, on which days, and which pay run template should use it.

{% hint style="warning" %}
**Changing a metric changes payroll.** Every pay run template linked to the metric uses the new rules in pay runs that aren't finalised yet.
{% endhint %}

To edit or delete a metric that is linked to a pay run template, you also need full payroll access. Without it, AllWage shows "Custom metric '…' is linked to pay run template(s): …. Full payroll access is required to modify it."

## Custom metrics don't change the Employee Overview's daily hours

A custom metric is calculated from the clocks and records on the Employee Overview. It never changes them. So when a pay run template uses a custom metric, the payslip can show a different number from the daily hours on the report, and both are correct.

**Example:** a business deducts a 1-hour break from weekend shifts with a custom metric, and its weekend earning template is linked to that metric. An employee clocks 9.5 hours on a Saturday. The Employee Overview shows 9.5 hours for the day. The payslip pays 8.5 hours, because the template reads the metric, which subtracts the break.

If payroll and the report don't agree, check which metrics the employee's earning templates link to on **Payroll > Pay run templates**. To see the metric's own totals next to the report, click **Manage metrics** on the Employee Overview and choose **Select by tags** or **Custom view**: see [Choose which totals you see](https://help.allwage.com/modules/time-and-attendance/reports/employee-overview.md#choose-which-totals-you-see). For a step-by-step check, see [A custom metric shows a value you did not expect](https://help.allwage.com/modules/time-and-attendance/troubleshooting-hours.md#a-custom-metric-shows-a-value-you-did-not-expect).

## How a custom metric works

AllWage works out an employee's hours one day at a time (see [How hours are calculated](https://help.allwage.com/modules/time-and-attendance/how-hours-are-calculated.md)). A custom metric then does three things with those days:

1. **Conditions choose the days.** For each day in the period, AllWage checks the metric's conditions, such as "the day is a Sunday" or "the day is a public holiday". A day that doesn't match adds 0.
2. **A measurement takes a number from each matching day**, such as the day's total hours or overtime. Instead of a measurement, a metric can use a formula.
3. **The numbers are added up for the period.** The period is the date range of the report, or the pay run's period when a pay run template uses the metric.

Days outside an employee's active period always add 0.

**Example:** a metric has the conditions **Day of the week** **Is in** Saturday and **Public holiday** **Is** **False**, and measures **Total hours**. In a fortnight an employee works 6 hours on the first Saturday and 5 hours on the second, which is a public holiday. The metric's value is 6: the second Saturday doesn't match.

## Create a custom metric

1. Navigate to [**Manage > Custom metrics**](https://app.allwage.com/#/employees/custom-metrics) and click **Add a metric**. The **Configure Metric** panel opens.
2. Enter a **Metric name**. The name must be different from every other custom metric on your profile. It is the column heading in exports, so name it after what it pays, for example "Sunday hours".
3. Optionally click **Add a description (Optional)** and describe the pay rule the metric is for, and add tags under **Link tags (Optional)**. Tags let you find and export the metric with others like it.
4. Under **Set up filter conditions**, click **Add timeline conditions**. A picker opens with the groups of fields on the left, such as **Calendar & Day Context** and **Leave**. Choose a group, then click the **+** next to a field to add it as a condition. Clicking a field's name shows its description first. Then set how to compare it and the value. See [Conditions](#conditions).
5. The condition appears in a group marked **And**. To add another condition that the day must also match, click the **+** at the top of that group. To add a second group marked **Or**, click **Add OR condition group**. See [Combining conditions with And and Or](#combining-conditions-with-and-and-or) before you use an **Or** group: it narrows the metric, it does not widen it.
6. Click **Add measurement conditions** and choose what to add up on each matching day, from the same picker. See [Measurements](#measurements). To calculate the number instead, choose the **Expression** group at the bottom of the picker and see [Formulas](#formulas).
7. Click **Add**. AllWage shows "New metric created" and the metric appears in the list.

To start from an existing metric, click **Duplicate** in its row menu. AllWage creates a copy named "… (Copy)" that you can edit. Aggregations can be duplicated in the same way.

A new metric does nothing until you use it. [Check it](#check-a-metric-before-you-pay-from-it) first, then link it to a pay run template: see [Link a metric or quantity](https://help.allwage.com/modules/payroll/payrun-templates.md#link-a-metric-or-quantity).

## Conditions

A condition has a field, a comparison and a value. The fields are grouped in the picker:

| Group                      | Fields you can use as conditions                                                                                                                     |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Calendar & Day Context** | **Day of the week**, **Public holiday**, **Optional day**, **Extended day**, **Night shift**, **Daily target reached**, **Missing clock template**   |
| **Presence & Employment**  | **Absent**, **Present**, **Present (T\&A only)**, **Clock in missing**, **Clock out missing**, **Employee inactive**                                 |
| **Worked Time**            | **Total hours**, **Normal hours**, **Overtime**, **Short time**, **Billable hours**, **Night shift hours** and other numbers from the day            |
| **Leave**                  | **Has Leave**, **Leave Type**, and leave hours and days by leave type                                                                                |
| **Activities**             | Whether the day has a chosen activity or activity category (**Activity (Presence)**, **Activity Category (Presence)**), or the hours or units on one |
| **Harvest**                | Whether the day has a chosen produce or variant, or the quantity harvested                                                                           |

The two conditions used most:

* **Public holiday** is true when the day is a public holiday for the employee.
* **Optional day** is true when the day's shift on the employee's clock template has **Make working hours optional** ticked. Days where it is false are the employee's required working days.

The comparison depends on the field:

| Kind of field                         | Comparisons                                                                                          | Example                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Yes or no, such as **Public holiday** | **Is**, **Is not**, with **True** or **False**                                                       | **Public holiday** **Is** **False**            |
| A list, such as **Day of the week**   | **Is in**, **Is not in**                                                                             | **Day of the week** **Is in** Saturday, Sunday |
| A number, such as **Total hours**     | **Equals**, **Not equals**, **Greater than**, **Less than**, **Greater or equal**, **Less or equal** | **Total hours** **Greater than** 8             |

### Combining conditions with And and Or

Conditions sit in groups. A group is marked **And** or **Or**:

* In an **And** group, a day must match every condition.
* In an **Or** group, a day must match at least one condition.
* If a metric has both, a day must match every condition in the **And** group **and** at least one in the **Or** group.

A metric has at most one **And** group and one **Or** group. Most metrics need only an **And** group. To add the other kind, use **Add OR condition group** or **Add AND condition group**.

{% hint style="danger" %}
**The two groups are not alternatives.** The text under **Add OR condition group** says "The metric will apply if any group matches". That is not what happens: a day has to match the **And** group as well as the **Or** group.

**Example:** the **And** group has **Day of the week** **Is in** Wednesday, Thursday. The **Or** group has **Public holiday** **Is** **True**. The metric counts only public holidays that fall on a Wednesday or a Thursday. It does not count every Wednesday and Thursday plus every public holiday.

To count days that match one rule or another, create one metric for each rule and link both to the same pay run template. Make sure no day matches both, or its hours are counted twice.
{% endhint %}

A condition with a list already works as "or" inside itself: **Day of the week** **Is in** Wednesday, Thursday matches either day.

{% hint style="warning" %}
**A day-of-the-week condition does not leave out public holidays.** A metric with only **Day of the week** **Is in** Monday to Friday also counts Good Friday. If another metric counts public holidays, those hours are counted twice. Add **Public holiday** **Is** **False** to any metric that should not count public holidays.
{% endhint %}

## Measurements

A measurement is the number AllWage takes from each matching day. If you add more than one measurement, they are added together for each day.

| Measurement                                                                    | What it is for a day                                                                                                                           |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Total hours**                                                                | All the hours worked, after flex and breaks. It includes the overtime.                                                                         |
| **Normal hours**                                                               | The hours worked up to the day's budget hours                                                                                                  |
| **Overtime**                                                                   | The hours worked above the day's budget hours                                                                                                  |
| **Billable hours**                                                             | The day's budget hours from the clock template, whether or not the employee worked. This is the same value that other pages call budget hours. |
| **Short time**                                                                 | The budget hours minus the hours worked and leave                                                                                              |
| **Night shift hours**                                                          | The hours worked inside the clock template's night shift window                                                                                |
| **… Leave Hours (Approved)**, for example **Annual Leave Hours (Approved)**    | Approved leave hours of that type on the day                                                                                                   |
| **Total Approved Leave Hours**                                                 | Approved leave hours of all types together                                                                                                     |
| **\[activity] \[category] (Duration)**                                         | Hours on that activity                                                                                                                         |
| **\[activity] \[category] (Total)**                                            | Units captured against that activity                                                                                                           |
| **\[category] \[Category] (Duration)** and **\[category] \[Category] (Total)** | Hours or units for all activities in a category together                                                                                       |
| A produce or variant, under **Harvest**                                        | Quantity harvested                                                                                                                             |

Three things to know before you combine measurements:

* **Total hours is Normal hours plus Overtime.** If one metric measures **Total hours** and another measures **Overtime** on the same days, the overtime is counted twice.
* **Billable hours don't depend on the employee working.** Use them for hours that are paid whether or not the employee clocks, such as a public holiday on a required day.
* **Leave hours are 0 on optional days and on public holidays**, even when a leave record covers the day.

Leave measurements exist for these leave types: Annual, Sick, Family Responsibility, Maternity, Special, Unpaid, Study, Parental, Booked Off, Injury on Duty (IOD), Suspended, Religious Holiday, Bad Weather, Standby and Other.

For how AllWage gets each day's total hours, normal hours, overtime and budget hours, see [How hours are calculated](https://help.allwage.com/modules/time-and-attendance/how-hours-are-calculated.md).

## Formulas

Use a formula when adding up a measurement is not enough: for example to count only the hours above a threshold, to subtract a break, or to count days instead of hours. In the measurement picker, choose **JEXL Expression** under **Expression**. A metric uses either measurements or a formula, not both.

In the **Expression** box, type `$` to browse the fields and insert one. A formula is worked out for each matching day, and the results are added up for the period. It can use:

* the day's values, by the names the picker inserts, such as `totalHours`, `actualHours` (the **Normal hours**), `overtime` and `billableHours` (the budget hours);
* `+`, `-`, `*` and `/`;
* comparisons (`>`, `>=`, `<`, `<=`, `==`, `!=`) and `&&` (and), `||` (or), `!` (not);
* a choice, written `condition ? value if true : value if false`;
* `Math` functions, such as `Math.min(a, b)`, `Math.max(a, b)`, `Math.round(x)`, `Math.floor(x)`, `Math.ceil(x)` and `Math.abs(x)`.

| What you want                                             | Formula                                        | A 10-hour day gives | A 7-hour day gives |
| --------------------------------------------------------- | ---------------------------------------------- | ------------------- | ------------------ |
| Only the hours above 8                                    | `Math.max(totalHours - 8, 0)`                  | 2                   | 0                  |
| The hours, but never more than 8                          | `Math.min(totalHours, 8)`                      | 8                   | 7                  |
| Count 1 for each day of 7 hours or more                   | `totalHours >= 7 ? 1 : 0`                      | 1                   | 1                  |
| The hours less a 1-hour break on days longer than 5 hours | `totalHours > 5 ? totalHours - 1 : totalHours` | 9                   | 6                  |

Put the choice of days in the conditions and keep the formula for the calculation. "Only Saturdays" is a condition, not part of the formula.

When the formula is correct, AllWage shows "Expression is valid". Otherwise it shows what is wrong:

| Message                                                      | What it means                                                                                                           |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| "Invalid expression syntax or unsupported language feature." | The formula is not written correctly, for example a missing bracket, or it uses something formulas don't support        |
| "Unknown variable: …"                                        | The formula uses a name AllWage doesn't recognise. Insert fields with `$` instead of typing them                        |
| "Unknown function 'max'. Use Math.max(...) instead."         | Functions must start with `Math.`                                                                                       |
| "Math.… expects … argument(s); received …."                  | The function has too many or too few values between its brackets                                                        |
| "Custom metrics cannot reference other custom metrics: …"    | A metric's formula can't use another custom metric. Use a [custom aggregation](#custom-aggregations) to combine metrics |

If a formula can't be worked out for a day, for example because a value is missing, that day adds 0.

## Custom aggregations

A custom metric looks at one day at a time. A **custom aggregation** looks at a whole week or pay period: it takes the totals of other metrics over that range and puts them through a formula. Use one when the answer depends on more than one day, for example "overtime is the hours above 45 in a week".

1. On **Manage > Custom metrics**, click **Add aggregation**. The **Configure Aggregation** panel opens.
2. Enter an **Aggregation name**. It must be different from every other aggregation on your profile.
3. Under **Set up formula**, choose **Calculate over**:
   * **Pay period:** the formula runs once over the whole period. The period is the pay run's dates, or the report's date range.
   * **Weekly:** the formula runs for each block of 7 days, counted from the first day of the period. If the period starts on a Thursday, each week runs Thursday to Wednesday. The last week is shorter if the days run out.
   * **Calendar week:** the formula runs for each Monday to Sunday. If the period starts or ends mid-week, the first and last weeks are shorter.
4. Write the formula. Type `$` to insert metrics from **Standard metrics** or **Custom metrics**. Each one stands for that metric's total over the week or period. The formula follows the same rules as a [metric's formula](#formulas).
5. Click **Add**. AllWage shows "New aggregation created".

With **Weekly** and **Calendar week**, the aggregation's value for the period is the weekly results added together.

**Example:** a metric called "Required day hours" measures **Total hours** on days where **Optional day** **Is** **False** and **Public holiday** **Is** **False**. An aggregation calculated over **Calendar week** uses the formula "the larger of 0 and Required day hours minus 45". In a week where the employee's required-day hours are 50, the result is 5. In a week of 40 hours, it is 0. Over a fortnight with those two weeks, the aggregation's value is 5.

Things to know:

* An aggregation has no conditions of its own. To leave days out, put the conditions on the metrics it uses.
* A formula can use standard metrics and custom metrics. It can't use another aggregation.
* A short week is calculated on the days it has. A threshold meant for a full week, such as 45 hours, is still compared with a 3-day week's hours. Line the pay run's period up with the weeks where you can, or work the threshold out from the budget hours: see [Weekly or period overtime](https://help.allwage.com/modules/time-and-attendance/custom-metrics/custom-metric-sets.md#weekly-or-period-overtime).

## Check a metric before you pay from it

AllWage has no preview of a metric's result while you build it. Check a new or changed metric on real days before you link it to a pay run template:

1. On the [Employee Overview](https://help.allwage.com/modules/time-and-attendance/reports/employee-overview.md), generate the report for one or two employees over a period you know well. Choose a period with a weekend and, if you can, a public holiday.
2. Click **Export Metrics**, then **Select metrics**, and tick the new metric. Set the **Type** filter to **System** and also tick **Total Hours**.
3. Under **Export Type**, choose **Daily**, then click **Export**.
4. In the file, check that the metric has a value on every day it should count and 0 on every day it should not, and that each value is what you would work out by hand from that day's hours.

If the metric is part of a set that payroll uses, also check the set as a whole: see [Check your set for gaps and overlaps](https://help.allwage.com/modules/time-and-attendance/custom-metrics/custom-metric-sets.md#check-your-set-for-gaps-and-overlaps).

## Limits and deleting

A profile can have up to 250 custom metrics and aggregations combined. Beyond that, AllWage shows "Maximum of 250 combined custom metrics and aggregations reached" when you add a metric, or "Maximum of 250 custom definitions (metrics + aggregations) reached" when you add an aggregation.

Two custom metrics can't have the same name ("A metric with this name already exists"), and neither can two aggregations ("An aggregation with this name already exists").

You can't delete a custom metric or aggregation that is still in use:

* "Cannot delete custom metric '…' — it is linked to … pay run template(s): …". Remove the metric from the pay run templates named in the message first. See [Link a metric or quantity](https://help.allwage.com/modules/payroll/payrun-templates.md#link-a-metric-or-quantity).
* "Cannot delete custom metric '…' — referenced by … custom aggregation(s): …". Change or delete the custom aggregations named in the message first.
* "Cannot delete custom aggregation '…' — it is linked to … pay run template(s): …". Remove the aggregation from the pay run templates named in the message first.

If you select several to delete and one of them is in use, none are deleted.

## Public holiday metrics

AllWage's standard (**System**) metrics include a set for public holidays. You choose them in the same lists as custom metrics, for example under **Export Metrics** on the Employee Overview. "Required days" are days that aren't optional on the employee's clock template.

| Metric                              | What it gives                                                                                                                                   |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public Holiday Clocked Total**    | All hours clocked on public holidays that fall on required days                                                                                 |
| **Public Holiday Clocked Normal**   | The normal hours (up to the budget hours) of those                                                                                              |
| **Public Holiday Clocked Overtime** | The overtime hours (above the budget hours) of those                                                                                            |
| **Public Holiday Optional Hours**   | Hours worked on public holidays that fall on optional days                                                                                      |
| **Public Holiday Budget Hours**     | The budget hours of public holidays on required days, whether or not the employee worked: the hours for the employee's ordinary pay for the day |
| **Public Holiday Worked**           | 1 for each public holiday the employee worked                                                                                                   |
| **Public Holiday Required Day**     | 1 for each public holiday on a required day, whether or not the employee worked                                                                 |

For all hours worked on public holidays, add **Public Holiday Clocked Total** and **Public Holiday Optional Hours** together. For how to pay public holidays with these metrics, see [Public Holidays](https://help.allwage.com/modules/payroll/payrun-templates/public-holidays.md#time-and-attendance-metrics).

## Export custom metric values

Use **Export Metrics** on the [Employee Overview](https://help.allwage.com/modules/time-and-attendance/reports/employee-overview.md#exports) report. Choose the metrics, then **Summary** for one total per employee for the period, or **Daily** for a value per employee per day.

To find metrics quickly there, filter them by tag. Tags are labels added to a metric under **Link tags (Optional)** when it is set up. Use them to group the metrics you export together, such as all the metrics for one pay run.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.allwage.com/modules/time-and-attendance/custom-metrics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
