--- availability: INSTALLABLE description: Streamlines the time-off request process by allowing employees and managers (on behalf of employees) to submit, validate, and check the status of PTO through the AI Assistant. name: Submit PTO Request installation_asset_uuid: cab4019c-6a0e-4c8f-9a80-c25cc69273a6 purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EI%27d+like+to+take+some+time+off+%3C%2Fp%3E%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%3EAuthenticating+user+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E+...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+can+help+with+that.+What+type+of+leave%2C+dates%2C+and+duration+would+you+like+to+request%3F+%28e.g.%2C+Vacation+on+December+5th%2C+full+day%29%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27ll+use+Vacation+from+August+12th+to+August+14th%2C+full+days.%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%3EIdentifying+manager+and+verifying+schedule+in+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+prepared+your+%3Cb%3EUKG%3C%2Fb%3E+request.+It+will+be+sent+to+your+manager%2C+%3Cb%3EMarcus+Thorne%3C%2Fb%3E%2C+for+approval.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EType%3C%2Fb%3E%3A+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EDates%3C%2Fb%3E%3A+Aug+12+-+14%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3ETotal+Duration%3C%2Fb%3E%3A+3+days+%2824+hours%29%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cb%3EDoes+this+look+right%3F%3C%2Fb%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%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%22Yes%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%3ESubmitting+PTO+request+to+%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%3EYour+PTO+request+has+been+successfully+submitted.+Your+manager+has+been+notified+for+approval.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO+Request%3A+Aug+12+-+Aug+14%22%7D%5D%7D%5D%7D%5D%7D solution_tags: - HR - Other - HR - Time & Absence systems: - ukg-pro-wfm --- # Description Streamlines the time-off request process by allowing employees and managers (on behalf of employees) to submit, validate, and check the status of PTO through the AI Assistant. # 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%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EI%27d+like+to+take+some+time+off+%3C%2Fp%3E%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%3EAuthenticating+user+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E+...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+can+help+with+that.+What+type+of+leave%2C+dates%2C+and+duration+would+you+like+to+request%3F+%28e.g.%2C+Vacation+on+December+5th%2C+full+day%29%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27ll+use+Vacation+from+August+12th+to+August+14th%2C+full+days.%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%3EIdentifying+manager+and+verifying+schedule+in+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+prepared+your+%3Cb%3EUKG%3C%2Fb%3E+request.+It+will+be+sent+to+your+manager%2C+%3Cb%3EMarcus+Thorne%3C%2Fb%3E%2C+for+approval.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EType%3C%2Fb%3E%3A+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EDates%3C%2Fb%3E%3A+Aug+12+-+14%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3ETotal+Duration%3C%2Fb%3E%3A+3+days+%2824+hours%29%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cb%3EDoes+this+look+right%3F%3C%2Fb%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%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%22Yes%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%3ESubmitting+PTO+request+to+%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%3EYour+PTO+request+has+been+successfully+submitted.+Your+manager+has+been+notified+for+approval.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO+Request%3A+Aug+12+-+Aug+14%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 **Submit PTO Request** plugin, please ensure the following requirements are met: ## **1. UKG Connector** This plugin requires an active **UKG connector** using **User Consent Auth** to communicate with your UKG instance. - If you have not already configured the connector, please follow the [UKG Connector Guide](https://marketplace.moveworks.com/connectors/ukg-pro-wfm) available in the Moveworks Marketplace. - The connector must be fully set up before installing this plugin. - Once the connector is successfully 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**. **Note:** UKG's user-consent authorization expires every 24 hours, requiring users to reauthorize once per day. This is a known limitation, and support for handling such short-lived refresh tokens is being built on Moveworks. ## **2. UKG System Requirements** ### **a. End User Permissions (Employee Persona)** To submit a PTO request through this plugin, employees must already have permission to submit PTO requests in UKG WFM — the same permissions required to submit PTO through the UKG WFM UI. At a minimum, end users must have: - **Time Off permissions** that allow: - Viewing available Time Off Types - Submitting a Time Off request - Access to their own **employee profile and time account balances** - A valid **Function Access Profile (FAP)** that includes permissions for scheduling and time-off request actions - A valid **Process Profile** assigned that includes time-off request process templates (enables the use of "My Actions" for time-off requests) - An active **license assignment** for the Scheduling package in UKG Pro WFM **Note**: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in UKG WFM. ### **b. Manager Permissions (Manager Persona)** For managers to submit PTO on behalf of a direct report through this plugin, they must have: - **Manager-level Function Access Profile (FAP)** that includes: - Ability to view and manage direct reports' schedules - Ability to submit time-off requests on behalf of employees - Access to the **Hyperfind query "My Direct Reports"** (see Tenant Configuration below) - Visibility into their direct reports via the **Reports To** field configured in UKG ### **c. Tenant Configuration** The following configurations must be in place in your UKG Pro WFM tenant before this plugin will work correctly: - **Hyperfind Query — "My Direct Reports":** A hyperfind query named **"My Direct Reports"** must exist and be accessible to managers. This is used by the plugin to retrieve the manager's direct reports. If this query does not exist in your tenant, an admin must create it. Details on how to create a hyperfind query can be found [here](https://customer2.kronos.com/support/kol/onlinehelp-workforcedimensions/en-us/content/mastertopics/hyperfind/HyperFindqueries.htm). - **Symbolic Pay Period — "Current_Payperiod":** The plugin uses the symbolic period `Current_Payperiod` when retrieving direct reports and accrual data. This must exist and be active in the tenant configuration. If your tenant uses a different symbolic period name (e.g., `Current_Pay_Period`, `Current`, or a custom name), the plugin's API calls must be updated to match the exact qualifier configured in your environment. - **Time Off Request Subtypes:** Leave subtypes must be configured in UKG for the plugin to present available leave types to the employee. These are managed under **Administration > Scheduling Setup > Time Off Request Subtypes** in UKG. - **Pay Codes and Accrual Codes:** Each leave subtype must have an associated pay code configured with valid accrual codes. The plugin retrieves the `payCode.id` from the request subtypes API and validates accrual-based pay codes before presenting leave types to the user. Only leave types with valid accrual mappings are shown as available options. - **Employee Scheduling Configuration:** Employees must have an active schedule or scheduling assignment in UKG. The plugin validates scheduling data when submitting PTO — if an employee has no schedule configured, the request may fail. ### **d. Weekend PTO Handling** By default, this plugin is configured to reject PTO requests submitted on weekends (Saturday or Sunday) based on the user's local time. This is a plugin-level configuration, not a UKG platform behavior — UKG natively does not reject PTO requests on weekends. Customers can modify this behavior within the plugin to match their own PTO policies. For example, organizations with shift-based or 7-day work schedules may want to allow weekend PTO submissions. # **Implementation details** ## Visual Representation of How the Plugin Works ![image.png](Submit%20PTO%20Request/image.png) ## API Details Before running the cURL examples below, replace '' with your actual UKG hostname. **Admin Checklist: How to Find Your UKG Hostname** 1. Log in to your UKG account. 2. Check the URL in your browser's address bar. 3. Your hostname will follow one of these formats (examples): - `https://acme-dev.cfn.mykronos.com` - `https://acme-test.cfn.mykronos.com` - `https://acme-uat.cfn.mykronos.com` - `https://acme-prod.cfn.mykronos.com` Use the full hostname (e.g., `acme-prod.cfn.mykronos.com`) when replacing '' in the cURL commands. ### **API #1: Lookup Current User** This REST API retrieves the authenticated user's details in UKG, including their name, employee ID, person number, email, and time zone. This is the first call made when the plugin is triggered — it identifies who is making the request. ```bash curl --request GET \ --url 'https:///api/v1/commons/persons/current_user_info?include_contact_information=true' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' ``` **Query Parameters:** - `include_contact_information` *(boolean):* Set to `true` to include email, phone, and postal address in the response. **Key Fields Returned:** - `employeeId` *(integer):* The user's unique ID in UKG. - `personNumber` *(string):* The user's person number (used as an identifier in downstream API calls). - `userName` *(string):* The user's login username. - `firstName`, `lastName` *(string):* The user's name. - `emailContacts` *(array):* The user's email addresses (filtered by `contactType: "Work"`). - `timeZone` *(object):* The user's time zone details, used for weekend/date validation. ### **API #2: Retrieve Direct Reports** This REST API retrieves the current user's (manager's) direct reports from UKG WFM using a hyperfind query. Used when a manager is submitting PTO on behalf of a direct report. ```bash curl --request POST \ --url https:///api/v1/commons/hyperfind/execute \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "dateRange": { "symbolicPeriod": { "qualifier": "Current_Payperiod" } }, "hyperfind": { "qualifier": "My Direct Reports" } }' ``` **Key nuances:** - A hyperfind query named **"My Direct Reports"** must exist in the tenant. If it does not, please create one before using this plugin. Details on how to create a hyperfind query can be found [here](https://customer2.kronos.com/support/kol/onlinehelp-workforcedimensions/en-us/content/mastertopics/hyperfind/HyperFindqueries.htm). - The example uses the symbolic period `Current_Payperiod`, which must exist and be active in the tenant configuration. If your tenant uses a different symbolic period name, update the request body accordingly. **Key Fields Returned:** - `result.basePersons` *(array):* List of direct reports, each containing `personNumber`, `displayName`, `fullName`, and `personId`. - `count` *(integer):* Total number of direct reports returned. ### **API #3: Retrieve Leave Request Sub Types** This REST API fetches the available leave sub types for a specific employee. It is used to present leave type options (e.g., Vacation, Sick, Personal) to the user. The same endpoint serves both the employee and manager flows — when a manager submits on behalf of a direct report, the `person_number` of the direct report is passed. ```bash curl --request GET \ --url 'https:///api/v1/scheduling/timeoff/request_subtypes?person_number={{PERSON_NUMBER}}' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' ``` **Query Parameters:** - `PERSON_NUMBER` *(string):* The person number of the employee whose leave sub types are being retrieved. For the employee flow, this is the authenticated user's person number. For the manager flow, this is the direct report's person number. **Key Fields Returned:** - `name` *(string):* Display name of the leave sub type (e.g., "Vacation", "Sick"). - `description` *(string):* Description of the leave sub type. - `defaultPayCode` *(object):* The pay code associated with this sub type, including `qualifier` and `id`. The `id` is required when submitting the PTO request. - `requestType` *(object):* The parent request type category. ### **API #4: Retrieve Accrual Codes from Pay Codes** This REST API validates which pay codes have associated accrual policies. The plugin uses this to filter leave sub types — only sub types with valid accrual-based pay codes are presented to the user as available options. ```bash curl --request POST \ --url https:///api/v1/timekeeping/paycodes_to_accrual_codes/multi_read \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "timeframe_id": "Current_Payperiod", "paycodes": [ { "qualifier": "{{PAYCODE_QUALIFIER}}" } ], "employee": { "qualifier": "{{PERSON_NUMBER}}" } }' ``` **Query Parameters:** - `PAYCODE_QUALIFIER` *(string):* The qualifier of the pay code to validate (retrieved from API #3). - `PERSON_NUMBER` *(string):* The person number of the employee. **Key nuances:** - This API uses the symbolic period `Current_Payperiod` to determine the active accrual policies. Ensure this matches your tenant configuration. - Multiple pay codes can be passed in the `paycodes` array to validate in a single call. - The response includes `effectiveDatedAccrualCodes` for each pay code — if this array is empty, the leave type is not accrual-based and is filtered out by the plugin. ### **API #5: Submit a PTO Request as an Employee** This API submits a time off request as the authenticated employee. ```bash curl --request POST \ --url https:///api/v1/scheduling/employee_timeoff \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "requestSubType": { "name": "{{SUBTYPE_NAME}}" }, "periods": [ { "payCode": { "id": {{PAYCODE_ID}} }, "endDate": "{{END_DATE}}", "startTime": "{{START_TIME}}", "duration": {{DURATION}}, "startDate": "{{START_DATE}}", "symbolicAmount": { "qualifier": "HOURS" } } ], "commentNotes": [ { "comment": { "active": true, "name": "Request Comment" }, "notes": [ { "text": "{{COMMENT_TEXT}}", "dataSourceDisplayName": "{{USERNAME}}" } ] } ] }' ``` **Parameters:** - `SUBTYPE_NAME` *(string):* PTO leave type being requested (e.g., "Vacation"). - `PAYCODE_ID` *(integer):* The pay code ID associated with the leave sub type (from API #3). - `START_DATE` *(string):* Start date in `YYYY-MM-DD` format. - `END_DATE` *(string):* End date in `YYYY-MM-DD` format. - `START_TIME` *(string):* Start time in `HH:MM:SS.000` format (defaults to `09:00:00.000`). - `DURATION` *(integer):* Duration in hours (e.g., `8` for full day, `4` for half day). - `COMMENT_TEXT` *(string):* Optional comment text for the request. - `USERNAME` *(string):* The username of the employee submitting the request. **Key nuances:** - The `commentNotes` section is optional — it is only included in the payload when the employee provides a comment. - For multi-day requests, the compound action generates a separate period object for each day within the date range. ### **API #6: Submit a PTO Request as a Manager** This API submits a time off request on behalf of a direct report. The key difference from the employee flow is the `employee.id` field in the payload and the use of the manager-level endpoint. ```bash curl --request POST \ --url https:///api/v1/scheduling/timeoff \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "timeOffRequest": { "requestSubType": { "name": "{{SUBTYPE_NAME}}" }, "periods": [ { "payCode": { "id": {{PAYCODE_ID}} }, "endDate": "{{END_DATE}}", "startTime": "{{START_TIME}}", "duration": {{DURATION}}, "startDate": "{{START_DATE}}", "symbolicAmount": { "qualifier": "HOURS" } } ], "employee": { "id": {{PERSON_ID}} }, "commentNotes": [ { "comment": { "active": true, "name": "Request Comment" }, "notes": [ { "text": "{{COMMENT_TEXT}}", "dataSourceDisplayName": "{{USERNAME}}" } ] } ] } }' ``` **Parameters:** - `SUBTYPE_NAME` *(string):* PTO leave type being requested. - `PAYCODE_ID` *(integer):* The pay code ID (from API #3). - `START_DATE` *(string):* Start date in `YYYY-MM-DD` format. - `END_DATE` *(string):* End date in `YYYY-MM-DD` format. - `START_TIME` *(string):* Start time in `HH:MM:SS.000` format. - `DURATION` *(integer):* Duration in hours. - `PERSON_ID` *(integer):* The `personId` of the direct report (from API #2). - `COMMENT_TEXT` *(string):* Optional comment text. - `USERNAME` *(string):* The username of the employee the PTO is being submitted for. ### **API #7: Retrieve PTO Request by ID** This REST API fetches the details of a specific PTO request from UKG WFM using the PTO request ID. Used after submission to confirm the request details and status. ```bash curl --request GET \ --url 'https:///api/v1/scheduling/timeoff/{{PTO_ID}}?include_overridden_shifts=false' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' ``` **Parameters:** - `PTO_ID` *(string):* The ID of the PTO request to retrieve. **Key Fields Returned:** - `id` *(integer):* The PTO request ID. - `currentStatus` *(object):* Current approval status (e.g., "Pending", "Approved", "Refused"). - `requestSubType` *(object):* The leave type details. - `periods` *(array):* The date/time/duration details of the request. - `employee` *(object):* The employee the PTO was submitted for. - `approvalInfo` *(object):* Approval workflow details including `pendingSteps` and `approvalHistories`. - `commentNotes` *(array):* Any comments added to the request. ### API References This plugin uses **UKG WFM Pro Time Management REST APIs** to retrieve employee information, determine eligible PTO time types, validate accrual balances, and submit PTO requests. For detailed information on request parameters, response formats, error handling, and versioning, please refer to the [**official UKG API documentation**](https://developer.ukg.com/wfm/reference/welcome-to-the-ukg-pro-workforce-management-api) provided by UKG. # **What Is In Scope for This Plugin?** This plugin supports the following capabilities: - Submitting PTO for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time). Only leave types with valid accrual-based pay codes are presented as options. - Initiating a PTO request **on behalf of a direct report** if I am a manager (e.g., "Apply for a sick leave for John from my team on 5th and 6th Feb"). - Submitting leave requests for **both past and future dates** (e.g., to log unplanned absences, like sick leave or emergency time off, after they have already occurred). - Articulating the PTO dates and date ranges in **several formats** (e.g., Wednesday, 12th–15th Dec, Tuesday next week, 3rd week of Dec). - Requesting **partial time off** by specifying units if the leave type supports it (e.g., "half-day," "first-half", "second-half," or specific hours like "request 2 hours off tomorrow"). - Adding a **comment** while applying for PTO. - Clear messaging when attempting to submit a PTO request that **overlaps or conflicts** with an existing leave record or when there is **insufficient PTO balance** available. - Handling PTOs on **weekends**. The plugin is configured by default to reject PTO submitted on weekends (Saturday or Sunday) based on the user's local time. # **What Is Out of Scope for This Plugin?** This plugin does **not** support the following: - Submitting PTO for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability. - Submitting PTO for **public holidays**.