Skip to content

Update Workday Open source topic descriptions to improve tool invocation from Sydney. Update specific to ESS DA agent #504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AdwaitRaut wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update Workday Open source topic descriptions to improve tool invocation from Sydney. Update specific to ESS DA agent #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0fdf84c
Update Workday Open source topic descriptions to improve tool invocat…
May 1, 2026
f6afbec
Add Time Off Reason field to MultiDay request payload
May 6, 2026
e68c3ff
fix(workday-da): harden EmployeeUpdateResidentialAddress topic for DA…
May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions ...yeeSelfServiceAgent/WorkdayDA/EmployeeScenarios/EmployeeAddDependents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
nav_exclude: true
search_exclude: false
---
# Workday Employee Add Dependents

## Overview

This topic enables employees to view their existing dependents and add new dependents to their Workday profile through a conversational interface. Dependents include spouses, domestic partners, children, and other family members who may be covered under employee benefits.

## Features

- View existing dependents with their relationship and date of birth
- Add new dependents (spouse, child, domestic partner, etc.)
- Dynamic relationship type dropdown populated from Workday reference data
- Confirmation flow showing summary of dependent details before submission
- Form validation for required fields

## Snapshots

![Add Dependents](add_dependents.png)

## Trigger Phrases

- "Add a dependent"
- "I want to add my child as a dependent"
- "Add my spouse to my benefits"
- "Register a new dependent"
- "I need to add a family member"
- "Show my dependents"

## Files

| File | Description |
|------|-------------|
| `topic.yaml` | Copilot Studio topic definition with conversation flow |
| `msdyn_HRWorkdayHCMEmployeeGetDependents.xml` | XML template for fetching existing dependents |
| `msdyn_HRWorkdayHCMEmployeeAddDependent.xml` | XML template for adding a new dependent |

## Workday APIs Used

| API | Purpose |
|-----|---------|
| `Human_Resources v45.0` | Fetch existing dependents |
| `Benefits_Administration v45.1` | Add new dependent |

## Flow Overview

```
┌─────────────────────────────────────────────────────────────┐
│ User Triggers Topic │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Fetch Reference Data (Relationship Types) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Fetch Existing Dependents │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Display Existing Dependents (or "No dependents") │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Show Add Dependent Form (Adaptive Card) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Show Confirmation Card │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Submit to Workday │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Show Success/Error Message │
└─────────────────────────────────────────────────────────────┘
```

## Configurations

Environment makers need to configure the following in the topic:

| Configuration | Description | Location in Topic |
|---------------|-------------|-------------------|
| **Gender Options** | Configure available gender options (Male, Female, Not_Declared) | Adaptive card dropdown |
| **Country Codes** | Define available country codes (USA, CAN, GBR, etc.) | Adaptive card dropdown |
| **Workday Icon** | Update the icon URL to match your organization's branding | Topic properties > Icon |
| **Workday URL** | Set your organization's Workday tenant URL | HTTP action or connector configuration |

## Dependencies

- **msdyn_HRWorkdayHCMEmployeeGetDependents template**: Required for fetching existing dependents
- **Employee Context**: Worker ID must be available in the conversation context
Binary file added ...rviceAgent/WorkdayDA/EmployeeScenarios/EmployeeAddDependents/add_dependents.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
65 changes: 65 additions & 0 deletions ...kdayDA/EmployeeScenarios/EmployeeAddDependents/msdyn_HRWorkdayHCMEmployeeAddDependent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<workdayEntityConfigurationTemplate>
<scenario name="msdyn_HRWorkdayHCMEmployeeAddDependent">
<apiRequests>
<apiRequest>
<authType>User</authType>
<endpoint>
<request>Template_AddDependentRequest</request>
<serviceName>Benefits_Administration</serviceName>
<version>v45.1</version>
</endpoint>
<responseProperties>
<property>
<extractPath>//*[local-name()='Dependent_Reference']/*[local-name()='ID' and @*[local-name()='type']='WID']/text()</extractPath>
<key>DependentWID</key>
</property>
<property>
<extractPath>//*[local-name()='Dependent_Reference']/*[local-name()='ID' and @*[local-name()='type']='Dependent_ID']/text()</extractPath>
<key>DependentID</key>
</property>
</responseProperties>
</apiRequest>
</apiRequests>
</scenario>
<requestTemplates>
<requestTemplate name="Template_AddDependentRequest">
<bsvc:Add_Dependent_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v45.1">
<bsvc:Business_Process_Parameters>
<bsvc:Auto_Complete>true</bsvc:Auto_Complete>
<bsvc:Run_Now>true</bsvc:Run_Now>
<bsvc:Discard_On_Exit_Validation_Error>true</bsvc:Discard_On_Exit_Validation_Error>
<bsvc:Comment_Data>
<bsvc:Comment>Dependent added via Copilot</bsvc:Comment>
<bsvc:Worker_Reference>
<bsvc:ID bsvc:type="Employee_ID">{Employee_ID}</bsvc:ID>
</bsvc:Worker_Reference>
</bsvc:Comment_Data>
</bsvc:Business_Process_Parameters>
<bsvc:Add_Dependent_Data>
<bsvc:Employee_Reference>
<bsvc:ID bsvc:type="Employee_ID">{Employee_ID}</bsvc:ID>
</bsvc:Employee_Reference>
<bsvc:Related_Person_Relationship_Reference>
<bsvc:ID bsvc:type="Related_Person_Relationship_ID">{Relationship_Type}</bsvc:ID>
</bsvc:Related_Person_Relationship_Reference>
<bsvc:Use_Employee_Address>true</bsvc:Use_Employee_Address>
<bsvc:Dependent_Personal_Information_Data>
<bsvc:Person_Name_Data>
<bsvc:Name_Detail_Data>
<bsvc:Country_Reference>
<bsvc:ID bsvc:type="ISO_3166-1_Alpha-3_Code">{Country_Code}</bsvc:ID>
</bsvc:Country_Reference>
<bsvc:First_Name>{First_Name}</bsvc:First_Name>
<bsvc:Last_Name>{Last_Name}</bsvc:Last_Name>
</bsvc:Name_Detail_Data>
</bsvc:Person_Name_Data>
<bsvc:Date_of_Birth>{Date_Of_Birth}</bsvc:Date_of_Birth>
<bsvc:Gender_Reference>
<bsvc:ID bsvc:type="Gender_Code">{Gender}</bsvc:ID>
</bsvc:Gender_Reference>
</bsvc:Dependent_Personal_Information_Data>
</bsvc:Add_Dependent_Data>
</bsvc:Add_Dependent_Request>
</requestTemplate>
</requestTemplates>
</workdayEntityConfigurationTemplate>
104 changes: 104 additions & 0 deletions ...dayDA/EmployeeScenarios/EmployeeAddDependents/msdyn_HRWorkdayHCMEmployeeGetDependents.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<workdayEntityConfigurationTemplate>
<scenario name="msdyn_HRWorkdayHCMEmployeeGetDependents">
<apiRequests>
<apiRequest>
<authType>User</authType>
<endpoint>
<request>Template_GetDependentsRequest</request>
<serviceName>Human_Resources</serviceName>
<version>v42.0</version>
</endpoint>
<responseProperties>
<!-- ONLY extract data from Related_Person nodes that have a Dependent child -->
<!-- This ensures all arrays are aligned (only actual dependents) -->

<!-- Dependent ID -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Dependent']/*[local-name()='Dependent_Reference']/*[local-name()='ID' and @*[local-name()='type']='Dependent_ID']/text()</extractPath>
<key>DependentID</key>
</property>
<!-- Dependent WID -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Dependent']/*[local-name()='Dependent_Reference']/*[local-name()='ID' and @*[local-name()='type']='WID']/text()</extractPath>
<key>DependentWID</key>
</property>
<!-- Person WID (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Person_Reference']/*[local-name()='ID' and @*[local-name()='type']='WID']/text()</extractPath>
<key>PersonWID</key>
</property>
<!-- Full Name (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Personal_Data']/*[local-name()='Name_Data']/*[local-name()='Legal_Name_Data']/*[local-name()='Name_Detail_Data']/@*[local-name()='Formatted_Name']</extractPath>
<key>FullName</key>
</property>
<!-- First Name (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Personal_Data']/*[local-name()='Name_Data']/*[local-name()='Legal_Name_Data']/*[local-name()='Name_Detail_Data']/*[local-name()='First_Name']/text()</extractPath>
<key>FirstName</key>
</property>
<!-- Last Name (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Personal_Data']/*[local-name()='Name_Data']/*[local-name()='Legal_Name_Data']/*[local-name()='Name_Detail_Data']/*[local-name()='Last_Name']/text()</extractPath>
<key>LastName</key>
</property>
<!-- Date of Birth (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Personal_Data']/*[local-name()='Personal_Information_Data']/*[local-name()='Birth_Date']/text()</extractPath>
<key>DateOfBirth</key>
</property>
<!-- Gender (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Personal_Data']/*[local-name()='Personal_Information_Data']//*[local-name()='Gender_Reference']/*[local-name()='ID' and @*[local-name()='type']='Gender_Code']/text()</extractPath>
<key>Gender</key>
</property>
<!-- Relationship Type ID (only for dependents) -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Related_Person_Relationship_Reference']/*[local-name()='ID' and @*[local-name()='type']='Related_Person_Relationship_ID']/text()</extractPath>
<key>RelationshipTypeID</key>
</property>
<!-- Full-time Student flag -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Dependent']/*[local-name()='Dependent_Data']/*[local-name()='Full-time_Student']/text()</extractPath>
<key>IsFullTimeStudent</key>
</property>
<!-- Disabled flag -->
<property>
<extractPath>//*[local-name()='Related_Person_Data']/*[local-name()='Related_Person'][*[local-name()='Dependent']]/*[local-name()='Dependent']/*[local-name()='Dependent_Data']/*[local-name()='Disabled']/text()</extractPath>
<key>IsDisabled</key>
</property>
</responseProperties>
</apiRequest>
</apiRequests>
</scenario>
<requestTemplates>
<requestTemplate name="Template_GetDependentsRequest">
<bsvc:Get_Workers_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v42.0">
<bsvc:Request_References bsvc:Skip_Non_Existing_Instances="false" bsvc:Ignore_Invalid_References="true">
<bsvc:Worker_Reference bsvc:Descriptor="Employee_ID">
<bsvc:ID bsvc:type="Employee_ID">{Employee_ID}</bsvc:ID>
</bsvc:Worker_Reference>
</bsvc:Request_References>
<bsvc:Response_Filter>
<bsvc:As_Of_Effective_Date>{As_Of_Effective_Date}</bsvc:As_Of_Effective_Date>
</bsvc:Response_Filter>
<bsvc:Response_Group>
<bsvc:Include_Reference>true</bsvc:Include_Reference>
<bsvc:Include_Personal_Information>false</bsvc:Include_Personal_Information>
<bsvc:Include_Employment_Information>false</bsvc:Include_Employment_Information>
<bsvc:Include_Organizations>false</bsvc:Include_Organizations>
<bsvc:Include_Roles>false</bsvc:Include_Roles>
<bsvc:Include_Management_Chain_Data>false</bsvc:Include_Management_Chain_Data>
<bsvc:Include_Benefit_Enrollments>false</bsvc:Include_Benefit_Enrollments>
<bsvc:Include_Benefit_Eligibility>false</bsvc:Include_Benefit_Eligibility>
<bsvc:Include_Related_Persons>true</bsvc:Include_Related_Persons>
<bsvc:Include_Qualifications>false</bsvc:Include_Qualifications>
<bsvc:Include_Photo>false</bsvc:Include_Photo>
<bsvc:Include_Worker_Documents>false</bsvc:Include_Worker_Documents>
<bsvc:Include_Transaction_Log_Data>false</bsvc:Include_Transaction_Log_Data>
<bsvc:Include_User_Account>false</bsvc:Include_User_Account>
</bsvc:Response_Group>
</bsvc:Get_Workers_Request>
</requestTemplate>
</requestTemplates>
</workdayEntityConfigurationTemplate>
Loading