From 46628b309babe0ed8721f5bd0d07e53c15865b2c Mon Sep 17 00:00:00 2001 From: Jishnu Sripada Date: Fri, 10 Apr 2026 15:40:57 +0530 Subject: [PATCH 1/2] Fix UKG and SAP SF plugin guide errors - Update UKG connector URLs from /connectors/ukg to /connectors/ukg-pro-wfm across all 6 UKG plugins - Fix ukg-cancel-pto-request: correct pre-req text, Authorization header format (Bearer token), and replace "Workday" with "UKG WFM" in scope section - Fix ukg-view-pto-requests-and-calendar: correct plugin name in pre-req section - Fix sap-success-factors-cancel-pto-request: remove manager scope from description, replace incorrect API #3 key nuances with accurate PTO request details - Fix sap-success-factors-notify-pto-decision: grammar fix in scope section Co-Authored-By: Claude Sonnet 4.6 --- .../README.md | 16 +++++++++------- .../README.md | 2 +- plugins/ukg-approve-reject-time-off/README.md | 2 +- plugins/ukg-cancel-pto-request/README.md | 14 +++++++------- plugins/ukg-notify-on-pto-decision/README.md | 2 +- plugins/ukg-notify-on-pto-submission/README.md | 2 +- .../ukg-view-pto-requests-and-calendar/README.md | 4 ++-- plugins/ukg-view-time-off-balance/README.md | 2 +- 8 files changed, 23 insertions(+), 21 deletions(-) diff --git a/plugins/sap-success-factors-cancel-pto-request/README.md b/plugins/sap-success-factors-cancel-pto-request/README.md index 99a242e1..784d21a6 100644 --- a/plugins/sap-success-factors-cancel-pto-request/README.md +++ b/plugins/sap-success-factors-cancel-pto-request/README.md @@ -13,7 +13,7 @@ systems: # Description -The **“Cancel PTO Request”** plugin enables employees and managers to instantly cancel approved or pending PTO requests in **SAP SF** through the **Moveworks AI Assistant**, eliminating HR portal friction and ensuring time-off records stay accurate in real time. +The **”Cancel PTO Request”** plugin enables employees to instantly cancel their own approved or pending PTO requests in **SAP SF** through the **Moveworks AI Assistant**, eliminating HR portal friction and ensuring time-off records stay accurate in real time. # User Experience Preview @@ -140,12 +140,14 @@ curl -X GET "https:///odata/v2/EmployeeTime?$filter=(userId eq '{{use **Key nuances:** -- **Returns all leave types** - - The API returns both **limited** (PTO) and **non-limited** (e.g., leave of absence) time types. - - The plugin filters the response to include **only limited time types** eligible for PTO requests. -- **Effective-dated results** - - Available time types depend on the **“as of date”** passed to the API. - - Different dates may return different eligible PTO types due to policy changes or employee eligibility. +- **Returns both pending and approved requests** + - The API returns PTO requests with `PENDING` or `APPROVED` status only. + - Cancelled and rejected requests are excluded from the response. +- **Future-date filter for approved PTOs** + - Approved PTOs are only returned for future dates (where `startDate > today`). Past approved PTOs cannot be cancelled and are excluded. + - Pending PTOs are returned regardless of date. +- **Limited leave types only** + - The `externalCode` filter ensures only limited leave type PTOs are returned. The external codes must be derived from API #2 and injected dynamically into the query. ### **API #4: Cancel PTO Request** diff --git a/plugins/sap-success-factors-notify-pto-decision/README.md b/plugins/sap-success-factors-notify-pto-decision/README.md index 1f753ae8..cf70af85 100644 --- a/plugins/sap-success-factors-notify-pto-decision/README.md +++ b/plugins/sap-success-factors-notify-pto-decision/README.md @@ -159,7 +159,7 @@ This plugin supports the following capabilities: - Notifying PTO decisions for approval, rejection and cancellation of PTO request. - **Cancellation notifications** are sent when a PTO request is cancelled either by the employee themselves or by another authorized user (for example, a manager). - Note : Manager’s ability to Cancel a PTO Request for an Employee is dependent on org’s HRIS configuration. It is not a by-default setup, and hence, customers should enable this workflow/ setting in their HRIS at the time of installation of this plugin. -- Supports ****notifications for **every leave types** supported by SAP SF. +- Supports notifications for **all leave types** supported by SAP SF. - Supports single and multi level approvals. However, for multi level approvals, notification will be triggered on final approval status change of PTO. # **What Is Out of Scope for This Plugin?** diff --git a/plugins/ukg-approve-reject-time-off/README.md b/plugins/ukg-approve-reject-time-off/README.md index 0ce403ed..689fa77a 100644 --- a/plugins/ukg-approve-reject-time-off/README.md +++ b/plugins/ukg-approve-reject-time-off/README.md @@ -27,7 +27,7 @@ Before installing and using the **Approve or Reject** **PTO** plugin, please ens This plugin requires an active **UKG connector** with **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)** available in the Moveworks Marketplace. +- 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**. diff --git a/plugins/ukg-cancel-pto-request/README.md b/plugins/ukg-cancel-pto-request/README.md index da8e0b3b..c98d7f5c 100644 --- a/plugins/ukg-cancel-pto-request/README.md +++ b/plugins/ukg-cancel-pto-request/README.md @@ -27,7 +27,7 @@ Before installing and using the **Cancel PTO Request** plugin, please ensure the This plugin requires an active **UKG connector** and **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) available in the Moveworks Marketplace. +- 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**. @@ -38,7 +38,7 @@ This plugin requires an active **UKG connector** and **user consent auth** to co ### **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 request through the UKG WFM UI. +To cancel a PTO request through this plugin, employees must already have permission to cancel PTO requests in UKG WFM — the same permissions required to cancel a PTO request through the UKG WFM UI. At a minimum, end users must have: @@ -88,7 +88,7 @@ This REST API is used to **retrieve current user details** in UKG WFM. This is u ```bash curl --request GET \ --url 'https:///api/v1/commons/persons/current_user_info?include_contact_information=true' \ - --header 'Authorization: ' \ + --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' ``` @@ -103,7 +103,7 @@ This API is used to **retrieve pending PTO requests** in UKG which will be used ```bash curl --request POST \ --url https:///api/v1/scheduling/timeoff/multi_read \ - --header 'Authorization: ' \ + --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "where": { @@ -132,7 +132,7 @@ This API is used to **retrieve approved PTO requests** in UKG WFM which will be ```bash curl --request POST \ --url https:///api/v1/scheduling/timeoff/multi_read \ - --header 'Authorization: ' \ + --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "where": { @@ -161,7 +161,7 @@ This API is used to update the status of PTO requests in UKG WFM. Specifically, ```bash curl --request POST \ --url https:///api/v1/scheduling/timeoff/apply_update \ - --header 'Authorization: ' \ + --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "changeState": { @@ -208,7 +208,7 @@ This plugin supports the following capabilities: - Cancelling PTO requests for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time). - Cancelling approved or pending requests for an **employee’s own PTO only**. -- Cancelling PTO requests that respect **existing Workday policies, validations, and approval workflows**. +- Cancelling PTO requests that respect **existing UKG WFM policies, validations, and approval workflows**. # **What Is Out of Scope for This Plugin?** diff --git a/plugins/ukg-notify-on-pto-decision/README.md b/plugins/ukg-notify-on-pto-decision/README.md index c5c3dfcd..c8040d9c 100644 --- a/plugins/ukg-notify-on-pto-decision/README.md +++ b/plugins/ukg-notify-on-pto-decision/README.md @@ -30,7 +30,7 @@ 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) available in the Moveworks Marketplace. Both connectors must be fully set up before installing this plugin. +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**. diff --git a/plugins/ukg-notify-on-pto-submission/README.md b/plugins/ukg-notify-on-pto-submission/README.md index 2a7a249d..5f603659 100644 --- a/plugins/ukg-notify-on-pto-submission/README.md +++ b/plugins/ukg-notify-on-pto-submission/README.md @@ -30,7 +30,7 @@ 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) available in the Moveworks Marketplace. Both connectors must be fully set up before installing this plugin. +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**. diff --git a/plugins/ukg-view-pto-requests-and-calendar/README.md b/plugins/ukg-view-pto-requests-and-calendar/README.md index 36605191..b2b17dc4 100644 --- a/plugins/ukg-view-pto-requests-and-calendar/README.md +++ b/plugins/ukg-view-pto-requests-and-calendar/README.md @@ -21,13 +21,13 @@ Please refer to the following [**Purple Chat**](https://marketplace.moveworks.co # Pre-requisites -Before installing and using the **PTO Search** plugin, please ensure the following requirements are met: +Before installing and using the **View PTO Requests & Calendar** plugin, please ensure the following requirements are met: ## **1. UKG Connector** This plugin requires an active **UKG connector** and **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) available in the Moveworks Marketplace. +- 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**. diff --git a/plugins/ukg-view-time-off-balance/README.md b/plugins/ukg-view-time-off-balance/README.md index 265c7690..dafb0c1a 100644 --- a/plugins/ukg-view-time-off-balance/README.md +++ b/plugins/ukg-view-time-off-balance/README.md @@ -27,7 +27,7 @@ Before installing and using the **Check PTO Balance** plugin, please ensure the This plugin requires an active **UKG connector** and **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)** available in the Moveworks Marketplace. +- 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**. From 0a9450b68de341c34297e88e29a9c0f8ca0bbdc3 Mon Sep 17 00:00:00 2001 From: Jishnu Sripada Date: Thu, 16 Apr 2026 15:05:28 +0530 Subject: [PATCH 2/2] Workday Plugin Guide Changes --- .../workday-approve-reject-time-off/README.md | 83 ++++++++----- plugins/workday-pto-lookups/README.md | 67 ++++++++--- plugins/workday-request-time-off/README.md | 109 ++++++++++++------ 3 files changed, 177 insertions(+), 82 deletions(-) diff --git a/plugins/workday-approve-reject-time-off/README.md b/plugins/workday-approve-reject-time-off/README.md index 8b0dd4fb..ac90af09 100644 --- a/plugins/workday-approve-reject-time-off/README.md +++ b/plugins/workday-approve-reject-time-off/README.md @@ -26,55 +26,70 @@ Before installing and using the **Approve or Reject PTO Request** plugin, please ## **1. Workday Connector** -This plugin requires an active **Workday connector** using **OAuth 2.0 (User consent Auth)** to communicate with your Workday instance. +This plugin requires an active **Workday connector** using **OAuth 2.0 (User Consent Auth / Authorization Code Grant)** to communicate with your Workday instance. All four API calls in this plugin — including the WQL query, REST event lookup, and SOAP approve/deny actions — execute under the authenticated **manager's own Workday identity**. No Integration System User (ISU) is required. - If you have not already configured the connector, please follow the [Workday Connector Guide](https://marketplace.moveworks.com/connectors/workday#how-to-implement) available in the Moveworks Marketplace. -- The connector must be fully set up and 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**. +- 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: User ingestion must be configured and operational. Without this step, users will not be able to use the plugin. -> +> **Note:** User ingestion must be configured and operational. Without this step, users will not be able to use the plugin. ## **2. Workday System Requirements** -### **a. End User Permissions (Manager Persona)** +The following configuration must be completed by a **Workday Administrator** before this plugin can function correctly. These are Workday-side requirements that govern what the authenticated manager is permitted to do via API. -To approve or reject a PTO request through this plugin, managers must already have permission to approve or reject time off in Workday — the same permissions required to approve or reject through the Workday UI. +### **a. OAuth 2.0 API Client — Functional Area Scopes** -At a minimum, managers must have: +The OAuth 2.0 (Authorization Code Grant) API Client registered in Workday must include the following **Functional Area Scopes**. These are required for the manager to query pending PTO requests via WQL (API #1), retrieve event details (API #2), and execute approve/deny actions via SOAP APIs (APIs #3 and #4): -- **Time Off permissions** that allow: - - Viewing available Time Off Types - - Approving and rejecting Time Off / PTO requests -- Access to their **team member profiles and time account balances** -- Eligibility to approve or reject PTO requests based on company time-off policies +- **Staffing** +- **Time Off and Leave** +- **System** +- **Tenant Non-Configurable** +- **Public Data** +- **Worktags** -> Note: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in Workday. -> +To verify: Search **"Register API Client for Integrations"** in Workday → locate the API Client used by the Moveworks connector → confirm all of the above are listed under **Scope (Functional Areas)**. -### **b. API Permissions (via Integration User)** +### **b. Domain Security — Approve Business Process (Web Service)** -The Workday connector uses an **Integration Systems User (ISU)** to process PTO requests through Workday APIs. +For managers to approve or reject a PTO request via the SOAP APIs (APIs #3 and #4), the **Manager** security group must have the correct domain security access to the Approve Business Process web service. -That admin/integration user must have permissions to: +- The **"Approve Business Process (Web Service)"** securable item must grant **Put** access to the Manager security group (or "All Users"). -- View Time Off requests on behalf of employees -- Read Time Off Types and Time Account information -- Validate employee eligibility and balances (as required by your configuration) -- Approve or reject Time Off requests on behalf of managers +To verify: +1. Search **"View Security for Securable Item"** in Workday +2. Search for **"Approve"** +3. Click **"View Security"** on **"Approve Business Process (Web Service) (Web Service Task)"** +4. Confirm the **Manager** security group (or "All Users") has **Put** access listed -These permissions are typically configured through **Create Integration System User (ISU)** Workday Task. +### **c. Business Process Security Policy — Request Time Off** + +For the manager's approve or reject action to be recognized by Workday's business process engine, the **"Review Time Off Request"** action step in the "Request Time Off" business process must include the Manager and/or Management Chain security groups. + +To verify: +1. Search **"View Business Process Security Policy"** in Workday +2. Select **"Request Time Off"** under **Time Off and Leave** +3. Scroll to **"Who Can Do Action Steps in the Business Process"** +4. Confirm **Manager** and/or **Management Chain** is listed under the **Review** step + +### **d. Activate Pending Security Policy Changes** + +After making any changes to Domain Security Policies or Business Process Security Policies in Workday: + +- Search **"Activate Pending Security Policy Changes"** in Workday and run it. + +> **Important:** Security changes in Workday do **not** take effect until this step is completed. If the plugin is not working as expected after configuring permissions above, ensure this step has been run. ## **3. Workday User Identity Ingestion** -This plugin requires User Identity Ingestion from workday in Moveworks. For Moveworks to complete actions across systems on the behalf of a user, it needs to have knowledge of all of the system IDs for the given user. -Setup information for User identity can be found on [https://help.moveworks.com/docs/user-identity](https://help.moveworks.com/docs/user-identity). +This plugin requires User Identity Ingestion from Workday in Moveworks. For Moveworks to complete actions across systems on behalf of a user, it needs to have knowledge of all system IDs for the given user. Setup information for User Identity can be found on [https://help.moveworks.com/docs/user-identity](https://help.moveworks.com/docs/user-identity). -Below mandatory attributes are needed from this user ingestion. +The following attributes are required from this user ingestion: -1. Workday ID of the user. -2. Organization id of the user. -3. Organization managed by the user. +1. Workday ID of the user +2. Organization ID of the user +3. Organization managed by the user # **Implementation details** @@ -110,6 +125,8 @@ The (tenantUrl) and (tenantName) in this URL are your **true This API is used to retrieve details of all PTO requests submitted by direct reports that require attention by the given manager (refer to Query Parameters below). +**Authentication:** User Consent Auth (OAuth 2.0 Authorization Code Grant). The query executes under the manager's own Workday identity — no ISU required. + ```bash curl -X POST "https:///ccx/api/wql/v1//data" \ -H "Content-Type: application/json" \ @@ -143,7 +160,9 @@ curl -X POST "https:///ccx/api/wql/v1//data" \ ### **API #2: Fetches the details of the Event from the Event_Id** -This API retrieves additional details for a specific PTO request. The timeOffEvent value retrieved from API#1 that is passed in as`EVENT_WID` parameter to return the required details. +This API retrieves additional details for a specific PTO request. The timeOffEvent value retrieved from API#1 that is passed in as `EVENT_WID` parameter to return the required details. + +**Authentication:** User Consent Auth (OAuth 2.0 Authorization Code Grant). Executes under the manager's own Workday identity — no ISU required. ```bash curl -X GET "https:///api/businessProcess/v1//events/{{event_wid}}" \ @@ -158,6 +177,8 @@ curl -X GET "https:///api/businessProcess/v1//events/{{ev This API will approve a PTO request based on the timeOffEvent value retrieved from API#1 that is passed in as `EVENT_WID` parameter. +**Authentication:** User Consent Auth (OAuth 2.0 Authorization Code Grant). The SOAP call executes under the manager's own Workday identity — no ISU or task reassignment required. + ```bash curl -X POST "https:///ccx/service//Integrations/v41.2" \ -H "Content-Type: text/xml" \ @@ -175,6 +196,8 @@ curl -X POST "https:///ccx/service//Integrations/v41.2" \ This API will reject a PTO request based on the timeOffEvent value retrieved from API#1 that is passed in as `EVENT_WID` parameter. +**Authentication:** User Consent Auth (OAuth 2.0 Authorization Code Grant). The SOAP call executes under the manager's own Workday identity — no ISU or task reassignment required. + ```bash curl -X POST "/ccx/service//Integrations/v41.2" \ -H "Content-Type: text/xml" \ diff --git a/plugins/workday-pto-lookups/README.md b/plugins/workday-pto-lookups/README.md index e622e94e..7ee3395e 100644 --- a/plugins/workday-pto-lookups/README.md +++ b/plugins/workday-pto-lookups/README.md @@ -27,37 +27,70 @@ Before installing and using the **Check PTO Balance** plugin, please ensure the ## **1. Workday Connector** -This plugin requires an active Workday connector ([**OAuth 2.0 with Authorization Code (User Consent Auth) Setup](https://marketplace.moveworks.com/connectors/workday#OAuth-2.0-with-Authorization-Code-(User-Consent-Auth)-Setup))** to communicate with your Workday instance. +This plugin requires an active Workday connector ([**OAuth 2.0 with Authorization Code (User Consent Auth) Setup**](https://marketplace.moveworks.com/connectors/workday#OAuth-2.0-with-Authorization-Code-(User-Consent-Auth)-Setup)) to communicate with your Workday instance. All API calls in this plugin execute under the authenticated **employee's own Workday identity**. No Integration System User (ISU) is required. - If you have not already configured the connector, please follow the [Workday Connector Guide](https://marketplace.moveworks.com/connectors/workday#how-to-implement) available in the Moveworks Marketplace. -- The connector must be fully set up and 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. +- 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. ## **2. Workday System Requirements** -### **a. End User Permissions** +The following configuration must be completed by a **Workday Administrator** before this plugin can function correctly. These are Workday-side requirements that govern what the authenticated employee is permitted to access via API. -To check PTO balances through this plugin, employees must already have permission to view time off balances in Workday — the same permissions required to view balances through the Workday UI. +> **Note:** The plugin does not grant new permissions. It respects existing role-based permissions and policies already granted to the user in Workday. -At a minimum, users must have: +### **a. OAuth 2.0 API Client — Functional Area Scopes** -- The ability to view available Time Off types. -- Eligibility to access time off plans and balances in accordance with company time‑off policies. +The OAuth 2.0 (Authorization Code Grant) API Client registered in Workday must include the following **Functional Area Scopes**. These are required for the employee to query their own worker data and time off balances via WQL: -> Note: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in Workday. -> +- **Staffing** +- **Time Off and Leave** +- **System** +- **Tenant Non-Configurable** +- **Public Data** +- **Worktags** -### **b. API Permissions (via Integration User)** +To verify: Search **"Register API Client for Integrations"** in Workday → locate the API Client used by the Moveworks connector → confirm all of the above are listed under **Scope (Functional Areas)**. -The Workday connector uses an Integration Systems User (ISU) to retrieve PTO balance data through Workday APIs. +### **b. Domain Security — WQL for Workday Extend** -That user must have permissions to: +This plugin uses WQL to retrieve worker data and time off balances. For employees authenticating via OAuth (User Consent Auth) to run WQL queries through the API, the following access is required: -- Read worker profiles (via WQL `allWorkers`) -- Read Time Off plan eligibility and balances (including accrual-related fields) -- Validate employee eligibility and balances (as required by your configuration) +- **WQL for Workday Extend** domain → under **Integration Permissions**: **Employee As Self** must have **Get** and **Put** access. -These permissions are typically configured through Create Integration System User (ISU) Workday Task. +To configure: +1. Search **"Edit Domain Security Policy"** in Workday +2. Search **"WQL for Workday Extend"** +3. Under **Integration Permissions**, add **Employee As Self** with **Get** and **Put** access +4. Save + +> **Note:** By default, only ISU/ISSG groups have integration access to this domain. If Employee As Self is not listed, OAuth-authenticated users will receive 403 errors or empty results on all WQL queries. + +### **c. Domain Security — Worker Data: Public Worker Reports** + +This domain controls access to base worker data (name, email, Workday ID) used to identify the authenticated employee in WQL queries. + +- **Worker Data: Public Worker Reports** domain → **All Employees** must have **Report/Task View** access. + +To verify: Search **"Domain Security Policy Summary"** in Workday → search **"Worker Data: Public Worker Reports"** → confirm **All Employees** has **Report/Task View** access listed. + +> **Note:** If this permission is missing, WQL queries run without error but return zero rows — no error message, just empty results. + +### **d. Domain Security — Worker Data: Time Off** + +This domain controls access to time off plan data, balances, and accrual information — the core data returned by this plugin. + +- **Worker Data: Time Off** domain → under **Integration Permissions**: **Employee As Self** must have **Get** access. + +To verify: Search **"Domain Security Policy Summary"** in Workday → search **"Worker Data: Time Off"** → confirm **Employee As Self** has **Get** access under Integration Permissions. + +### **e. Activate Pending Security Policy Changes** + +After making any changes to Domain Security Policies in Workday: + +- Search **"Activate Pending Security Policy Changes"** in Workday and run it. + +> **Important:** Security changes in Workday do **not** take effect until this step is completed. This is the most common reason for "I changed the permission but it still doesn't work." # **Implementation details** diff --git a/plugins/workday-request-time-off/README.md b/plugins/workday-request-time-off/README.md index 0cd7fade..b5e43522 100644 --- a/plugins/workday-request-time-off/README.md +++ b/plugins/workday-request-time-off/README.md @@ -25,64 +25,103 @@ Before installing and using the **Submit PTO Request** plugin, please ensure the ## **1. Workday Connector** -This plugin requires an active Workday connector to communicate with your Workday instance. We recommend creating a connector which utilizes **OAuth 2.0 with Authorization Code Grant Type flow**. +This plugin requires an active Workday connector using **OAuth 2.0 with Authorization Code Grant Type (User Consent Auth)** to communicate with your Workday instance. All API calls in this plugin — including WQL queries, REST lookups, and the SOAP PTO submission — execute under the authenticated **employee's or manager's own Workday identity**. No Integration System User (ISU) is required. - If you have not already configured the connector, please follow the [Workday Connector Guide](https://marketplace.moveworks.com/connectors/workday#oauth-2-0-with-authorization-code-user-consent-auth-setup) available in the Moveworks Marketplace. -- The connector must be fully set up and 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. +- 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. ## **2. Workday System Requirements** -### **a. End User Permissions (Employee Persona)** +The following configuration must be completed by a **Workday Administrator** before this plugin can function correctly. These are Workday-side requirements that govern what the authenticated employee or manager is permitted to do via API. -To submit a PTO request through this plugin, employees must already have permission to submit time off in Workday — the same permissions required to submit through the Workday UI. +> **Note:** The plugin does not grant new permissions. It respects existing role-based permissions and policies already granted to the user in Workday. -At a minimum, employees and managers must have: +### **a. OAuth 2.0 API Client — Functional Area Scopes** -- **Time Off permissions** that allow: - - Viewing available Time Off Types - - Creating Time Off / PTO requests -- Access to their own **employee profiles and time account balances** -- Eligibility to submit PTO requests based on company time-off policies +The OAuth 2.0 (Authorization Code Grant) API Client registered in Workday must include the following **Functional Area Scopes**. These are required to look up worker details, retrieve eligible leave types, and submit PTO requests via WQL, REST, and SOAP APIs: -Note: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in Workday. +- **Staffing** +- **Time Off and Leave** +- **System** +- **Tenant Non-Configurable** +- **Public Data** +- **Worktags** +- **Organizations and Roles** *(required for fetching direct report lists)* -### **b. End User Permissions (Manager Persona)** +To verify: Search **"Register API Client for Integrations"** in Workday → locate the API Client used by the Moveworks connector → confirm all of the above are listed under **Scope (Functional Areas)**. -To submit PTO request for direct reports through this plugin, managers must already have permission to submit time off in Workday — the same permissions required to submit through the Workday UI. +### **b. Domain Security — WQL for Workday Extend** -At a minimum, managers must have: +This plugin uses WQL to look up worker details by email. For employees and managers authenticating via OAuth (User Consent Auth) to run WQL queries through the API, the following access is required: -- Time Off permissions that allow: - - Viewing available Time Off Types of their direct reports - - Creating Time Off / PTO requests of their direct reports -- Access to their team member profiles and time account balances -- Eligibility to submit requests for their direct reports based on company time-off policies +- **WQL for Workday Extend** domain → under **Integration Permissions**: **Employee As Self** and **Manager** must each have **Get** and **Put** access. - Note: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in Workday. +To configure: +1. Search **"Edit Domain Security Policy"** in Workday +2. Search **"WQL for Workday Extend"** +3. Under **Integration Permissions**, add **Employee As Self** (Get + Put) and **Manager** (Get + Put) +4. Save -### **c. API Permissions** +> **Note:** By default, only ISU/ISSG groups have integration access to this domain. If these security groups are not listed, OAuth-authenticated users will receive 403 errors or empty results on WQL queries. -The Workday connector uses the Workday API Client to process PTO requests through Workday APIs. The API Client must have the following permissions (or their equivalent in your tenant): +### **c. Domain Security — Worker Data: Public Worker Reports** -- Organizations and Roles -- Public Data -- Staffing -- System -- Tenant Non-Configurable -- Time Off and Leave -- Worktags +This domain controls access to base worker data (name, email, Workday ID) used to resolve the authenticated user or their direct reports in WQL. -These permissions are typically configured through the Register API Client task. +- **Worker Data: Public Worker Reports** domain → **All Employees** must have **Report/Task View** access. + +To verify: Search **"Domain Security Policy Summary"** in Workday → search **"Worker Data: Public Worker Reports"** → confirm **All Employees** has **Report/Task View** access. + +> **Note:** If this permission is missing, WQL queries return zero rows with no error — requests appear to succeed but no worker data is returned. + +### **d. Domain Security — Worker Data: Time Off** + +This domain controls access to time off plan data and eligibility — required for the plugin to retrieve available leave types and validate balances before submission. + +- **Worker Data: Time Off** domain → under **Integration Permissions**: + - **Employee As Self** must have **Get** access *(for viewing own leave types and balance)* + - **Manager** must have **Get** access *(for viewing direct report data when submitting on behalf of another employee)* + +To verify: Search **"Domain Security Policy Summary"** in Workday → search **"Worker Data: Time Off"** → confirm the above groups and access levels under Integration Permissions. + +### **e. Business Process Security Policy — Request Time Off** + +For PTO submissions to succeed through the SOAP API (API #4), the "Request Time Off" business process must be configured to permit both employee self-service and manager on-behalf-of submissions. + +Search **"View Business Process Security Policy"** in Workday → select **"Request Time Off"** under **Time Off and Leave**, then verify the following: + +**Section: "Who Can Start the Business Process"** + +Look for these initiation actions and confirm the security groups listed under each: + +- **"Enter Time Off (Web Service)"** → **Employee As Self** must be listed. + This is the initiation path used by the SOAP API when an employee submits their own PTO. If missing, API submissions fail for employees. +- **"Request Time Off for a Worker"** → **Management Chain** (or **Manager**) must be listed. + This allows a manager to submit PTO on behalf of a direct report. Expand "More" if the full list is collapsed. +- **"Request Time Off for Self"** → **Employee As Self** should be listed. + This covers the self-service submission path. + +**Section: "Who Can Do Action Steps in the Business Process"** + +- **Action Step: "Review Time Off Request"** → **Manager** and/or **Management Chain** must be listed under Security Groups. + This is the approval routing step. Without it, submitted PTO requests will not route to the manager for approval. Expand "More" to see the full list. + +### **f. Activate Pending Security Policy Changes** + +After making any changes to Domain Security Policies or Business Process Security Policies in Workday: + +- Search **"Activate Pending Security Policy Changes"** in Workday and run it. + +> **Important:** Security changes in Workday do **not** take effect until this step is completed. This is the most common reason for "I changed the permission but it still doesn't work." ## **3. Workday User Identity Ingestion** -This plugin requires User Identity Ingestion from workday in Moveworks. For Moveworks to complete actions across systems on the behalf of a user, it needs to have knowledge of all of the system IDs for the given user. -Setup information for User identity can be found on https://help.moveworks.com/docs/user-identity. +This plugin requires User Identity Ingestion from Workday in Moveworks. For Moveworks to complete actions across systems on behalf of a user, it needs to have knowledge of all system IDs for the given user. Setup information for User Identity can be found on [https://help.moveworks.com/docs/user-identity](https://help.moveworks.com/docs/user-identity). -Below mandatory attributes are needed from this user ingestion. +The following attribute is required from this user ingestion: -1. workday ID of the user. +1. Workday ID of the user This attribute is utilized in the input mapping of the target_report_id slot's resolver strategy as shown below. Depending on your ingestion configuration, you might need to change this to point to the user's workday_id.