You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This topic lets employees submit single-day or multi-day time off requests to Workday directly from a Copilot Studio agent.
8
8
9
-
This topic enables employees to submit time off requests through a conversational interface with their Copilot Studio agent. Employees can request single-day or multi-day time off by specifying dates and selecting from available time off types (e.g., vacation, sick leave, personal time).
9
+
When an employee triggers this topic, the agent:
10
10
11
-
## Features
11
+
1. Fetches current leave balances from Workday
12
+
2. Shows an Adaptive Card form with leave type, dates, hours, and reason
13
+
3. Submits the request to the Workday `Enter_Time_Off` API
14
+
4. Displays a confirmation card or a friendly error with retry options
12
15
13
-
- Request single-day or multi-day time off
14
-
- Display available time off types dynamically from Workday
15
-
- Validate date inputs for business logic compliance
16
-
- Submit time off requests directly to Workday
17
-
- Confirmation of successful submission
16
+
**Example trigger phrases:** "Request time off" · "Request vacation from January 5th to January 10th" · "Submit sick leave for next week"
18
17
19
-
## Snapshots
18
+
19
+
20
20
21
-
21
+
{: .important }
22
+
> This topic ships with sample values from a reference Workday tenant. Every Workday tenant is configured differently — you must replace the Plan IDs, Reason IDs, leave types, and tenant URL with values from your own Workday setup before importing. See [Configure the topic](#configure-the-topic) for details.
22
23
23
-
## Trigger Phrases
24
+
## Prerequisites
24
25
25
-
- "I want to request time off"
26
-
- "Submit time off request"
27
-
- "I need to take some time off"
28
-
- "Request vacation"
29
-
- "Book time off"
26
+
Before you start, make sure you have:
30
27
31
-
## Files
28
+
- The **msdyn_copilotforemployeeselfservicehr** managed solution installed in your agent
29
+
- A Workday tenant with the **Absence_Management** module enabled
30
+
- A Workday connector configured with **User**-level authentication in your Power Platform environment
31
+
- The global variable **`Global.ESS_UserContext_Employee_Id`** populated at session start with the logged-in employee's Workday Employee ID
32
+
- The **`msdyn_HRWorkdayHCMEmployeeGetVacationBalance`** template already imported (from the [EmployeeGetVacationBalance](../EmployeeGetVacationBalance/) folder)
33
+
- Your organization's Workday Absence Plan IDs, Time Off Type IDs, and Reason IDs
32
34
33
-
| File | Description |
34
-
|------|-------------|
35
-
|`topic.yaml`| Copilot Studio topic definition with conversation flow |
36
-
|`msdyn_HRWorkdayAbsenceEnterTimeOff_MultiDay.xml`| Workday API request template for multi-day time off |
|`msdyn_HRWorkdayAbsenceEnterTimeOff_MultiDay.xml`| SOAP template for the Workday `Enter_Time_Off` API | Usually no |
41
+
|`requestTimeOffAdapativeCard.png`| Screenshot of the Adaptive Card form | No |
42
+
|`requestTimeOffSubmitted.png`| Screenshot of the confirmation card | No |
43
+
|`README.md`| This file | No |
39
44
40
-
| API | Purpose |
41
-
|-----|---------|
42
-
|`Get_Time_Off_Types`| Retrieves available time off types for the employee |
43
-
|`Enter_Time_Off`| Submits the time off request to Workday |
45
+
## Import the templates
44
46
45
-
## Flow Overview
47
+
Before configuring the topic, import the XML templates into your agent.
46
48
49
+
1. Add `msdyn_HRWorkdayAbsenceEnterTimeOff_MultiDay.xml` to your agent's ESS Template Configuration.
50
+
51
+
2. If you haven't already, import the balance template `msdyn_HRWorkdayHCMEmployeeGetVacationBalance` from the [EmployeeGetVacationBalance](../EmployeeGetVacationBalance/) folder. This topic calls it to display leave balances.
52
+
53
+
## Configure the topic
54
+
55
+
Open `topic.yaml` and update the following values to match your Workday tenant. All sample values shown below come from a reference tenant and **must** be replaced.
56
+
57
+
### Step 1: Set your Workday tenant URL
58
+
59
+
Find the `set_workday_url` node and replace `<TENANT_NAME>` with your tenant name:
Your Workday URL typically follows the pattern `https://<host>.workday.com/<tenant_name>/home.htmld`. Check your browser address bar when logged into Workday.
70
+
71
+
### Step 2: Update Plan IDs
72
+
73
+
Find the `set_plan_config` node. Replace each `PlanID` with the corresponding ID from your Workday tenant:
You can find your Plan IDs in Workday under **Setup > Absence Plans > Plan ID**. Only plans listed here **and** returned by the Workday API will appear in the balance header.
84
+
85
+
### Step 3: Update Reason IDs
86
+
87
+
Find the **second** `set_time_off_reason_config` node. Replace each `ReasonID` with your tenant's value:
88
+
89
+
| ReasonKey | TimeOffTypeID | ReasonID ← replace this |
|**Time Off Plans**| Configure which time off plans to display balances for | Global variable or condition node |
90
-
|**Time Off Types**| Define the available time off types for selection | Adaptive card or choice options |
91
-
|**Workday Icon**| Update the icon URL to match your organization's branding | Topic properties > Icon |
92
-
|**Workday URL**| Set your organization's Workday tenant URL | HTTP action or connector configuration |
136
+
| What to test | What to expect |
137
+
|-------------|---------------|
138
+
| Say "I want to request time off" | Balance header appears, then the Adaptive Card form |
139
+
| Say "Request vacation from September 15 to September 19" and submit | Success card with date range, type, hours, and reason |
140
+
| Submit with end date before start date | Error: "The end date can't be earlier than the start date"with retry |
141
+
| Select "I don't see my leave type listed" and submit | Redirect message with a link to Workday |
142
+
| Click **Cancel** | "Leave request was cancelled - nothing was submitted" |
143
+
| Submit dates that overlap an existing request | Friendly AI-rewritten error with retry |
144
+
145
+
If balances show as empty but the form appears, your `PlanConfig` Plan IDs likely don't match your Workday tenant.
146
+
147
+
## XML template reference
148
+
149
+
The `msdyn_HRWorkdayAbsenceEnterTimeOff_MultiDay.xml` file is a SOAP template for the Workday `Enter_Time_Off_Request` operation. You usually don't need to edit it — placeholder tokens like `{Employee_ID}` and `{timeoff_Dates}` are filled at runtime.
150
+
151
+
Two settings you might want to change:
152
+
153
+
| Setting | Default | Change if… |
154
+
|---------|---------|------------|
155
+
| `<wd:Auto_Complete>` | `false` (requires manager approval) | Your process skips approval — set to `true` |
156
+
| `<version>` and `wd:version` | `v42.0` | Your tenant uses a different API version |
157
+
158
+
{: .important }
159
+
> If you change the API version, update it in **both** the `<version>` element and the `wd:version` attribute. Mismatched versions cause API errors.
160
+
161
+
## What you can safely edit in the YAML
162
+
163
+
| What | Where in `topic.yaml` |
164
+
|------|----------------------|
165
+
| Workday tenant URL | `set_workday_url` node |
166
+
| Plan IDs | `set_plan_config` node |
167
+
| Reason IDs | Second `set_time_off_reason_config` node |
- `dialog:`references — point to the shared solution
179
+
- `output: binding:` mappings — must match shared dialog outputs
180
+
- XML placeholder tokens (`{Employee_ID}`, `{timeoff_Dates}`, etc.) — filled at runtime
181
+
- The `EmployeeName` input — the model uses it to validate the request is for the logged-in user
93
182
94
183
## Dependencies
95
184
96
-
-**msdyn_HRWorkdayHCMEmployeeGetVacationBalance template**: Required for fetching available time off types
97
-
-**Employee Context**: Worker ID must be available in the conversation context
185
+
This topic depends on three external components:
186
+
187
+
- **Workday `Get_Time_Off_Plan_Balances`** — Absence_Management service, User-level auth. Uses the `msdyn_HRWorkdayHCMEmployeeGetVacationBalance` template from [EmployeeGetVacationBalance](../EmployeeGetVacationBalance/). Called at topic start to show balances.
188
+
189
+
- **Workday `Enter_Time_Off`** — Absence_Management v42.0, User-level auth. Uses the `msdyn_HRWorkdayAbsenceEnterTimeOff_MultiDay` template in this folder. Called after form submission.
190
+
191
+
- **`WorkdaySystemGetCommonExecution` dialog** — from the `msdyn_copilotforemployeeselfservicehr` solution. Executes XML templates against the Workday connector. Must be pre-installed.
192
+
193
+
## Troubleshooting
194
+
195
+
**Balance header is empty or shows all zeros**
196
+
Your `PlanConfig` Plan IDs don't match your Workday tenant, or the balance template isn't imported. Verify the IDs and confirm `msdyn_HRWorkdayHCMEmployeeGetVacationBalance` is in your ESS Template Configuration.
197
+
198
+
**"Something went wrong" when submitting**
199
+
The `ReasonID` values in `TimeOffReasonConfig` don't match your Workday tenant. Check your IDs in Workday under **Setup > Time Off Reasons**.
200
+
201
+
**Authentication error**
202
+
`Global.ESS_UserContext_Employee_Id`is empty or the Workday connector isn't configured. Verify both.
203
+
204
+
**Vacation isn't pre-selected when the user says "request vacation"**
205
+
The keyword mapping uses `Vacation_Hours` but the dropdown value is `ESS_Vacation_Hours`. Update `LeaveTypeConfig` to use `ESS_Vacation_Hours`. See [Open Questions](#open-questions).
206
+
207
+
**Success card shows a raw ID like `ESS_Vacation_Hours`**
208
+
The `Switch()` expression in the success card doesn't match the dropdown values. See [Open Questions](#open-questions).
209
+
210
+
## Tips
211
+
212
+
- Import the balance template **before** this topic — the balance lookup runs at topic start and fails silently if the template is missing.
213
+
- Update `PlanConfig`, `TimeOffReasonConfig`, **and** the Adaptive Card `choices` together — they're interconnected but maintained separately.
214
+
- Test with a real Workday employee ID that has leave balances.
215
+
- Keep `ReasonKey` values as `full_day`, `half_day_am`, `half_day_pm` — they're bound to the Adaptive Card dropdown.
216
+
217
+
## Handle repo updates
218
+
219
+
When this repo publishes a new version of the topic:
220
+
221
+
1. **Diff first.** Your customized tenant URL, Plan IDs, Reason IDs, and leave-type keywords will be overwritten if you re-import `topic.yaml`.
222
+
2. **Merge.** Copy your config values from the current topic, pull the updated file, paste your values back, then import.
223
+
3. The XML template is safe to overwrite — unless you changed `Auto_Complete` or the API version.
224
+
225
+
## Known limitations
226
+
227
+
- **Leave type pre-selection may not work for Vacation and Floating Holiday.** The keyword mapping (`LeaveTypeConfig`) uses `Vacation_Hours` and `Floating_Holiday_Hours`, but the Adaptive Card dropdown expects `ESS_Vacation_Hours` and `ESS_Floating_Holiday_Hours`. To fix this, update the `LeaveTypeValue` entries in `LeaveTypeConfig` to include the `ESS_` prefix.
228
+
229
+
- **Success card may show raw IDs instead of friendly names.** After a successful submission, the confirmation card may display `ESS_Vacation_Hours` instead of "Vacation". To work around this, update the `Switch()` expression in the success card to match the `ESS_`-prefixed values from the dropdown.
0 commit comments