Leave requests

A leave request records that one person is away from one date to another, and its Status decides whether the rest of xMatix treats that person as away. It sits between the leave types you set up once and the places that read leave: the payroll run, mobile attendance check-in, assignment rules, the dispatch console and appointment and training scheduling.

Overview

A leave request names a Resource (the person), a Leave Type, a From Date and a To Date, and carries a Status of Pending, Approved, Rejected or Cancelled. It is keyed on the person's Resource record, so you can record leave for people who are not on payroll as well as for employees.

There is no approval workflow behind a leave request. No approval process ships for it, and it has no Approve or Reject button. A request is approved when someone with edit access sets its Status to Approved and saves. There is also no leave balance: nothing checks a request against an allowance, and approving leave does not reduce a Leave Entitlement.

When to use it

Record a leave request whenever a person will be away for a day or more, or for half a day, and the absence should:

• reduce pay, when the leave type is unpaid;
• stop the person checking in on the mobile app that day;
• keep the person out of automatic assignment and show them as on leave in the dispatch console;
• stop a training session being booked with them as trainer.

Record it before the payroll run for that month is calculated. A request approved after the run is posted does not change that run.

How xMatix handles it

Each part of xMatix reads leave requests on its own terms. The table shows which statuses count as leave in each place.

So a Pending request already takes someone out of automatic assignment and shows them as on leave on the consoles. It does not affect pay, check-in, appointment capacity or training until it is Approved.

A leave request doesn't create or change any attendance day (Resource Availability record).

Prerequisites

• A way to reach the list. No shipped app lists Leave Request. Find it through the App Launcher search, or ask your administrator to add it to an app (see Configuration).
• A form that can save. The shipped Create Leave Request form shows only Resource, Leave Type, From Date and To Date. Every leave request needs a Name, and no numbering setting ships for leave requests, so the shipped form can't save a new request: it is refused with "Name is required". It also has no Status box. Your administrator adds Name and Status to the form, or sets up numbering for the name (see Configuration).
• Leave types. Create the leave types first, and set Type to Unpaid on every type that should reduce pay.
• Resources. The person needs a Resource record. For payroll, the employee must be linked to that Resource.
• Access. Your security profile needs access to the Leave Request entity (see Permissions).

Procedure

Step 1 — Open the leave request list

Open the App Launcher (the grid icon next to the xMatix logo) and type Leave Request in the search box. Select Leave Request under All Entities. The All Leave Requests list opens, with the columns Name, Resource, Leave Type, Status, Days, From Date and To Date. If your administrator has added Leave Request to an app, open it from that app's navigation instead.

Step 2 — Record a request

1. Click New in the list header.
2. In Name, enter a short description, for example Casual leave 3–4 Nov. Skip this if your administrator set up numbering for leave requests.
3. In Resource, choose the person who will be away.
4. In Leave Type, choose the category. Choose an unpaid type for leave that should reduce pay.
5. In From Date, choose the first day away. In To Date, choose the last day away. Both days are included, so a one-day request has the same date in both boxes. Always fill To Date: the payroll run, mobile check-in and the consoles ignore a request without one.
6. In Status, choose Pending while the request waits for a decision, or Approved if it is already agreed. Status has no default, so leaving it empty saves a request with no status.
7. If your form shows Days, tick it for a half day. Despite its name, Days is a half-day flag, not a number of days.
8. Save. The request appears in the list with the values you entered.

Step 3 — Approve, reject or cancel a request

1. In the All Leave Requests list, open the row's actions and choose Edit.
2. Change Status to Approved, Rejected or Cancelled.
3. Save.

Nothing else happens on save: no notice is sent and no attendance day is created. The new status takes effect the next time each part of xMatix reads leave. Payroll reads it when the run is next calculated, check-in reads it at the next punch, and the consoles read it when they next load the day.

To withdraw a request, set its status to Cancelled rather than deleting it, so the record of the request stays.

Step 4 — Change the dates or the type

Choose Edit on the row, change From Date, To Date or Leave Type, and save. If the request is approved and falls in a month whose payroll run is not yet posted, click Calculate on that run again so it uses the new dates.

Step 5 — Delete requests

Choose Delete on the row, or select several rows and click Delete in the list header, and confirm. A deleted request no longer counts anywhere. If it was approved, recalculate any unposted payroll run for that month.

Fields

Business rules

• No checks on save. xMatix doesn't check that To Date is on or after From Date, that requests for the same person don't overlap, or that the person has leave left. The only rule on save is that Name is filled.
• Status is the switch. Only the values in the table under How xMatix handles it matter. Use the picklist values as shipped; a status typed as other text may count in some places and not in others.
• Payroll counts calendar days. When a run is calculated, each approved request of an unpaid type adds every day from From Date to To Date that falls inside the payroll period and inside the employee's employment window. Weekends and holidays inside the span are counted too. A half-day request counts half. Loss-of-pay days never exceed the employed days.
• Paid leave still matters to payroll. When the Payroll setting Unpaid absence: working days with no attendance is on, any approved leave, paid or unpaid, stops those days being counted as absent.
• HR's locked attendance wins. When HR has locked an employee's month, the run takes HR's payable and loss-of-pay days and doesn't count leave requests for that person.
• Posted runs don't change. A request approved, changed or deleted after a run is posted doesn't change that run. Correct it with a payroll adjustment in a later period.
• Today for assignment rules is the current date in UTC, so close to midnight in your zone the rule may look at a different day than you expect.
• Trainers. Booking a training session refuses a trainer on approved leave with "name is on leave dates (leave type, half day). Pick another time or another trainer." A half-day request blocks the whole day. Leave approved after a session was booked doesn't move the session; an hourly check notifies about trainers who are now away.
• No attendance day. Approving leave doesn't create or change a Resource Availability record.

Example

A field service company pays monthly. A technician asks for two days of unpaid leave, 12 and 13 November, and one day of casual leave on 20 November.

1. The service supervisor opens Leave Request from the App Launcher and creates Unpaid leave 12–13 Nov for the technician's Resource, Leave Type Leave Without Pay (Type Unpaid), From Date 12 November, To Date 13 November, Status Pending.
2. That afternoon the assignment rule for new service orders skips the technician for 12 November, and the dispatch console shows the technician as on leave on both days, even though the request is still pending.
3. The manager agrees. The supervisor edits the request and sets Status to Approved. The technician's check-in on 12 November is refused: "You have an approved leave covering today."
4. The supervisor records Casual leave 20 Nov, Leave Type Casual Leave (Type Paid), From Date and To Date 20 November, Status Approved.
5. On 26 November the payroll officer calculates the November run. The period has 30 days. The two unpaid days are loss-of-pay days and the casual day is paid, so the technician's payable days are 28.

Training

Practice exercise

In a sandbox with Payroll set up, and with Name and Status on the leave request form:

1. Create a leave request for an employee on payroll: Leave Type an unpaid type, From Date and To Date two consecutive weekdays inside a payroll period whose run is not posted, Status Pending.
2. Click Calculate on the run and open the employee's payroll run detail. Note Loss Of Pay Days.
3. Edit the request, set Status to Approved, and calculate again.
4. Tick Days on the request (if it is on your form) and calculate again.

Expected result: Loss Of Pay Days is 0 after step 2, 2 after step 3 and 1 after step 4. Delete the practice request and recalculate the run afterwards.

Quick reference

• Find Leave Request through the App Launcher search under All Entities.
• The shipped form can't save a new request until Name is added or numbered.
• From Date and To Date are both included; always fill To Date.
• Approved is the only status payroll, check-in, appointments and training read.
• Pending already counts as leave for assignment rules and the consoles.
• Days is a half-day tick, not a day count.
• Approve by editing Status; there is no approval button or workflow.
• After approving or changing leave, recalculate any unposted payroll run.
• Leave beyond an allowance is neither blocked nor flagged.

Permissions

Leave requests follow the ordinary entity permissions on the user's security profile. The shipped Standard User, Sales Executive, Sales Manager and System Admin profiles have full access to Leave Request, including viewing and changing every user's requests. Other shipped profiles have none, so their users don't find Leave Request in the App Launcher search.

Because approval is just an edit of Status, anyone who can edit a request can approve it, including their own. To keep approval with managers or HR:

• remove edit access to Leave Request from the profiles that should only view or create requests, or
• use a field permission to make Status read-only for those profiles, so they can record a request but not approve it.

Leave requests have no server actions of their own that need a separate grant.

Configuration

• Menu entry. Go to Setup → Design Studio → Apps, open the app your HR or payroll staff use (for example Payroll), choose Manage Items and add Leave Request. See Create an entity (step 7).
• The form. In the layout designer, add Name and Status to the Create Leave Request layout, and Days and Reason if you use them. The same layout is used for Edit. Mark To Date as required on the form so no request is saved without one.
• Numbering the name. Instead of a typed Name, create a document numbering setting for Leave Request with Name as the destination field. See Document numbering.
• Status values. Status ships with Pending, Approved, Rejected and Cancelled, and none is the default. Keep these values: payroll, check-in, appointments and training look for Approved, and the consoles look for "reject" or "cancel" in the text. A new value such as "On hold" would count as leave on the consoles and for assignment rules, but not for pay.
• Leave types. The paid or unpaid decision lives on the leave type. See Leave types.
• Check-in leave gate. Block on approved leave on the Check-In tab of the mobile app configuration (Setup → Design Studio → Apps → Mobile Apps). See Attendance.
• Assignment rules. Add Not on leave, absent or on holiday today under Only candidates who are on a rule in Setup → Process Studio → Assignment rules. See Assignment rules.
• Absence as loss of pay. Unpaid absence: working days with no attendance in the Payroll settings decides whether unmarked working days are deducted; approved leave always protects its days. See Running payroll.
• Dashboards. The Attendance & Leave and My Attendance & Leave dashboards chart leave requests by leave type.

Common problems

"Name is required" when I save a new leave request

The form has no Name box and no numbering is set up for leave requests. Ask your administrator to add Name to the form, or to create a numbering setting for it.

There is no Status box, so I can't approve a request

The shipped form has no Status. Ask your administrator to add it to the Create Leave Request layout. Until then a request saved from the form has no status, which payroll ignores.

Approved unpaid leave was not deducted from pay

Check, in order: the request's Status is Approved; To Date is filled; the request names a leave type whose Type is Unpaid; the dates overlap the payroll period and the employee's employment dates; the request is on the employee's own Resource; and HR has not locked the month. Fix the cause and click Calculate on the run again before it is posted.

Payroll deducted the weekend in the middle of the leave

Payroll counts every calendar day from From Date to To Date. Split the request into one request per working stretch, for example Friday and Monday as two requests, and recalculate.

Someone is shown as on leave but their request is still pending

The dispatch console, the time-sheet allocation console and assignment rules count every request that isn't rejected or cancelled. Set the request to Rejected or Cancelled if the person is working, or approve it if they are not.

Someone could still check in on a day of approved leave

Block on approved leave is off in the mobile app configuration, or the request has no To Date, or it is on a different Resource from the one linked to the user.

A training session can't be booked with this trainer

The trainer has an approved leave request on a day the session touches. Pick another time or trainer, or, if the leave is no longer taken, cancel the request.

Common questions

Is there an approval workflow for leave?

No. No approval process ships for leave requests and there is no Approve or Reject button. A request is approved when someone with edit access sets Status to Approved. Nothing notifies the person when the status changes. To control who can approve, limit edit access to Leave Request, or make Status read-only with a field permission for everyone except approvers. Payroll, check-in, appointment capacity and training scheduling all read Approved, so that value is what turns a request into leave.

Does xMatix keep leave balances?

No. A leave request is never checked against an allowance, and approving one doesn't reduce anything. The Leave Entitlement record can state an allowance as policy, but nothing reads it when leave is recorded or approved, so leave beyond the allowance is neither blocked nor flagged. If someone goes over their paid allowance, record the extra days on an unpaid leave type, and the payroll run deducts them.

Does approving leave mark the attendance day?

No. A leave request doesn't create or change a Resource Availability record. Mobile check-in, payroll and the consoles read the leave request directly, so they don't need one. If your attendance reports should show a Leave day, add that day on the Resource Availability list by hand. See Attendance.

Why do the consoles and payroll disagree about who is on leave?

They read the status differently. Payroll counts only Approved requests, while the dispatch console, the time-sheet allocation console and assignment rules count any request that isn't rejected or cancelled, including Pending ones. A pending request therefore takes someone off the dispatch board without reducing their pay. Approve or reject requests promptly to keep both views the same.

Related topics

• Leave types
• Running payroll
• Payroll periods
• Attendance
• Resource availability
• Assignment rules
• Holidays
• Leave Request reference
• Leave Type reference