From a0509d2fa15bfb178773fe0f3a058960a7f6b7f3 Mon Sep 17 00:00:00 2001 From: Vedika Gupta Date: Wed, 28 Jan 2026 18:06:35 +0530 Subject: [PATCH] readMe for workday scenarios --- .../EmployeeGetVacationBalance/README.md | 166 +++++++++++ .../WorkdayEmployeeRequestTimeOff/README.md | 252 ++++++++++++++++ .../README.md | 203 +++++++++++++ .../WorkdayGetContactInformation/README.md | 262 +++++++++++++++++ .../WorkdayGetEducation/README.md | 268 ++++++++++++++++++ .../WorkdayGetGovernmentIDs/README.md | 216 ++++++++++++++ .../WorkdayGivePeerFeedback/README.md | 201 +++++++++++++ .../README.md | 244 ++++++++++++++++ .../README.md | 216 ++++++++++++++ .../README.md | 217 ++++++++++++++ .../README.md | 247 ++++++++++++++++ 11 files changed, 2492 insertions(+) create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeeRequestTimeOff/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeesviewtheirjobtaxonomy/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetContactInformation/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetEducation/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetGovernmentIDs/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGivePeerFeedback/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagerServiceAnniversary/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CompanyCode/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CostCenter/README.md create mode 100644 EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-Jobtaxanomy/README.md diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/README.md new file mode 100644 index 00000000..8e2da442 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/README.md @@ -0,0 +1,166 @@ +# Workday Get Vacation Balance + +## Overview +This scenario enables employees to view their time off plan balances from Workday. It retrieves vacation, sick leave, and other time off balances for a specified effective date and presents them in a user-friendly format. + +## Features + +- **Date Selection**: Prompts user to select an as-of date via Adaptive Card (defaults to today) +- **Automatic Date Detection**: If user includes a date in their request, it's automatically extracted +- **Multiple Plans**: Displays all time off plan balances (vacation, sick leave, PTO, etc.) +- **AI-Formatted Response**: Uses AI to format the response in a friendly, readable way + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and Power Fx logic | +| `msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml` | XML template for Workday Get_Time_Off_Plan_Balances API call | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID + +### Workday API +- **Service**: Absence_Management +- **Operation**: Get_Time_Off_Plan_Balances +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What is my vacation │ +│ balance?") │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Date in │ + │ request? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ Use provided │ │ Show date │ +│ date │ │ picker card │ +└──────┬───────┘ └──────┬───────┘ + │ │ + └───────┬────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Workday API │ +│ (Get_Time_Off_Plan_Balances) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ AI formats response │ +│ (Friendly, user-focused) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Display vacation balances │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "What is my vacation balance?" +- "How much time off can I take?" +- "What is my workday vacation balance?" +- "Show my PTO balance" +- "How many vacation days do I have left?" + +## Data Retrieved + +| Field | Description | XPath | +|-------|-------------|-------| +| RemainingBalance | Available balance for the time off plan | `.//Time_Off_Plan_Balance/text()` | +| PlanDescriptor | Name of the time off plan (e.g., "Vacation", "Sick Leave") | `.//Time_Off_Plan_Reference/@Descriptor` | +| PlanID | Unique identifier for the plan (hidden from user) | `.//ID[@type='Absence_Plan_ID']/text()` | +| UnitOfTime | Unit of measurement (Hours, Days) | `.//Unit_of_Time_Reference/@Descriptor` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{As_Of_Effective_Date}` | Date to check balance (YYYY-MM-DD) | `2026-01-28` | + +## Topic Input Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `AsOfEffectiveDate` | DateTime | No | The effective date for balance lookup. If not provided, user is prompted to select a date. | + +## Adaptive Card: Date Picker + +The topic displays an Adaptive Card with a date picker when no date is provided: + +| Element | Type | Default Value | +|---------|------|---------------| +| Date Selector | Input.Date | Today's date | +| Submit Button | Action.Submit | "Submit" | + +## AI Response Formatting + +The response is formatted by AI with these instructions: +- Display each vacation balance on a separate line +- Highlight the vacation plan name +- Include the as-of date in the response +- Never include the Plan ID +- Format in a friendly, conversational way +- Tie response back to the user's original question + +## Example Interaction + +**User**: "What is my vacation balance?" + +**Agent** displays date picker card: +> Which date would you like to check your vacation balance for? +> [Date: 2026-01-28] [Submit] + +**User** submits with selected date + +**Agent**: +> As of **January 28, 2026**, here are your time off balances: +> +> **Vacation**: 80 Hours +> **Sick Leave**: 40 Hours +> **Personal Time**: 16 Hours + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_Employee_Id` is populated (typically from user authentication context) + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_Employee_Id` - Current user's employee ID + +## Model Instructions + +The topic includes model instructions to: +- Only respond to requests about the user's own vacation balance +- Reject requests about other employees' balances +- Retrieve data exclusively from Workday + +### Invalid Requests (Rejected) +- "What is my manager's vacation balance?" +- "What is my sister's vacation balance?" +- "Show [EmployeeName]'s PTO balance" + +### Valid Requests (Accepted) +- "What is my vacation balance?" +- "How much time off can I take?" +- "What is my workday vacation balance?" diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeeRequestTimeOff/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeeRequestTimeOff/README.md new file mode 100644 index 00000000..950769f2 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeeRequestTimeOff/README.md @@ -0,0 +1,252 @@ +# Workday Employee Request Time Off + +## Overview +This scenario enables employees to submit time off requests directly through the Copilot agent. It collects the necessary information (date, hours, type, and reason) via an Adaptive Card form and submits the request to Workday's Absence Management system. + +## Features + +- **Automatic Input Extraction**: If user includes date, hours, or reason in their request, they're automatically extracted +- **Time Off Types**: Supports multiple time off types (Vacation, Sick, Floating Holiday) +- **Validation**: Form validation ensures all required fields are provided +- **Access Control**: Verifies the user can only request time off for themselves +- **Cancel Support**: User can cancel the request before submission + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases, Adaptive Card form, and submission logic | +| `msdyn_HRWorkdayAbsenceEnterTimeOff_EnterTimeOffInfo.xml` | XML template for Workday Enter_Time_Off API call | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID + +### Environment Variables +- `Env.WorkdayWebsiteRedirectMessage` - Optional message shown after successful submission (e.g., link to Workday portal) + +### Workday API +- **Service**: Absence_Management +- **Operation**: Enter_Time_Off +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "Request time off") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Access Check │ +│ (Verify user is requesting for │ +│ themselves only) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Display Time Off Form │ +│ (Adaptive Card with pre-filled │ +│ values if provided in request) │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Cancel? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ End dialog │ │ Submit to │ +│ with cancel │ │ Workday API │ +│ message │ │ │ +└──────────────┘ └──────┬───────┘ + │ + ▼ + ┌──────┴──────┐ + │ Success? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ Show error │ │ Show success │ + │ message │ │ message │ + └──────────────┘ └──────────────┘ +``` + +## Trigger Phrases + +- "Request time off" +- "I need to submit time off" +- "Please request 8 hours time off on 2025-09-15 because of a family event" +- "Request 4 hours vacation on December 1st" +- "Submit vacation request" +- "I want to take a day off" + +## Topic Input Parameters + +The topic supports automatic extraction of these parameters from the user's request: + +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `TimeOffDate` | DateTime | Date of time off (yyyy-mm-dd) | `2026-01-30` | +| `NumberOfHours` | Number | Number of hours requested | `8` | +| `ReasonText` | String | Free text reason for time off | `Family event` | +| `EmployeeName` | String | Name mentioned (used for access check) | `John Smith` | + +## Adaptive Card Form Fields + +| Field | Type | Required | Validation | Default | +|-------|------|----------|------------|---------| +| Type of Time Off | Dropdown | Yes | Must select one | - | +| Date | Date Picker | Yes | Cannot be in the past | Pre-filled if provided | +| Number of Hours | Number Input | Yes | Min: 0.5, Max: 24 | 8 hours | +| Reason | Text Input | Yes | Max 500 characters | Pre-filled if provided | + +### Supported Time Off Types + +| Display Name | Value (Time_Off_Type_ID) | +|--------------|--------------------------| +| Floating Holiday | `Floating_Holiday_Hours` | +| Vacation | `Vacation_Hours` | +| Sick | `Sick_Hours` | + +> **Note**: To add more time off types, update the `choices` array in the `timeOffType` Input.ChoiceSet within the Adaptive Card in `topic.yaml`. + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{Time_Off_Date}` | Date of time off (YYYY-MM-DD) | `2026-01-30` | +| `{Hours}` | Number of hours requested | `8` | +| `{Reason_ID}` | Time Off Type ID | `Vacation_Hours` | +| `{Comment}` | Reason/comment text | `Family event` | + +## Response Data + +| Field | Description | XPath | +|-------|-------------|-------| +| WID | Workday Internal ID of the created time off event | `//*[local-name()='Time_Off_Event_Reference']/*[local-name()='ID' and @type='WID']` | + +## Business Process Configuration + +The XML template configures the Workday business process with: + +| Setting | Value | Description | +|---------|-------|-------------| +| `Auto_Complete` | false | Request goes through approval workflow | +| `Run_Now` | true | Submit immediately | +| `Discard_On_Exit_Validation_Error` | true | Discard if validation fails | + +## Example Interactions + +### Example 1: Basic Request +**User**: "I want to request time off" + +**Agent** displays form: +> **Request Time Off** +> Enter the date, hours, and reason for your time off request. +> +> Type of Time Off: [Dropdown] +> Date: [Date Picker] +> Number of Hours: [8] +> Reason: [Text Input] +> +> [Submit] [Cancel] + +**User** fills form and submits + +**Agent**: "Your time off request has been submitted." + +--- + +### Example 2: Pre-filled Request +**User**: "Request 4 hours vacation on January 30th for a doctor's appointment" + +**Agent** displays form with pre-filled values: +> Type of Time Off: [Dropdown] +> Date: [2026-01-30] +> Number of Hours: [4] +> Reason: [doctor's appointment] + +--- + +### Example 3: Cancelled Request +**User** clicks Cancel + +**Agent**: "Your request has been cancelled. Is there anything else you need help with?" + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayAbsenceEnterTimeOff_EnterTimeOffInfo.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_Employee_Id` is populated from user authentication +5. **Configure Environment Variable** (Optional): Set `Env.WorkdayWebsiteRedirectMessage` for post-submission guidance + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemAccessCheck` - Verifies user access permissions +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_Employee_Id` - Current user's employee ID + +## Model Instructions + +The topic includes model instructions to: +- Only respond to requests for the user's own time off +- Reject requests to submit time off for other employees +- Prompt for input if date, hours, or reason are missing + +### Invalid Requests (Rejected) +- "Request time off for my manager" +- "Request time off for my sister" +- "Request time off for [EmployeeName]" + +### Valid Requests (Accepted) +- "Request time off" +- "I need to submit time off" +- "Please request 8 hours time off on 2025-09-15 because of a family event" +- "Request 4 hours vacation on December 1st" + +## Customization Guide + +### Adding Time Off Types +In `topic.yaml`, locate the `timeOffType` dropdown in the Adaptive Card and add new choices: + +```yaml +choices: [ + { title: "Floating Holiday", value: "Floating_Holiday_Hours" }, + { title: "Vacation", value: "Vacation_Hours" }, + { title: "Sick", value: "Sick_Hours" }, + # Add your custom time off type: + { title: "Bereavement", value: "Bereavement_Hours" } +] +``` + +### Changing Hour Limits +Modify the `min` and `max` values in the `numberOfHours` input: + +```yaml +{ + type: "Input.Number", + id: "numberOfHours", + min: 0.5, # Minimum hours + max: 24, # Maximum hours + ... +} +``` + +### Enabling Auto-Complete +To skip the approval workflow, change `Auto_Complete` to `true` in the XML template: + +```xml +true +``` diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeesviewtheirjobtaxonomy/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeesviewtheirjobtaxonomy/README.md new file mode 100644 index 00000000..a41c2a4e --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayEmployeesviewtheirjobtaxonomy/README.md @@ -0,0 +1,203 @@ +# Workday Employees View Their Job Taxonomy + +## Overview +This scenario enables employees to view their job taxonomy information from Workday. It retrieves job-related data including job title, business title, job profile, and job family, providing employees with visibility into their role classification within the organization. + +## Features + +- **Multiple Job Attributes**: Retrieves job title, business title, job profile, and job family +- **Two-Step Retrieval**: First fetches employee job data, then enriches with job family details +- **Real-Time Data**: Uses current date as effective date for up-to-date information +- **AI Response**: Returns structured data that AI formats based on the user's specific question + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMEmployeeGetJobTaxonomy.xml` | XML template for Workday Get_Workers API call to retrieve job taxonomy | + +> **Note**: This scenario also uses `msdyn_HRWorkdayHCMEmployeeGetJobTaxonomyGeneric` (a shared template) to fetch job family details in a second API call. This template is part of the common ESS configuration. + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID +- `Global.ESS_UserContext_Employee_Firstname` - Employee's first name +- `Global.ESS_UserContext_Employee_Lastname` - Employee's last name + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What is my job title?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (msdyn_HRWorkdayHCMEmployee │ +│ GetJobTaxonomy) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Response │ +│ (JobTitle, BusinessTitle, │ +│ JobProfile, JobFamilyId) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get Job Family API │ +│ (msdyn_HRWorkdayHCMEmployee │ +│ GetJobTaxonomyGeneric) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Job Family Name │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Combine into Job Taxonomy Data │ +│ and return to AI for response │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "What is my job title?" +- "What job function do I belong to?" +- "What is my job function?" +- "What job category do I belong to?" +- "What is my role?" +- "What job family do I belong to?" +- "What is my job profile?" +- "What is my internal title?" +- "What is my external title?" + +## Data Retrieved + +### Step 1: Employee Job Data + +| Field | Description | XPath | +|-------|-------------|-------| +| JobTitle | Position title (internal title) | `//*[local-name()="Position_Title"]/text()` | +| BusinessTitle | Business/external title | `//*[local-name()="Business_Title"]/text()` | +| JobProfile | Job profile name | `//*[local-name()="Job_Profile_Name"]/text()` | +| JobFamilyId | Job family identifier (for lookup) | `//*[local-name()='Job_Family_Reference']/*[local-name()='ID' and @type='Job_Family_ID']/text()` | + +### Step 2: Job Family Data + +| Field | Description | +|-------|-------------| +| JobFamily | Human-readable job family name | + +### Final Output Structure + +| Field | Description | Example | +|-------|-------------|---------| +| EmployeeName | Full name of the employee | `John Smith` | +| JobTitle | Internal position title | `Senior Software Engineer` | +| BusinessTitle | External-facing title | `Software Engineer III` | +| JobProfile | Job profile classification | `Software Engineering` | +| JobFamily | Job family grouping | `Engineering & Technology` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template is optimized for performance by only requesting employment information: + +```xml + + true + +``` + +## Example Interactions + +### Example 1: Job Title Query +**User**: "What is my job title?" + +**Agent**: "Your job title is **Senior Software Engineer**." + +--- + +### Example 2: Job Function Query +**User**: "What job function do I belong to?" + +**Agent**: "You belong to the **Engineering & Technology** job family." + +--- + +### Example 3: Full Taxonomy Query +**User**: "Tell me about my role" + +**Agent**: "Here's your job information: +- **Job Title**: Senior Software Engineer +- **Business Title**: Software Engineer III +- **Job Profile**: Software Engineering +- **Job Family**: Engineering & Technology" + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMEmployeeGetJobTaxonomy.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variables**: Make sure the following are populated from user authentication: + - `Global.ESS_UserContext_Employee_Id` + - `Global.ESS_UserContext_Employee_Firstname` + - `Global.ESS_UserContext_Employee_Lastname` + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `msdyn_HRWorkdayHCMEmployeeGetJobTaxonomyGeneric` - Secondary scenario for job family lookup +- `Global.ESS_UserContext_Employee_Id` - Current user's employee ID +- `Global.ESS_UserContext_Employee_Firstname` - Current user's first name +- `Global.ESS_UserContext_Employee_Lastname` - Current user's last name + +## Model Instructions + +The topic includes model instructions to: +- Respond based on the specific piece of data the user is asking for +- Only respond to requests about the user's own job taxonomy +- Reject requests about other employees' data + +### Invalid Requests (Rejected) +- "What is my manager's job function?" +- "What is my sister's job title?" +- "What is [EmployeeName]'s role?" + +### Valid Requests (Accepted) +- "What is my job title?" +- "What is my external title?" +- "What job family do I belong to?" +- "What is my job profile?" + +## Output Type + +The topic outputs a `jobFunctionData` record with the following properties: + +```yaml +jobFunctionData: + EmployeeName: String # e.g., "John Smith" + JobTitle: String # e.g., "Senior Software Engineer" + BusinessTitle: String # e.g., "Software Engineer III" + JobProfile: String # e.g., "Software Engineering" + JobFamily: String # e.g., "Engineering & Technology" +``` diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetContactInformation/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetContactInformation/README.md new file mode 100644 index 00000000..13bd3fe7 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetContactInformation/README.md @@ -0,0 +1,262 @@ +# Workday Get Contact Information + +## Overview +This scenario enables employees to view their complete contact information from Workday, including both work and personal (home) contact details. It retrieves phone numbers, email addresses, and physical addresses, with primary contact indicators. + +## Features + +- **Work Contact Information**: Work phone numbers, work emails, and work address +- **Home/Personal Contact Information**: Personal phone numbers, personal emails, and home address +- **Primary Indicators**: Identifies which phone/email is marked as primary +- **Access Control**: Verifies the user can only access their own contact information +- **Comprehensive Data**: Combines three API calls for complete contact profile + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMEmployeeGetHomeContactInformation.xml` | XML template for fetching home/personal contact information | + +> **Note**: This scenario also uses two additional shared templates from the common ESS configuration: +> - `msdyn_HRWorkdayHCMEmployeeGetWorkContactInformation` - For work phone/email data +> - `msdyn_HRWorkdayHCMEmployeeGetWorkAddress` - For work address data + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID +- `Global.ESS_UserContext_Employee_Firstname` - Employee's first name +- `Global.ESS_UserContext_Employee_Lastname` - Employee's last name + +### Workday API +- **Service**: Human_Resources +- **Version**: v42.0 +- **Operations**: + - `Get_Change_Home_Contact_Information` - For home/personal contact data + - `Get_Workers` (Work Contact) - For work contact data + - `Get_Workers` (Work Address) - For work address + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What is my work phone?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Access Check │ +│ (Verify user is requesting │ +│ their own data only) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Fetch Work Contact Information │ +│ (msdyn_HRWorkdayHCMEmployee │ +│ GetWorkContactInformation) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Work Contact Data │ +│ (Phones, Emails) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Fetch Home Contact Information │ +│ (msdyn_HRWorkdayHCMEmployee │ +│ GetHomeContactInformation) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Home Contact Data │ +│ (Phones, Emails, Address) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Fetch Work Address │ +│ (msdyn_HRWorkdayHCMEmployee │ +│ GetWorkAddress) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Combine All Contact Data │ +│ and return to AI for response │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +### Work Contact +- "Show my contact details" +- "What is my work phone?" +- "What is my work email?" +- "What is my work address?" +- "Show my work contact information" + +### Home/Personal Contact +- "Show my personal phone number" +- "What is my home phone number?" +- "Show my home email" +- "Can you tell me what my personal email is?" +- "Which personal email is registered as primary?" +- "Show my home address" +- "Show my personal contact information" + +## Data Retrieved + +### Work Contact Data + +| Field | Description | +|-------|-------------| +| workPhoneNumbers | Table of work phone numbers with primary indicator | +| workEmails | Table of work email addresses with primary indicator | +| workAddress | Formatted work address | + +### Home Contact Data + +| Field | Description | +|-------|-------------| +| homePhoneNumbers | Table of personal phone numbers with primary indicator | +| homeEmails | Table of personal email addresses with primary indicator | +| homeAddress | Formatted home address | + +### Phone Number Structure + +| Property | Type | Description | +|----------|------|-------------| +| PhoneNumber | String | Formatted phone number | +| IsPrimaryPhoneNumber | Boolean | Whether this is the primary phone | + +### Email Structure + +| Property | Type | Description | +|----------|------|-------------| +| EmailAddress | String | Email address | +| IsPrimaryEmailAddress | String | Whether this is the primary email | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Properties Extracted + +### Home Contact Information + +| Key | XPath | Description | +|-----|-------|-------------| +| PhoneInformation | `//*[local-name()='Phone_Information_Data']` | All phone data nodes | +| EmailInformation | `//*[local-name()='Email_Information_Data']` | All email data nodes | +| HomeAddress | `//@*[local-name()='Formatted_Address']` | Formatted address string | + +## Example Interactions + +### Example 1: Work Phone Query +**User**: "What is my work phone?" + +**Agent**: "Your work phone number is **(555) 123-4567** (Primary)." + +--- + +### Example 2: Personal Email Query +**User**: "What is my personal email?" + +**Agent**: "Your personal email addresses are: +- **john.smith@gmail.com** (Primary) +- john.backup@outlook.com" + +--- + +### Example 3: Full Contact Info +**User**: "Show my contact information" + +**Agent**: "Here's your contact information: + +**Work Contact:** +- Phone: (555) 123-4567 ⭐ +- Email: john.smith@company.com ⭐ +- Address: 123 Business Ave, Suite 100, Seattle, WA 98101 + +**Personal Contact:** +- Phone: (555) 987-6543 ⭐ +- Email: john.smith@gmail.com ⭐ +- Address: 456 Home Street, Apt 2B, Seattle, WA 98102" + +--- + +### Example 4: Home Address Query +**User**: "What is my home address?" + +**Agent**: "Your home address is **456 Home Street, Apt 2B, Seattle, WA 98102**." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Templates**: Upload the following to your Workday connector configuration: + - `msdyn_HRWorkdayHCMEmployeeGetHomeContactInformation.xml` + - Work contact and work address templates (if not already present) +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variables**: Make sure the following are populated from user authentication: + - `Global.ESS_UserContext_Employee_Id` + - `Global.ESS_UserContext_Employee_Firstname` + - `Global.ESS_UserContext_Employee_Lastname` + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemAccessCheck` - Verifies user access permissions +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `msdyn_HRWorkdayHCMEmployeeGetWorkContactInformation` - Scenario for work contact data +- `msdyn_HRWorkdayHCMEmployeeGetHomeContactInformation` - Scenario for home contact data +- `msdyn_HRWorkdayHCMEmployeeGetWorkAddress` - Scenario for work address +- `Global.ESS_UserContext_Employee_Id` - Current user's employee ID + +## Model Instructions + +The topic includes model instructions to: +- Respond based on the specific contact information the user is asking for +- Only respond to requests about the user's own contact information +- Treat "Home" and "Personal" as synonymous terms + +### Invalid Requests (Rejected) +- "What is my manager's contact information?" +- "What is my sister's contact information?" +- "Show [EmployeeName]'s phone number" + +### Valid Requests (Accepted) +- "What is my contact information?" +- "What is my work phone?" +- "Show my home email" +- "What is my personal address?" + +## Output Type + +The topic outputs a `finalizedContactInformation` record: + +```yaml +finalizedContactInformation: + employeeName: String # e.g., "John Smith" + workPhoneNumbers: # Table + - PhoneNumber: String # e.g., "(555) 123-4567" + IsPrimaryPhoneNumber: Boolean + workEmails: # Table + - EmailAddress: String # e.g., "john@company.com" + IsPrimaryEmailAddress: String + workAddress: String # Formatted work address + homePhoneNumbers: # Table + - PhoneNumber: String + IsPrimaryPhoneNumber: Boolean + homeEmails: # Table + - EmailAddress: String + IsPrimaryEmailAddress: String + homeAddress: String # Formatted home address +``` diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetEducation/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetEducation/README.md new file mode 100644 index 00000000..b322370e --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetEducation/README.md @@ -0,0 +1,268 @@ +# Workday Get Education + +## Overview +This scenario enables employees to view their education history from Workday. It retrieves all education records including schools attended, degrees earned, fields of study, and years attended, with human-readable names resolved from reference data. + +## Features + +- **Complete Education History**: Retrieves all education records for the employee +- **Reference Data Resolution**: Converts country codes, degree IDs, and field of study IDs to human-readable names +- **Multiple Degrees Support**: Handles employees with multiple education entries +- **Access Control**: Verifies the user can only access their own education data + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMEmployeeGetEducation.xml` | XML template for Workday Get_Workers API call with qualifications | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID +- `Global.ESS_UserContext_Employee_Firstname` - Employee's first name +- `Global.ESS_UserContext_Employee_Lastname` - Employee's last name + +### Reference Data Lookup Tables +The topic automatically refreshes these lookup tables if empty: +- `Global.CountryNameLookupTable` - Country names by ISO code +- `Global.DegreeTypeLookupTable` - Degree names by Degree_ID +- `Global.FieldOfStudyLookupTable` - Field of study names by Field_Of_Study_ID + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v41.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "Show my education") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Access Check │ +│ (Verify user is requesting │ +│ their own data only) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Include_Qualifications = true) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Education Data │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Refresh Reference Data │ +│ (Country, Degree, Field of Study) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Transform Data with Lookups │ +│ (Resolve IDs to names) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return finalized education data │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "Show my education details" +- "From which school I completed my BS degree education?" +- "Show my education degrees" +- "What was my field of study during education?" +- "Show my first year attended for BS degree education" +- "Show my last year attended for BS degree education" +- "What is my education?" +- "List my degrees" + +## Data Retrieved + +| Field | Description | Example | +|-------|-------------|---------| +| EmployeeName | Full name of the employee | `John Smith` | +| Country | Country where education was obtained | `United States` | +| School | Name of the school/university | `University of Washington` | +| Degree | Type of degree earned | `Bachelor of Science` | +| FieldOfStudy | Major or field of study | `Computer Science` | +| FirstYearAttended | Year started | `2010` | +| LastYearAttended | Year completed | `2014` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template is optimized to only request qualification data: + +```xml + + true + +``` + +## Response Properties Extracted + +| Key | XPath | Description | +|-----|-------|-------------| +| EducationData | `//*[local-name()='Worker']/*[local-name()='Worker_Data']/*[local-name()='Qualification_Data']/*[local-name()='Education']` | All education records | + +### Raw Education Data Fields + +| Field | Description | +|-------|-------------| +| Education_ID | Unique identifier for the education record | +| School_Name | Name of the institution | +| Country_Reference | Country reference with ID | +| Degree_Reference | Degree type reference with ID | +| Field_Of_Study_Reference | Field of study reference with ID | +| First_Year_Attended | Start year | +| Last_Year_Attended | End year | +| Date_Degree_Received | Date degree was awarded | +| Is_Highest_Level_of_Education | Flag for highest education level | +| Location | Location of the institution | + +## Example Interactions + +### Example 1: Full Education History +**User**: "Show my education details" + +**Agent**: "Here's your education history: + +**University of Washington** +- Degree: Bachelor of Science +- Field of Study: Computer Science +- Years: 2010 - 2014 +- Country: United States + +**Stanford University** +- Degree: Master of Science +- Field of Study: Software Engineering +- Years: 2015 - 2017 +- Country: United States" + +--- + +### Example 2: Specific Field Query +**User**: "What was my field of study?" + +**Agent**: "Your field of study was **Computer Science** (BS) and **Software Engineering** (MS)." + +--- + +### Example 3: School Query +**User**: "Which schools did I attend?" + +**Agent**: "You attended: +- University of Washington (2010-2014) +- Stanford University (2015-2017)" + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMEmployeeGetEducation.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variables**: Make sure the following are populated from user authentication: + - `Global.ESS_UserContext_Employee_Id` + - `Global.ESS_UserContext_Employee_Firstname` + - `Global.ESS_UserContext_Employee_Lastname` +5. **Reference Data**: Ensure reference data topics are configured for country, degree, and field of study lookups + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemAccessCheck` - Verifies user access permissions +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemRefreshReferenceData` - Reference data refresh +- `Global.CountryNameLookupTable` - Country reference data +- `Global.DegreeTypeLookupTable` - Degree type reference data +- `Global.FieldOfStudyLookupTable` - Field of study reference data + +## Model Instructions + +The topic includes model instructions to: +- Respond based on the specific education information the user is asking for +- Only respond to requests about the user's own education +- Reject requests about other employees' data + +### Invalid Requests (Rejected) +- "What is my manager's education?" +- "What is my sister's education?" +- "Show [EmployeeName]'s degrees" + +### Valid Requests (Accepted) +- "What is my education?" +- "Show my education details" +- "What was my field of study?" +- "Which school did I attend?" + +## Output Type + +The topic outputs a `FinalizedEducationData` table: + +```yaml +FinalizedEducationData: + - EmployeeName: String # e.g., "John Smith" + Country: String # e.g., "United States" + School: String # e.g., "University of Washington" + Degree: String # e.g., "Bachelor of Science" + FieldOfStudy: String # e.g., "Computer Science" + FirstYearAttended: String # e.g., "2010" + LastYearAttended: String # e.g., "2014" +``` + +## Customization Guide + +### Adding Additional Education Fields + +To extract additional fields from Workday's education data, modify the `ParseValue` action in `topic.yaml`. Available fields include: + +| Field | Description | +|-------|-------------| +| `Date_Degree_Received` | Exact date degree was awarded | +| `Is_Highest_Level_of_Education` | Flag indicating highest education | +| `Location` | Specific location/campus | +| `Education_ID` | Unique Workday identifier | + +### Adding to Final Output + +In the `SetVariable` action for `Topic.FinalizedEducationData`, add the new field: + +```yaml +{ + ...existing fields... + DateDegreeReceived: currentRecord.Date_Degree_Received, + IsHighestLevel: currentRecord.Is_Highest_Level_of_Education = "1" +} +``` + +### Adding New Reference Data Lookups + +To add additional reference data (e.g., School types), add a new `BeginDialog` block: + +```yaml +- kind: BeginDialog + displayName: Refresh school type reference data + input: + binding: + IsTableEmpty: =IsBlank(Global.SchoolTypeLookupTable) + ReferenceDataKey: School_Type_ID + dialog: msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemRefreshReferenceData +``` diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetGovernmentIDs/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetGovernmentIDs/README.md new file mode 100644 index 00000000..5f49f99a --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGetGovernmentIDs/README.md @@ -0,0 +1,216 @@ +# Workday Get Government IDs + +## Overview +This scenario enables employees to view their government identification documents from Workday. It retrieves all government IDs on file including ID type, country of issue, issue date, and expiration date, with human-readable names resolved from reference data. + +## Features + +- **Multiple ID Support**: Retrieves all government IDs associated with the employee +- **Reference Data Resolution**: Converts country codes and ID type codes to human-readable names +- **Expiration Tracking**: Shows issue and expiration dates for each ID +- **Access Control**: Verifies the user can only access their own government ID data + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMEmployeeGetGovernmentIds.xml` | XML template for Workday Get_Workers API call with personal information | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The employee's Workday Employee ID +- `Global.ESS_UserContext_Employee_Firstname` - Employee's first name +- `Global.ESS_UserContext_Employee_Lastname` - Employee's last name + +### Reference Data Lookup Tables +The topic automatically refreshes these lookup tables if empty: +- `Global.CountryNameLookupTable` - Country names by ISO code +- `Global.GovernmentIdTypeLookupTable` - Government ID type names + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What are my government │ +│ IDs?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Access Check │ +│ (Verify user is requesting │ +│ their own data only) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Include_Personal_Information) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Government ID Data │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Refresh Reference Data │ +│ (Country, Government ID Type) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Transform Data with Lookups │ +│ (Resolve IDs to names) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return finalized ID data │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "What are my government IDs?" +- "Which government IDs are available on my profile?" +- "Show my government IDs" +- "What IDs do I have on file?" +- "Show my identification documents" + +## Data Retrieved + +| Field | Description | Example | +|-------|-------------|---------| +| EmployeeName | Full name of the employee | `John Smith` | +| IDType | Type of government ID | `Passport`, `Social Security Number`, `Driver's License` | +| ID | The ID number (may be masked) | `***-**-1234` | +| CountryName | Country that issued the ID | `United States` | +| IssuedDate | Date the ID was issued | `2020-05-15` | +| ExpirationDate | Date the ID expires | `2030-05-14` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Employee's Workday ID | `21514` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template requests personal information which includes government IDs: + +```xml + + true + +``` + +## Response Properties Extracted + +| Key | XPath | Description | +|-----|-------|-------------| +| GovernmentId | `//*[local-name()='Government_ID']/*[local-name()='Government_ID_Data']` | All government ID records | + +### Raw Government ID Data Fields + +| Field | Description | +|-------|-------------| +| ID | The government ID value | +| ID_Type_Reference | Reference to the type of ID | +| Country_Reference | Reference to the issuing country | +| Issued_Date | Date the ID was issued | +| Expiration_Date | Date the ID expires | + +## Example Interactions + +### Example 1: All Government IDs +**User**: "What are my government IDs?" + +**Agent**: "Here are your government IDs on file: + +**Passport** +- Country: United States +- Issued: 2020-05-15 +- Expires: 2030-05-14 + +**Driver's License** +- Country: United States +- Issued: 2022-03-10 +- Expires: 2028-03-10 + +**Social Security Number** +- Country: United States" + +--- + +### Example 2: Specific Query +**User**: "Do I have a passport on file?" + +**Agent**: "Yes, you have a **United States Passport** on file. It was issued on 2020-05-15 and expires on 2030-05-14." + +--- + +### Example 3: Expiration Check +**User**: "When does my driver's license expire?" + +**Agent**: "Your driver's license expires on **2028-03-10**." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMEmployeeGetGovernmentIds.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variables**: Make sure the following are populated from user authentication: + - `Global.ESS_UserContext_Employee_Id` + - `Global.ESS_UserContext_Employee_Firstname` + - `Global.ESS_UserContext_Employee_Lastname` +5. **Reference Data**: Ensure reference data topics are configured for country and government ID type lookups + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemAccessCheck` - Verifies user access permissions +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemRefreshReferenceData` - Reference data refresh +- `Global.CountryNameLookupTable` - Country reference data +- `Global.GovernmentIdTypeLookupTable` - Government ID type reference data + +## Model Instructions + +The topic includes model instructions to: +- Respond based on the specific government ID information the user is asking for +- Only respond to requests about the user's own government IDs +- Reject requests about other employees' data + +### Invalid Requests (Rejected) +- "What are my manager's government IDs?" +- "What are my sister's government IDs?" +- "Show [EmployeeName]'s government IDs" + +### Valid Requests (Accepted) +- "What are my government IDs?" +- "Which government IDs are available on my profile?" +- "Show my government IDs" + +## Output Type + +The topic outputs a `finalizedResponseTableData` table: + +```yaml +finalizedResponseTableData: + - EmployeeName: String # e.g., "John Smith" + IDType: String # e.g., "Passport" + ID: String # e.g., "***-**-1234" + CountryName: String # e.g., "United States" + IssuedDate: String # e.g., "2020-05-15" + ExpirationDate: String # e.g., "2030-05-14" +``` diff --git a/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGivePeerFeedback/README.md b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGivePeerFeedback/README.md new file mode 100644 index 00000000..fb98eb5e --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/WorkdayGivePeerFeedback/README.md @@ -0,0 +1,201 @@ +# Workday Give Peer Feedback + +## Overview +This scenario enables employees to send feedback to their colleagues through Workday's Talent module. It provides a simple conversational interface to collect the recipient's employee ID and feedback text, then submits it to Workday. + +## Features + +- **Peer-to-Peer Feedback**: Send feedback to any colleague by their Employee ID +- **Simple Conversation Flow**: Collects recipient ID and feedback text via prompts +- **Immediate Submission**: Feedback is auto-completed and sent immediately +- **Non-Anonymous by Default**: Sender's name is shown to the recipient + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with conversational prompts | +| `msdyn_HRWorkdayHCMEmployeeGiveFeedback.xml` | XML template for Workday Give_Feedback API call | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_Employee_Id` - The sender's Workday Employee ID + +### Workday API +- **Service**: Talent +- **Operation**: Give_Feedback +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "Give feedback") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Ask for recipient's Employee ID │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Employee ID │ + │ provided? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ "Cannot send │ │ Ask for │ +│ to yourself" │ │ feedback text│ +└──────────────┘ └──────┬───────┘ + │ + ▼ + ┌─────────────────────────────────────┐ + │ Submit to Workday │ + │ (Give_Feedback API) │ + └──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Success? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ "Feedback │ │ Show error │ + │ sent │ │ message │ + │ successfully"│ │ │ + └──────────────┘ └──────────────┘ +``` + +## Trigger Phrases + +- "Send feedback about Workday" +- "Give feedback on Workday" +- "Workday feedback" +- "Share thoughts on Workday" +- "Submit comments for Workday" +- "Provide input on Workday experience" +- "I want to appreciate my teammate" +- "Give feedback" +- "Share feedback for a colleague" + +## Conversation Flow + +### Step 1: Collect Recipient +**Agent**: "What is the _Employee ID_ of the colleague you want to give feedback for?" + +**User**: "12345" + +### Step 2: Collect Feedback +**Agent**: "Please enter your feedback for your coworker." + +**User**: "Great job on the project delivery! Your attention to detail really made a difference." + +### Step 3: Confirmation +**Agent**: "Feedback is sent successfully" + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{Employee_ID}` | Sender's Workday Employee ID | `21514` | +| `{Employee_ID_Of_Receiver}` | Recipient's Workday Employee ID | `12345` | +| `{Comment}` | Feedback text | `Great teamwork!` | + +## Business Process Configuration + +The XML template configures the feedback submission: + +| Setting | Value | Description | +|---------|-------|-------------| +| `Run_Now` | true | Submit immediately | +| `Auto_Complete` | true | Complete without approval workflow | +| `Show_Name` | true | Sender's name visible to recipient | +| `Confidential` | false | Not marked as confidential | +| `Private` | false | Not marked as private | + +## Response Data + +| Field | Description | XPath | +|-------|-------------|-------| +| WID | Workday Internal ID of the feedback event | `//*[local-name()='Give_Feedback_Event_Reference']/*[local-name()='ID'][@type='WID']/text()` | + +## Example Interactions + +### Example 1: Successful Feedback +**User**: "I want to give feedback to a colleague" + +**Agent**: "What is the _Employee ID_ of the colleague you want to give feedback for?" + +**User**: "54321" + +**Agent**: "Please enter your feedback for your coworker." + +**User**: "Thank you for your help with the quarterly report. Your data analysis was excellent!" + +**Agent**: "Feedback is sent successfully" + +--- + +### Example 2: Error Scenario +**User**: "Give feedback" + +**Agent**: "What is the _Employee ID_ of the colleague you want to give feedback for?" + +**User**: "99999" + +**Agent**: "Please enter your feedback for your coworker." + +**User**: "Great work!" + +**Agent**: "There is a failure in sending the feedback: Invalid Employee ID" + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMEmployeeGiveFeedback.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_Employee_Id` is populated from user authentication + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_Employee_Id` - Current user's employee ID + +## Customization Guide + +### Making Feedback Anonymous +To allow anonymous feedback, modify the XML template: + +```xml +false +``` + +### Making Feedback Confidential +To mark feedback as confidential (only visible to recipient and HR): + +```xml +true +``` + +### Making Feedback Private +To mark feedback as private (only visible to recipient): + +```xml +true +``` + +### Adding Employee Lookup +To enhance the experience, you could add an employee search step before asking for the Employee ID, allowing users to search by name instead of ID. + +## Output Type + +This topic does not have a structured output type. Success/failure is communicated via messages. diff --git a/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagerServiceAnniversary/README.md b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagerServiceAnniversary/README.md new file mode 100644 index 00000000..d3e78369 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagerServiceAnniversary/README.md @@ -0,0 +1,244 @@ +# Workday Manager Service Anniversary + +## Overview +This scenario enables managers to view upcoming service anniversaries for their direct reports. It retrieves hire dates from Workday, calculates upcoming anniversary dates and milestones, and presents the information as a markdown table. + +## Features + +- **Anniversary Calculation**: Automatically calculates upcoming service anniversary dates from hire dates +- **Milestone Tracking**: Shows how many years each employee will be celebrating +- **Next Month Filter**: Ability to filter for anniversaries happening next month +- **Manager Verification**: Validates that the requesting user is a manager before proceeding +- **Name Filtering**: Optionally filter results by a specific employee's name +- **Markdown Table Output**: Results formatted as a clean markdown table + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and anniversary calculation logic | +| `msdyn_HRWorkdayHCMManagerServiceAnniversary.xml` | XML template for Workday Get_Workers API call with employment data | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_ManagerOrganizationId` - The manager's organization ID in Workday + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v41.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "When are my team's │ +│ service anniversaries?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Manager Check │ +│ (Verify user is a manager) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Filter by manager's org) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Response │ +│ (Names, Hire Dates) │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Employee │ + │ name given? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ Filter by │ │ Include all │ +│ employee name│ │ direct │ +│ │ │ reports │ +└──────┬───────┘ └──────┬───────┘ + │ │ + └───────┬────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Calculate Anniversary Data │ +│ - Upcoming Anniversary Date │ +│ - Upcoming Milestone (years) │ +│ - Anniversary Month │ +│ - Is Anniversary Next Month? │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return as markdown table │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "When are the service anniversaries of all my directs?" +- "What are the service anniversaries of my entire team?" +- "Show me the service anniversaries of my reports" +- "What are the upcoming service anniversaries of my team?" +- "Any upcoming service anniversaries of my reports?" +- "Show me service anniversaries of my directs" +- "What is [EmployeeName]'s next service anniversary?" +- "When is [EmployeeName]'s next year service anniversary?" + +## Topic Input Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `EmployeeName` | String | Optional. Filter results to a specific employee by name. | +| `duration` | Number | Optional. Duration for calculating nth service anniversary date. | + +## Data Retrieved from Workday + +| Field | Description | XPath | +|-------|-------------|-------| +| WorkerID | Employee's worker ID | `//*[local-name()='Worker_ID']/text()` | +| FirstName | First name | `//*[local-name()='First_Name']/text()` | +| LastName | Last name | `//*[local-name()='Last_Name']/text()` | +| HireDate | Original hire date | `//*[local-name()='Hire_Date']/text()` | + +## Calculated Fields + +| Field | Description | Example | +|-------|-------------|---------| +| EmployeeName | Full name (FirstName + LastName) | `John Smith` | +| HireDate | Original hire date | `2020-03-15` | +| UpcomingServiceAnniversaryDate | Next anniversary date | `2026-03-15` | +| UpcomingMilestone | Number of years at next anniversary | `6` | +| AnniversaryMonth | Month number of anniversary | `3` | +| isAnniversaryNextMonth | Boolean flag for filtering | `true` / `false` | + +## Anniversary Calculation Logic + +The topic uses Power Fx formulas to calculate upcoming anniversaries: + +``` +UpcomingServiceAnniversaryDate = + If Today() <= this year's anniversary date + Then this year's anniversary + Else next year's anniversary + +UpcomingMilestone = Years between HireDate and UpcomingServiceAnniversaryDate +``` + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{ManagerOrgId}` | Manager's organization reference ID | `ORG-12345` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template requests employment and personal information: + +```xml + + true + true + +``` + +## Example Interactions + +### Example 1: All Direct Reports +**User**: "When are the service anniversaries of all my directs?" + +**Agent**: + +| Employee Name | Hire Date | Upcoming Service Anniversary Date | Upcoming Milestone | +|---------------|-----------|-----------------------------------|-------------------| +| John Smith | 2020-03-15 | 2026-03-15 | 6 years | +| Jane Doe | 2019-07-22 | 2026-07-22 | 7 years | +| Bob Johnson | 2022-01-10 | 2026-01-10 | 4 years | + +--- + +### Example 2: Specific Employee +**User**: "What is Jane Doe's next service anniversary?" + +**Agent**: + +| Employee Name | Hire Date | Upcoming Service Anniversary Date | Upcoming Milestone | +|---------------|-----------|-----------------------------------|-------------------| +| Jane Doe | 2019-07-22 | 2026-07-22 | 7 years | + +--- + +### Example 3: Next Month Filter +**User**: "Any service anniversaries next month?" + +**Agent** (uses `isAnniversaryNextMonth` to filter): + +| Employee Name | Hire Date | Upcoming Service Anniversary Date | Upcoming Milestone | +|---------------|-----------|-----------------------------------|-------------------| +| Bob Johnson | 2022-02-15 | 2026-02-15 | 4 years | + +--- + +### Example 4: Employee Not Found +**User**: "What is Alice's service anniversary?" + +**Agent**: "It looks like you don't have access to this information. Try making a new request." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMManagerServiceAnniversary.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_ManagerOrganizationId` is populated from user authentication + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdayManagerCheck` - Verifies user is a manager +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_ManagerOrganizationId` - Manager's organization ID + +## Model Instructions + +The topic includes model instructions to: +- Output results as a markdown table with columns: Employee Name, Hire Date, Upcoming Service Anniversary Date, Upcoming Milestone +- Use `isAnniversaryNextMonth` to filter when user asks about "next month" +- Default to showing future anniversaries unless otherwise specified +- Reject requests about non-direct-reports + +### Invalid Requests (Rejected) +- "What is my manager's service anniversary?" +- "What is my sister's hire date?" + +### Valid Requests (Accepted) +- "What is the service anniversary of my direct reports?" +- "What is [EmployeeName]'s next service anniversary?" +- "Any upcoming service anniversaries next month?" + +## Output Type + +The topic outputs a `response` table: + +```yaml +response: + - EmployeeName: String # e.g., "John Smith" + HireDate: Date # e.g., 2020-03-15 + UpcomingServiceAnniversaryDate: Date # e.g., 2026-03-15 + UpcomingMilestone: Number # e.g., 6 + AnniversaryMonth: Number # e.g., 3 + isAnniversaryNextMonth: Boolean # e.g., false +``` diff --git a/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CompanyCode/README.md b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CompanyCode/README.md new file mode 100644 index 00000000..09ccc65e --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CompanyCode/README.md @@ -0,0 +1,216 @@ +# Workday Managers Direct Reports - Company Code + +## Overview +This scenario enables managers to view the company code and company name for their direct reports. It retrieves organization data from Workday and presents it as a nested markdown list, with optional filtering by employee name. + +## Features + +- **Direct Reports Only**: Retrieves company information for employees who report directly to the manager +- **Manager Verification**: Validates that the requesting user is a manager before proceeding +- **Name Filtering**: Optionally filter results by a specific employee's name +- **Markdown Output**: Results formatted as a nested markdown list for easy reading + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMManagerDirectCompanyCode.xml` | XML template for Workday Get_Workers API call with organization data | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_ManagerOrganizationId` - The manager's organization ID in Workday + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v41.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What are the company │ +│ codes for my reports?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Manager Check │ +│ (Verify user is a manager) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Filter by manager's org) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Response │ +│ (Worker IDs, Names, Company info) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Transform to Table │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Employee │ + │ name given? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ Filter by │ │ Return all │ +│ employee name│ │ direct │ +│ │ │ reports │ +└──────────────┘ └──────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return as nested markdown list │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "Show me my team's company codes" +- "What are the company codes for my reports?" +- "What company codes are mapped to my team members?" +- "What is the company code for [EmployeeName]?" + +## Topic Input Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `EmployeeName` | String | Optional. Filter results to a specific employee by name. | + +## Data Retrieved + +| Field | Description | Example | +|-------|-------------|---------| +| FirstName | Employee's first name | `John` | +| LastName | Employee's last name | `Smith` | +| CompanyCode | Organization company code | `CORP001` | +| CompanyName | Organization company name | `Contoso Corporation` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{ManagerOrgId}` | Manager's organization reference ID | `ORG-12345` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template requests organization and personal information: + +```xml + + true + false + true + true + +``` + +## Response Properties Extracted + +| Key | XPath | Description | +|-----|-------|-------------| +| WorkerID | `//*[local-name()='Worker_ID']/text()` | Employee's worker ID | +| FirstName | `//*[local-name()='First_Name']/text()` | First name | +| LastName | `//*[local-name()='Last_Name']/text()` | Last name | +| CompanyCode | `...Organization_Data/Organization_Code` (filtered by Company subtype) | Company code | +| CompanyName | `...Organization_Data/Organization_Name` (filtered by Company subtype) | Company name | + +## Example Interactions + +### Example 1: All Direct Reports +**User**: "What are the company codes for my reports?" + +**Agent**: +``` +Here are the company codes for your direct reports: + +- **John Smith** + - Company Code: CORP001 + - Company Name: Contoso Corporation + +- **Jane Doe** + - Company Code: CORP002 + - Company Name: Contoso International + +- **Bob Johnson** + - Company Code: CORP001 + - Company Name: Contoso Corporation +``` + +--- + +### Example 2: Specific Employee +**User**: "What is the company code for Jane Doe?" + +**Agent**: +``` +- **Jane Doe** + - Company Code: CORP002 + - Company Name: Contoso International +``` + +--- + +### Example 3: Employee Not Found +**User**: "What is the company code for Alice?" + +**Agent**: "It looks like you don't have access to this information. Try making a new request." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMManagerDirectCompanyCode.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_ManagerOrganizationId` is populated from user authentication + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdayManagerCheck` - Verifies user is a manager +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_ManagerOrganizationId` - Manager's organization ID + +## Model Instructions + +The topic includes model instructions to: +- Only respond to requests about direct reports' company information +- Output results as a nested markdown list +- Reject requests about non-direct-reports (managers, siblings, etc.) + +### Invalid Requests (Rejected) +- "What is my manager's company code?" +- "What is my sister's company code?" +- "What is my own company code?" + +### Valid Requests (Accepted) +- "What is the company code of my direct reports?" +- "What are the company codes for my reports?" +- "What is the company code for [EmployeeName]?" (if they are a direct report) + +## Output Type + +The topic outputs a `workdayResponseTable` table: + +```yaml +workdayResponseTable: + - FirstName: String # e.g., "John" + LastName: String # e.g., "Smith" + CompanyCode: String # e.g., "CORP001" + CompanyName: String # e.g., "Contoso Corporation" +``` diff --git a/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CostCenter/README.md b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CostCenter/README.md new file mode 100644 index 00000000..52135984 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-CostCenter/README.md @@ -0,0 +1,217 @@ +# Workday Managers Direct Reports - Cost Center + +## Overview +This scenario enables managers to view the cost center information for their direct reports. It retrieves organization data from Workday and presents cost center codes and names as a nested markdown list, with optional filtering by employee name. + +## Features + +- **Direct Reports Only**: Retrieves cost center information for employees who report directly to the manager +- **Manager Verification**: Validates that the requesting user is a manager before proceeding +- **Name Filtering**: Optionally filter results by a specific employee's name +- **Markdown Output**: Results formatted as a nested markdown list for easy reading + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMManagerDirectCostCenter.xml` | XML template for Workday Get_Workers API call with organization data | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_ManagerOrganizationId` - The manager's organization ID in Workday + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v42.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "What is the cost center │ +│ of my direct reports?") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Manager Check │ +│ (Verify user is a manager) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Filter by manager's org) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Response │ +│ (Worker IDs, Names, Cost Center) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Transform to Table │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Employee │ + │ name given? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ Filter by │ │ Return all │ +│ employee name│ │ direct │ +│ │ │ reports │ +└──────────────┘ └──────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return as nested markdown list │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "Show me my team's cost center data" +- "What cost centers are assigned to my reports?" +- "What are my team's cost centers?" +- "What is the cost center for [EmployeeName]?" + +## Topic Input Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `EmployeeName` | String | Optional. Filter results to a specific employee by name. | + +## Data Retrieved + +| Field | Description | Example | +|-------|-------------|---------| +| FirstName | Employee's first name | `John` | +| LastName | Employee's last name | `Smith` | +| CostCenterCode | Cost center code | `CC-1001` | +| CostCenterName | Cost center name | `Engineering - West` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{ManagerOrgId}` | Manager's organization reference ID | `ORG-12345` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template requests organization and personal information: + +```xml + + true + false + true + true + +``` + +## Response Properties Extracted + +| Key | XPath | Description | +|-----|-------|-------------| +| WorkerID | `//*[local-name()='Worker_ID']/text()` | Employee's worker ID | +| LegalNameData | `//*[local-name()='Legal_Name_Data']` | Name data including first/last name | +| CostCenterCode | `...Organization_Data/Organization_Code` (filtered by Cost_Center type) | Cost center code | +| CostCenterName | `...Organization_Data/Organization_Name` (filtered by Cost_Center type) | Cost center name | +| PositionID | `//*[local-name()='Position_ID']/text()` | Position identifier | + +## Example Interactions + +### Example 1: All Direct Reports +**User**: "What are my team's cost centers?" + +**Agent**: +``` +Here are the cost centers for your direct reports: + +- **John Smith** + - Cost Center Code: CC-1001 + - Cost Center Name: Engineering - West + +- **Jane Doe** + - Cost Center Code: CC-2002 + - Cost Center Name: Product Development + +- **Bob Johnson** + - Cost Center Code: CC-1001 + - Cost Center Name: Engineering - West +``` + +--- + +### Example 2: Specific Employee +**User**: "What is the cost center for Jane Doe?" + +**Agent**: +``` +- **Jane Doe** + - Cost Center Code: CC-2002 + - Cost Center Name: Product Development +``` + +--- + +### Example 3: Employee Not Found +**User**: "What is the cost center for Alice?" + +**Agent**: "It looks like you don't have access to this information. Try making a new request." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMManagerDirectCostCenter.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_ManagerOrganizationId` is populated from user authentication + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdayManagerCheck` - Verifies user is a manager +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `Global.ESS_UserContext_ManagerOrganizationId` - Manager's organization ID + +## Model Instructions + +The topic includes model instructions to: +- Only respond to requests about direct reports' cost center information +- Output results as a nested markdown list +- Reject requests about non-direct-reports (managers, siblings, etc.) +- Only provide data when sufficient information is available + +### Invalid Requests (Rejected) +- "What is my manager's cost center?" +- "What is my sister's cost center?" +- "What is my own cost center?" + +### Valid Requests (Accepted) +- "What is the cost center of my direct reports?" +- "What cost centers are assigned to my reports?" +- "What is the cost center for [EmployeeName]?" (if they are a direct report) + +## Output Type + +The topic outputs a `workdayResponseTable` table: + +```yaml +workdayResponseTable: + - FirstName: String # e.g., "John" + LastName: String # e.g., "Smith" + CostCenterCode: String # e.g., "CC-1001" + CostCenterName: String # e.g., "Engineering - West" +``` diff --git a/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-Jobtaxanomy/README.md b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-Jobtaxanomy/README.md new file mode 100644 index 00000000..1eb09707 --- /dev/null +++ b/EmployeeSelfServiceAgent/Workday/ManagerScenarios/WorkdayManagersdirect-Jobtaxanomy/README.md @@ -0,0 +1,247 @@ +# Workday Managers Direct Reports - Job Taxonomy + +## Overview +This scenario enables managers to view the job taxonomy information for their direct reports. It retrieves job-related data including job title, business title, job profile, and job family from Workday, with human-readable job family names resolved from reference data. + +## Features + +- **Direct Reports Only**: Retrieves job taxonomy for employees who report directly to the manager +- **Manager Verification**: Validates that the requesting user is a manager before proceeding +- **Reference Data Resolution**: Converts Job Family IDs to human-readable names +- **Name Filtering**: Optionally filter results by a specific employee's name +- **Markdown Output**: Results formatted as a nested markdown list for easy reading + +## Files + +| File | Description | +|------|-------------| +| `topic.yaml` | Copilot Studio topic definition with trigger phrases and data transformation logic | +| `msdyn_HRWorkdayHCMManagerJobTaxonomy.xml` | XML template for Workday Get_Workers API call with employment data | + +## Prerequisites + +### Global Variables Required +- `Global.ESS_UserContext_ManagerOrganizationId` - The manager's organization ID in Workday + +### Reference Data Lookup Tables +The topic automatically refreshes this lookup table if empty: +- `Global.JobFamilyLookupTable` - Job family names by Job_Family_ID + +### Workday API +- **Service**: Human_Resources +- **Operation**: Get_Workers +- **Version**: v41.0 + +## Workflow + +``` +┌─────────────────────────────────────┐ +│ User triggers topic │ +│ (e.g., "Show me my team's job │ +│ titles") │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Manager Check │ +│ (Verify user is a manager) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Call Get_Workers API │ +│ (Filter by manager's org) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Parse Response │ +│ (Names, Job Titles, Profiles) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Refresh Job Family Reference Data │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Transform Data with Lookups │ +│ (Resolve Job Family IDs to names) │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Employee │ + │ name given? │ + └──────┬──────┘ + │ + ┌───────┴───────┐ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ Filter by │ │ Return all │ +│ employee name│ │ direct │ +│ │ │ reports │ +└──────────────┘ └──────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Return as nested markdown list │ +└─────────────────────────────────────┘ +``` + +## Trigger Phrases + +- "Show me my team's job title" +- "What is the internal title of my direct report [EmployeeName]?" +- "What is the job function of my team?" +- "What job profile is mapped to my team members?" +- "What are the external titles of my team members?" +- "Show me my team's job taxonomy" +- "Get job data for [EmployeeName]" +- "What is the job title of [EmployeeName]?" + +## Topic Input Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `EmployeeName` | String | Optional. Filter results to a specific employee by name. | + +## Data Retrieved + +| Field | Description | Example | +|-------|-------------|---------| +| FirstName | Employee's first name | `John` | +| LastName | Employee's last name | `Smith` | +| JobTitle | Internal position title | `Senior Software Engineer` | +| BusinessTitle | External-facing title | `Software Engineer III` | +| JobProfile | Job profile classification | `Software Engineering` | +| JobFamily | Job family grouping | `Engineering & Technology` | + +## XML Template Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `{ManagerOrgId}` | Manager's organization reference ID | `ORG-12345` | +| `{As_Of_Effective_Date}` | Current date (YYYY-MM-DD) | `2026-01-28` | + +## Response Group Configuration + +The XML template requests employment and personal information: + +```xml + + true + true + +``` + +## Response Properties Extracted + +| Key | XPath | Description | +|-----|-------|-------------| +| WorkerID | `//*[local-name()='Worker_ID']/text()` | Employee's worker ID | +| FirstName | `//*[local-name()='First_Name']/text()` | First name | +| LastName | `//*[local-name()='Last_Name']/text()` | Last name | +| JobTitle | `//*[local-name()='Position_Title']/text()` | Internal job title | +| BusinessTitle | `//*[local-name()='Business_Title']/text()` | Business/external title | +| JobProfile | `//*[local-name()='Job_Profile_Name']/text()` | Job profile name | +| JobFamilyId | `//*[local-name()='Job_Family_Reference']/*[local-name()='ID']` | Job family ID (for lookup) | + +## Example Interactions + +### Example 1: All Direct Reports +**User**: "Show me my team's job titles" + +**Agent**: +``` +Here is the job taxonomy for your direct reports: + +- **John Smith** + - Job Title: Senior Software Engineer + - Business Title: Software Engineer III + - Job Profile: Software Engineering + - Job Family: Engineering & Technology + +- **Jane Doe** + - Job Title: Product Manager + - Business Title: Senior Product Manager + - Job Profile: Product Management + - Job Family: Product & Design + +- **Bob Johnson** + - Job Title: QA Engineer + - Business Title: Quality Assurance Engineer + - Job Profile: Quality Assurance + - Job Family: Engineering & Technology +``` + +--- + +### Example 2: Specific Employee +**User**: "What is the job title of Jane Doe?" + +**Agent**: +``` +- **Jane Doe** + - Job Title: Product Manager + - Business Title: Senior Product Manager + - Job Profile: Product Management + - Job Family: Product & Design +``` + +--- + +### Example 3: Employee Not Found +**User**: "What is the job title for Alice?" + +**Agent**: "It looks like you don't have access to this information. Try making a new request." + +## Setup Instructions + +1. **Import the Topic**: Import `topic.yaml` into your Copilot Studio agent +2. **Add XML Template**: Upload `msdyn_HRWorkdayHCMManagerJobTaxonomy.xml` to your Workday connector configuration +3. **Configure Connection**: Ensure your Workday connector connection reference is properly set in the topic +4. **Set Global Variable**: Make sure `Global.ESS_UserContext_ManagerOrganizationId` is populated from user authentication +5. **Reference Data**: Ensure reference data topic is configured for Job Family lookups + +## Dependencies + +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdayManagerCheck` - Verifies user is a manager +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemGetCommonExecution` - Common API execution topic +- `msdyn_copilotforemployeeselfservicehr.topic.WorkdaySystemRefreshReferenceData` - Reference data refresh +- `Global.ESS_UserContext_ManagerOrganizationId` - Manager's organization ID +- `Global.JobFamilyLookupTable` - Job family reference data + +## Model Instructions + +The topic includes model instructions to: +- Only respond to requests about direct reports' job taxonomy +- Output results as a nested markdown list +- Reject requests about non-direct-reports (managers, siblings, etc.) +- Only provide data when sufficient information is available + +### Invalid Requests (Rejected) +- "What is my manager's job function?" +- "What is my sister's job title?" +- "What is my own job title?" + +### Valid Requests (Accepted) +- "What is the external title of my direct reports?" +- "What is [EmployeeName]'s job title?" +- "Show me my team's job taxonomy" + +## Output Type + +The topic outputs a `workdayResponseTable` table: + +```yaml +workdayResponseTable: + - FirstName: String # e.g., "John" + LastName: String # e.g., "Smith" + JobTitle: String # e.g., "Senior Software Engineer" + BusinessTitle: String # e.g., "Software Engineer III" + JobProfile: String # e.g., "Software Engineering" + JobFamily: String # e.g., "Engineering & Technology" +```