--- availability: INSTALLABLE description: Proactively notifies employees when their PTO request in UKG Pro WFM has been approved, refused, or cancelled. name: Notify on PTO Decision installation_asset_uuid: 559d1bdf-7507-4f25-91f8-d1b55f5c9f18 purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EDecision+Taken%3A+PTO+Approved%3C%2Fstrong%3E%3C%2Fp%3E%3Cp%3EYour+Time+Off+request+for+%3Cstrong%3E4%2F12%2F2026%3C%2Fstrong%3E+has+been+%3Cstrong%3EApproved%3C%2Fstrong%3E+by+%3Cstrong%3EPaul+Senior%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ERequest+Dates%3A%3C%2Fstrong%3E+4%2F12%2F2026+-+4%2F12%2F2026%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A%3C%2Fstrong%3E+Vacation%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EReason%3A%3C%2Fstrong%3E+Approved+since+we+have+enough+team+coverage+in+this+time+period.%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off%3A+Apr+12%2C+2026%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EDecision+Taken%3A+PTO+Rejected%3C%2Fstrong%3E%3C%2Fp%3E%3Cp%3EYour+Time+Off+request+for+%3Cstrong%3E4%2F13%2F2026+-+4%2F14%2F2026%3C%2Fstrong%3E+has+been+%3Cstrong%3ERejected%3C%2Fstrong%3E+by+%3Cstrong%3EPaul+Senior%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ERequest+Dates%3A%3C%2Fstrong%3E+4%2F13%2F2026+-+4%2F14%2F2026%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A%3C%2Fstrong%3E+Vacation%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EReason%3A%3C%2Fstrong%3E+Insufficient+balance%2C+please+apply+in+the+next+cycle.%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off%3A+Apr+13-14%2C+2026%22%7D%5D%7D%5D%7D%5D%7D solution_tags: - HR - Other - HR - Time & Absence systems: - ukg-pro-wfm --- # Description Proactively notifies employees when their PTO request in UKG Pro WFM has been approved, refused, or cancelled. # User Experience Preview Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EDecision+Taken%3A+PTO+Approved%3C%2Fstrong%3E%3C%2Fp%3E%3Cp%3EYour+Time+Off+request+for+%3Cstrong%3E4%2F12%2F2026%3C%2Fstrong%3E+has+been+%3Cstrong%3EApproved%3C%2Fstrong%3E+by+%3Cstrong%3EPaul+Senior%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ERequest+Dates%3A%3C%2Fstrong%3E+4%2F12%2F2026+-+4%2F12%2F2026%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A%3C%2Fstrong%3E+Vacation%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EReason%3A%3C%2Fstrong%3E+Approved+since+we+have+enough+team+coverage+in+this+time+period.%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off%3A+Apr+12%2C+2026%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3E%3Cstrong%3EDecision+Taken%3A+PTO+Rejected%3C%2Fstrong%3E%3C%2Fp%3E%3Cp%3EYour+Time+Off+request+for+%3Cstrong%3E4%2F13%2F2026+-+4%2F14%2F2026%3C%2Fstrong%3E+has+been+%3Cstrong%3ERejected%3C%2Fstrong%3E+by+%3Cstrong%3EPaul+Senior%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ERequest+Dates%3A%3C%2Fstrong%3E+4%2F13%2F2026+-+4%2F14%2F2026%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A%3C%2Fstrong%3E+Vacation%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EReason%3A%3C%2Fstrong%3E+Insufficient+balance%2C+please+apply+in+the+next+cycle.%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Time+Off%3A+Apr+13-14%2C+2026%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 Decision** 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 on behalf of the employee. 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. 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 the following employee-facing notification types enabled — these are the notifications UKG generates when a manager approves, refuses, or cancels an employee's time-off request: - **`TOR-Employee Notification`** — generated when a PTO request is approved - **`TOR-Refusal`** — generated when a PTO request is refused - **`TOR-Employee Status Change`** — generated when a PTO request is cancelled To verify: go to **Administration > Application Setup > Common Setup > Event Manager** in UKG and confirm these time-off decision notifications are active for employees. ### **c. Employee Permissions (User Consent)** Employees must have permission to view PTO notifications in UKG WFM and a valid UKG User Consent authorization (reauthorized within the last 24 hours) for notification acknowledgement. **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. While this event does fire on approval (when the leave pay code is applied to the schedule), it does not cover refusals or cancellations — and the payload does not include the employee-facing notification details needed for a rich notification message. Instead, the plugin polls UKG's Notifications API, which mirrors exactly what an employee sees in their **Control Center > My Notifications** tile. This approach covers all three decision states (approved, refused, cancelled) with complete notification context. If UKG generates a notification for an employee, 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 employee-facing PTO decision notifications using: | Field | Value | Reason | |-------|-------|--------| | `type` | `TIME_OFF` | PTO-related notifications only | | `reviewed` | `false` | Not yet seen by the employee | | `status` | `Approved`, `Refused`, or `Cancelled` | Decision has been made | | `disableActions` | `true` | No further action required — informational only | | `category` | `MYREQUEST` | Employee's own request (not a manager approval queue) | | `notificationName` | `TOR-Employee Notification`, `TOR-Refusal`, or `TOR-Employee Status Change` | Decision notifications sent to the requesting employee | **Key difference from Notify on PTO Submission:** The PTO Submission plugin filters for `category: REQUEST` and `disableActions: false` (manager-facing, actionable). This plugin filters for `category: MYREQUEST` and `disableActions: true` (employee-facing, informational). These are entirely separate notification objects in UKG — even for the same PTO request, the manager and employee receive different notifications with different `notificationName` values. # **Implementation Details** ## Visual Representation of How the Plugin Works ![image.png](Notify%20on%20PTO%20Decision/image.png) ## API Details Before running the cURL examples below, replace '' 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:///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 an employee sees in their UKG Control Center. **Auth:** Client Credentials ```bash curl --request POST \ --url https:///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 an employee, used to extract their work email for Moveworks user resolution. **Auth:** Client Credentials ```bash curl --request GET \ --url https:///api/v1/commons/persons/{{personId}} \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' ``` **Parameters:** - `personId` *(integer):* The UKG person ID of the employee (from the notification's `employee.id` field). **Key nuances:** - Unlike the Notify on PTO Submission plugin (which uses `receiverId` to look up the manager), this plugin uses `employee.id` to look up the employee who submitted the PTO — since the employee is the notification recipient for decision notifications. ### **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:///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 employee. 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 employee. UKG's user consent token expires every 24 hours. If the employee'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 employee reauthorizes, the notification is delivered one final time and successfully acknowledged. Support is being built on the Moveworks platform for the AI Assistant to automatically acknowledge notifications 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 employee's notification center — it does not create or infer notifications. If a notification type is disabled in the UKG tenant, or if the employee's request was not routed through UKG's standard approval workflow, the plugin will not generate any alert. # **What Is In Scope for This Plugin?** - Notifying employees when their PTO request has been **approved**, **refused**, or **cancelled**. - Surfacing the **decision maker's name**, **requested dates**, **leave type**, and **reason/details** in the notification. - Notifying decisions for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time). - Surfacing **detailed approval chain information** (e.g., which approver in a multi-step chain made the final decision). - **Auto-acknowledging** notifications in UKG after delivery to prevent duplicates. # **What Is Out of Scope for This Plugin?** - Notifying PTO decisions for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability. - Notifying **managers or approvers** about new PTO submissions requiring action (separate use case: Notify on PTO Submission). - Notifying on **ESS (Employee Self-Service) submission notifications** — these use a different notification type (`ESS-Employee Submission Notification`) and are not included in the current filter.