---
availability: INSTALLABLE
description: Proactively notifies managers and approvers when an employee submits a PTO request in UKG Pro WFM and enables one-tap approval or rejection.
name: Notify on PTO Submission
installation_asset_uuid: 62b579f3-56fd-48cf-a81d-4f4a34334f12
purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22startTimestamp%22%3A%2211%3A43+AM%22%2C%22messages%22%3A%5B%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EAlex+Johnson+has+submitted+a+time+off+request+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Alex+Johnson%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EPaid+Time+Off+%28Vacation%29%3A+3+days%3C%2Fstrong%3E%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EStart+Date%3A%3C%2Fstrong%3E+Oct+14%2C+2024%3C%2Fli%3E%3Cli%3E%3Cstrong%3EEnd+Date%3A%3C%2Fstrong%3E+Oct+17%2C+2024%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETotal+Time+Taken%3A%3C%2Fstrong%3E+3+days%3C%2Fli%3E%3Cli%3E%3Cstrong%3EJustification%3A%3C%2Fstrong%3E+Going+to+a+friend%27s+wedding%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Approve%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Reject%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Approve%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EApproving+the+time+off+request+in+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+successfully+approved+the+time+off+request+for+%3Cb%3EAlex+Johnson%3C%2Fb%3E+in+%3Cb%3EUKG+WFM%3C%2Fb%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off+Request+-+Alex+Johnson%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- HR - Other
- HR - Time & Absence
systems:
- ukg-pro-wfm
---
# Description
Proactively notifies managers and approvers when an employee submits a PTO request in UKG Pro WFM and enables one-tap approval or rejection.
# User Experience Preview
Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22startTimestamp%22%3A%2211%3A43+AM%22%2C%22messages%22%3A%5B%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EAlex+Johnson+has+submitted+a+time+off+request+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Alex+Johnson%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EPaid+Time+Off+%28Vacation%29%3A+3+days%3C%2Fstrong%3E%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EStart+Date%3A%3C%2Fstrong%3E+Oct+14%2C+2024%3C%2Fli%3E%3Cli%3E%3Cstrong%3EEnd+Date%3A%3C%2Fstrong%3E+Oct+17%2C+2024%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETotal+Time+Taken%3A%3C%2Fstrong%3E+3+days%3C%2Fli%3E%3Cli%3E%3Cstrong%3EJustification%3A%3C%2Fstrong%3E+Going+to+a+friend%27s+wedding%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Approve%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Reject%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Approve%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EApproving+the+time+off+request+in+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+successfully+approved+the+time+off+request+for+%3Cb%3EAlex+Johnson%3C%2Fb%3E+in+%3Cb%3EUKG+WFM%3C%2Fb%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off+Request+-+Alex+Johnson%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin.
# Pre-requisites
Before installing and using the **Notify on PTO Submission** plugin, please ensure the following requirements are met:
## **1. UKG Connector**
This plugin requires **two active UKG connectors**:
- **Client Credentials Auth (Non-Interactive)** — used for all system-level polling: fetching users, retrieving bulk notifications, and looking up user details.
- **User Consent Auth (Interactive)** — used for notification acknowledgement and the approve/reject action performed by the manager.
If you have not already configured the connectors, please follow the [**UKG Connector Guide**](https://marketplace.moveworks.com/connectors/ukg-pro-wfm) available in the Moveworks Marketplace. Both connectors must be fully set up before installing this plugin.
Once configured, follow our [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for detailed steps on how to install and activate the plugin in **Agent Studio**.
## **2. Approve or Reject PTO Plugin**
This ambient agent triggers the **Approve or Reject Time Off** plugin when a manager taps Approve or Reject on a notification. This plugin must be installed and active **before** installing the Notify on PTO Submission plugin.
If you have not already installed it, please follow the [**Approve or Reject Time Off Plugin Guide**](https://marketplace.moveworks.com/plugins/ukg-approve-reject-time-off#how-to-implement) available in the Moveworks Marketplace.
## **3. UKG System Requirements**
### **a. Service Account Permissions (Client Credentials)**
The client credentials connector uses a service account to poll notifications across all users. This service account must have:
- **Function Access Profile (FAP)** set to **Super Access** (or equivalent)
- Permission to read all employee notification records and person records
### **b. Notification Configuration**
The UKG tenant must have **"TOR-Submission Notification Manager"** enabled — this is the notification UKG generates when an employee submits a time-off request. The plugin specifically filters for this notification name.
To verify: go to **Administration > Application Setup > Common Setup > Event Manager** in UKG and confirm the time-off request submission notification is active for managers.
### **c. Manager Permissions (User Consent)**
Managers must have permission to approve and refuse time-off requests in UKG WFM and a valid UKG User Consent authorization (reauthorized within the last 24 hours).
**Note**: The plugin does not grant new permissions. It respects existing role-based permissions and policies in UKG WFM.
# **How This Plugin Works**
## **Why Polling Instead of Webhooks?**
UKG Pro WFM supports webhooks through the [UKG Webhooks Events Catalog](https://developer.ukg.com/hcm/docs/ukg-webhooks-events-catalog). The closest available event is `PTOChangeEvent`, which fires when a PTO request results in a **pay code change** on the employee's timecard. A pay code change only occurs when a PTO is **approved** — that's when the leave pay code is applied to the employee's schedule. A **submitted** PTO (still pending approval) does not trigger a pay code change and therefore does not fire the webhook.
Since this plugin needs to notify managers at the point of submission — before any decision is made — the webhook event does not apply. Instead, the plugin polls UKG's Notifications API, which mirrors exactly what a manager sees in their **Control Center > My Notifications** tile. If UKG generates a notification for a manager, the API returns it. If it doesn't, the API won't return it either.
## **Triggering**
This plugin runs on a **Scheduled CRON job** every 30 minutes (CRON expression: `*/30 * * * *`), with a 1-hour lookback window to ensure no notifications are missed.
```bash
# Start of the polling window (1 hour before current time)
start_date: "($TIME() - 3600).$FORMAT_TIME('%Y-%m-%dT%H:%M:%S')"
# End of the polling window (current time)
end_date: "$TIME().$FORMAT_TIME('%Y-%m-%dT%H:%M:%S')"
# Number of pages to fetch users from (200 users per page)
max_pages: "200"
```
## **Notification Filtering**
From the raw notification response, the plugin filters for actionable PTO submissions using:
| Field | Value | Reason |
|-------|-------|--------|
| `type` | `TIME_OFF` | PTO-related notifications only |
| `reviewed` | `false` | Not yet seen by the manager |
| `status` | `Submitted` | Pending action, not already decided |
| `disableActions` | `false` | Manager can still act on it |
| `category` | `REQUEST` | Approval-type notification |
| `notificationName` | `TOR-Submission Notification Manager` | New PTO submissions to managers only |
# **Implementation Details**
## Visual Representation of How the Plugin Works
## API Details
Before running the cURL examples below, replace '<YOUR_UKG_HOST>' with your actual UKG hostname (e.g., `acme-prod.cfn.mykronos.com`).
### **API #1: Get All UKG Users (Paginated)**
Retrieves all active users from UKG using pagination. Only person IDs are returned to minimize payload size.
**Auth:** Client Credentials
```bash
curl --request POST \
--url https://<YOUR_UKG_HOST>/api/v1/commons/persons/apply_read \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"count": {{count}},
"index": {{index}},
"where": {
"snapshotDate": "{{date}}",
"employmentStatus": "Active",
"userAccountStatus": "Active",
"returnPersonIdOnly": true
}
}'
```
**Parameters:**
- `count` *(integer):* Users per page (default: 200).
- `index` *(integer):* Page index starting from 0.
- `date` *(string):* Today's date in `YYYY-MM-DD` format.
### **API #2: Fetch Bulk Notifications for Employee List**
Retrieves all `TIME_OFF` notifications for a batch of users within a date range. This is the core API that surfaces the same notifications a manager sees in their UKG Control Center.
**Auth:** Client Credentials
```bash
curl --request POST \
--url https://<YOUR_UKG_HOST>/api/v1/commons/notifications/apply_read \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"employees": {
"ids": {{ids}}
},
"types": ["TIME_OFF"],
"startDateTime": "{{start_date_time}}",
"endDateTime": "{{end_date_time}}"
}'
```
**Parameters:**
- `ids` *(array of integers):* UKG person IDs (from API #1).
- `start_date_time` / `end_date_time` *(string):* Date range in `YYYY-MM-DDTHH:MM:SS` format.
**Key nuances:**
- Maximum of **1,000 notifications per call** ([UKG API Limits](https://developer.ukg.com/wfm/docs/limits-doc)). The plugin handles this by batching 200 user IDs per call.
- Only returns notifications that UKG has generated — the plugin never creates or infers notifications.
### **API #3: Lookup UKG User by ID**
Retrieves the full person record for a manager, used to extract their work email for Moveworks user resolution.
**Auth:** Client Credentials
```bash
curl --request GET \
--url https://<YOUR_UKG_HOST>/api/v1/commons/persons/{{personId}} \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept: application/json'
```
**Parameters:**
- `personId` *(integer):* The UKG person ID of the manager (from the notification's `receiverId`).
### **API #4: Acknowledge Notifications in UKG**
Marks a notification as reviewed in UKG, preventing duplicate delivery on the next polling cycle.
**Auth:** User Consent (the notification recipient must be authenticated)
```bash
curl --request POST \
--url https://<YOUR_UKG_HOST>/api/v1/commons/notifications/multi_review \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"messageIds": ["{{uuid}}"]
}'
```
**Parameters:**
- `uuid` *(string):* The unique notification ID from API #2.
**Key nuances:**
- Requires **user consent authentication** from the manager. Client credentials cannot acknowledge on behalf of another user.
### API References
For detailed information on request parameters, response formats, and error handling, refer to the [**official UKG API documentation**](https://developer.ukg.com/wfm/reference/welcome-to-the-ukg-pro-workforce-management-api).
# **Known Limitations**
### **Notification Acknowledgement and User Consent Auth**
The acknowledgement step (API #4) requires user consent authentication from the manager. UKG's user consent token expires every 24 hours.
If the manager's token has expired when the notification is processed, the notification will still be delivered, but acknowledgement will fail — causing the same notification to be re-delivered on the next polling cycle. Once the manager reauthorizes, the notification is delivered one final time and successfully acknowledged.
Support is being built on the Moveworks platform for the AI Assistant to understand which PTO notification needs to be acted on and to automatically acknowledge it once the user has reauthorized — even across sessions.
### **Notification API Limit**
The UKG Notifications API returns a maximum of **1,000 notifications per call** ([UKG API Limits](https://developer.ukg.com/wfm/docs/limits-doc)). The plugin handles this by batching 200 user IDs per call. This assumes fewer than 1,000 time-off notifications are generated for any batch of 200 users within each 30-minute window. For organizations with very high PTO volume, the batch size may need to be reduced.
### **Notification Mirroring**
This plugin only surfaces notifications that **already exist in UKG Pro WFM**. It mirrors the manager's notification center — it does not create or infer notifications. If a notification type is disabled in the UKG tenant, or if a manager is not in the approval chain for an employee, the plugin will not generate any alert.
# **What Is In Scope for This Plugin?**
- Notifying managers and approvers of new PTO submissions for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time).
- Allowing managers to **approve or reject** directly from the notification.
- Prompting for a **rejection reason** when a manager chooses to reject.
- Notifying **all approvers** in the PTO approval chain (if multiple exist).
- **Auto-acknowledging** notifications in UKG after delivery to prevent duplicates.
# **What Is Out of Scope for This Plugin?**
- Notifying PTO submissions for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability.
- Notifying employees about **approval or rejection decisions** on their own PTO requests (separate use case: Notify on PTO Decision).
- Batch approval of multiple PTO requests from a single notification.
- Modifying PTO request details (dates, duration, leave type) from the notification.