PR #9: Reference documentation - #19
Conversation
This branch will be populated via scoped PRs reviewed by Graham, John, and Cavill. Once all PRs are merged here, main2 will replace main.
Adds the ESS reference documentation under solutions/ess-agent-kit/src/reference/ess-docs/: - customization/ - agent customization patterns - deployment/ - deployment guidance - flightcheck/ - FlightCheck usage docs - integrations/ - ServiceNow, Workday integration guides - operations/ - operational guidance 46 markdown files. Pulled together from official Microsoft documentation; review for accuracy and any internal-only references. Reviewer: @CavillMason Tracker: #10
rename solutions/ess-agent-kit -> solutions/ess-maker-skills
John Nguyen (johnguy0)
left a comment
There was a problem hiding this comment.
47 files, 10456 lines. The bulk is well-written, well-organized, and SFI-clean for actual content. Specifically scanned for ICM, internal Microsoft tools (Geneva/Kusto/Cosmos/Aether), internal usernames, hardcoded user paths, internal aka.ms links, and TODO/FIXME markers — all clean. workday-isu-debugging.md (724 lines) is solid customer-facing debugging guidance with the right escalation path for external users (HAR traces, Postman tests, config checklists), not Microsoft-internal tooling. rai-faq.md matches Microsoft's public RAI guidance. customize.md and the integration guides are appropriate public docs.
The defects are concentrated in three areas: a real-looking tenant GUID embedded in a sample report, broken cross-references, and missing image assets.
CRITICAL:
-
flightcheck/report-template.html:132ships a sample HTML report containingMicrosoft Entra ID configured: EmployeeHub (Tenant: 935884d7-bdee-469b-a461-fcc530a3ac83). The GUID is unique in the repo (no other reference). Combined with the customer-sounding deployment nameEmployeeHub, this looks like a real flightcheck output captured and shipped as a template. Two scenarios:- If the GUID is a real tenant (Microsoft's, a customer's, or a partner's), this is an information leak in a public OSS repo.
- If the GUID is fictional, the convention should be obvious — use a documented placeholder like
00000000-0000-0000-0000-000000000000and a generic name likeContoso ESS Agentso no reader has to wonder.
Replace with a documented placeholder regardless of which case applies. Same treatment for any other sample data in the HTML template I might have missed (didn't audit the full 1300-ish lines of HTML).
HIGH:
-
overview.mdhas 4 broken cross-references (lines 58, 72, 88, 89). The relative paths don't match where files actually land in this PR:(customize.md)— file is atcustomization/customize.md(../microsoft-365-copilot-architecture.md)— doesn't exist anywhere(sap-employee-read-write-scenarios.md)— file is atintegrations/sap-employee-read-write-scenarios.md(sap-manager-read-write-scenarios.md)— file is atintegrations/sap-manager-read-write-scenarios.md
-
Missing
media/ess/directory breaks images across multiple docs.overview.md:70,workday.md:12, 96, 150, 178+, and others reference../media/ess/*.png. The directory doesn't exist in this PR. Either ship the images or replace with text descriptions or external Microsoft Learn-hosted equivalents. -
overview.md:3has a malformedaka.mslink:https://aka.ms//gablog(double slash). May resolve, may not — depends on aka.ms's redirect handling. Single-character fix.
MEDIUM:
-
operations/auditing-logging.md:21has a tracking parameter on a Microsoft blog link (?msockid=1614e9ffd18265002a76fcabd0016456). Themsockidis a marketing/session tracking parameter that doesn't belong in canonical doc URLs. Strip the query string. -
customization/optimization-sharepoint.md:203links tomicrosoft.github.io/TechExcel-...— a GitHub Pages site, not Microsoft Learn. Pages content can be unpublished without deprecation notice. Either find the equivalent onlearn.microsoft.com, mirror the content into this kit's docs, or label it as an external community resource that may go away. -
Cross-PR coordination —
my/paths inflightcheck/permissions-required.md:68, 72,flightcheck/remediation-guide.md:47. Same recurring concern from PRs #6/#7/#8 — these change ifmy/→workspace/+.local/lands per PR #2. Per the mapping,my/config.json→.local/config.json.
LOW:
-
customization/agent-handoff.md:67— YouTube video link without a descriptor that it's a video. Add[YouTube video walkthrough]so users know what they're clicking. -
integrations/servicenow-connector-setup-scripts.md:3referenceshttps://github.com/microsoft/copilot-servicenow-connector-setup-scripts. Verify that repo is public and the link resolves before merge — if it's still private or doesn't exist, the link 404s.
Dismissed (audit agent over-graded):
MicrosoftGraphConnectorsFeedback@service.microsoft.cominservicenow-knowledge-troubleshooting.md:18is a public Microsoft Graph Connector support address. The kit's SUPPORT.md correctly says the kit isn't Microsoft-supported, but pointing customers at the connector team for connector issues is appropriate. Not a leak.
PR-level:
- PR description still references
solutions/ess-agent-kit/instead ofsolutions/ess-maker-skills/. Eighth PR with this issue across PRs #2-#9. This is now a pattern. Worth catching upstream in whatever generates PR descriptions.
Inline below.
| <td>Authentication</td> | ||
| <td>Critical</td> | ||
| <td class="status-passed">Passed</td> | ||
| <td>Microsoft Entra ID configured: EmployeeHub (Tenant: 935884d7-bdee-469b-a461-fcc530a3ac83)</td> |
There was a problem hiding this comment.
CRITICAL — sample report contains a tenant GUID and product-sounding name.
Microsoft Entra ID configured: EmployeeHub (Tenant: 935884d7-bdee-469b-a461-fcc530a3ac83) is unique in the repo (only this line). The combination of EmployeeHub (looks like a real deployment / product name) and a 32-char GUID in tenant position reads as captured-real-data, not as a fictional sample.
If the GUID is real (Microsoft's, a partner's, or a customer's), this is an information leak in a public Microsoft OSS repo. If it's fictional, the convention should make that obvious.
Fix: replace with a documented placeholder pattern, regardless of which case applies.
<td>Microsoft Entra ID configured: Contoso ESS Agent (Tenant: 00000000-0000-0000-0000-000000000000)</td>While you're in this file: audit the full HTML template for any other GUIDs, names, URLs, or IDs that look like captured real data. Report templates are exactly the kind of file where a single test run's output gets shipped as the template by accident. Worth a sweep for IDs that don't match the 00000000-... or Contoso placeholder convention.
|
|
||
| ## Implementation considerations | ||
|
|
||
| Consider which Employee Self-Service agent starter is right for your organization to start with – HR or IT. Both Employee Self-Service agent starter can be deployed into a single Employee Self-Service agent experience, but you must deploy them one at a time. [Learn more](customize.md) about how to get started customizing the Employee Self-Service agent, common roles and responsibilities, and basic agent building blocks. |
There was a problem hiding this comment.
HIGH — broken cross-reference. (customize.md) resolves relative to this file's location (ess-docs/) but the file is at ess-docs/customization/customize.md. Link 404s.
Fix:
[Learn more](customization/customize.md)
Same issue type at line 72 ((../microsoft-365-copilot-architecture.md) — doesn't exist anywhere; either remove the link or redirect to a public Microsoft Learn page), line 88 ((sap-employee-read-write-scenarios.md) → (integrations/sap-employee-read-write-scenarios.md)), and line 89 ((sap-manager-read-write-scenarios.md) → (integrations/sap-manager-read-write-scenarios.md)).
| @@ -0,0 +1,126 @@ | |||
| # Employee Self-Service | |||
|
|
|||
| As part of our general availability release, access is rolling out in waves, starting with managed customers and expanding to all customers over time. If you’d like to explore access sooner, reach out to your Microsoft account team. If you don’t currently have an account team, keep an eye on [this blog post](https://aka.ms//gablog) for updates on when the Employee Self-Service Agent is available to all customers in Copilot Studio. | |||
There was a problem hiding this comment.
HIGH — https://aka.ms//gablog has a double slash.
Depending on aka.ms's redirect handling, this may resolve, may not, or may resolve to a different target than intended. One-character fix:
[this blog post](https://aka.ms/gablog)
Verify the link resolves to the intended ESS GA blog post before merge.
|
|
||
| The Employee Self-Service agent consists of three main parts: the agent itself, domain topic packages, and Power Platform connectors and actions. | ||
|
|
||
| [](../media/ess/structure-big.png#lightbox) |
There was a problem hiding this comment.
HIGH — missing media/ess/ directory breaks images here and across multiple docs.
This line references ../media/ess/structure-big.png. The media/ess/ directory doesn't exist in this PR. Same issue affects:
integrations/workday.md:12, 96, 150, 178(workday-1.png through workday-4.png+)integrations/sapsuccessfactors.md(per audit)- Other docs with
../media/ess/references
Three options:
- Ship the images in this PR under
solutions/ess-maker-skills/src/reference/media/ess/. - Replace with text descriptions. The alt text in the markdown links already describes what the image shows.
- Link to public Microsoft Learn-hosted equivalents if the source docs are public.
Don't ship the docs with broken images. Either land the assets or remove the references.
|
|
||
| [Manage Dataverse auditing](/power-platform/admin/manage-dataverse-auditing) | ||
|
|
||
| [Integrate Microsoft Sentinel and Power Platform to better monitor and protect your low-code solutions.](https://www.microsoft.com/power-platform/blog/power-apps/integrating-microsoft-sentinel-and-power-platform-to-better-monitor-and-protect-your-low-code-solutions/?msockid=1614e9ffd18265002a76fcabd0016456) |
There was a problem hiding this comment.
MEDIUM — strip the msockid tracking parameter.
The URL has ?msockid=1614e9ffd18265002a76fcabd0016456 appended. That's a Microsoft session/tracking parameter that doesn't belong in canonical docs — it ties the link to whoever copied it from their browser. Strip the query string:
https://www.microsoft.com/power-platform/blog/power-apps/integrating-microsoft-sentinel-and-power-platform-to-better-monitor-and-protect-your-low-code-solutions/
Worth a quick grep across the rest of the docs (grep -rEn '\?msockid=') to make sure no other links carry the same artifact.
|
|
||
| ## Resources | ||
|
|
||
| - [Add a SharePoint site, hub, or page as a knowledge source in Copilot Studio](https://microsoft.github.io/TechExcel-Designing-your-own-copilot-using-copilot-studio/docs/Ex05/0502.html) |
There was a problem hiding this comment.
MEDIUM — github.io link can disappear without notice.
https://microsoft.github.io/TechExcel-Designing-your-own-copilot-using-copilot-studio/... is a GitHub Pages site, not Microsoft Learn. GitHub Pages content can be unpublished or restructured without redirect, and SFI/MSRC won't notice when public docs link to a stale tutorial.
Three options:
- Find an equivalent on
learn.microsoft.comand link there. - Mirror the relevant content into this kit's docs.
- Keep the link but add a label:
[external community walkthrough — may move](URL)so readers understand the stability.
| 1. **Environment variables** — if already set (e.g., from a CI pipeline) | ||
| 2. **`.vscode/mcp.json`** — base URL and tenant are read directly (they're | ||
| not secrets). Username/password use `${input:...}` so they can't be read. | ||
| 3. **`my/config.json`** → `connections.Workday` — tenant and base URL from |
There was a problem hiding this comment.
MEDIUM — cross-PR my/ path coordination.
This line and line 72 reference my/config.json. Same recurring concern from PRs #6, #7, #8 — these paths change if my/ → workspace/ + .local/ lands per PR #2 review.
Mapping: my/config.json → .local/config.json (kit bookkeeping, not user-edited).
Also applies to flightcheck/remediation-guide.md:47. Bulk-update across all src/reference/ files when the rename lands.
|
|
||
| ## Handoff in action | ||
|
|
||
| Check out [this video](https://www.youtube.com/watch?v=UzAOD6DreA0&list=PLR9nK3mnD-OUov7JnGBoy_u3TwSrIT1Ln&index=2) to see an example of the Employee Self-Service agent handoff. |
There was a problem hiding this comment.
LOW — label the YouTube link as a video.
Check out [this video](https://www.youtube.com/watch?v=...) is fine-ish, but readers behind YouTube-blocking firewalls (common in regulated industries) won't realize it's a video link until they click. Be explicit:
Check out [this YouTube video walkthrough](URL) to see an example.
Also consider: is there a transcript or text summary? If yes, link it next to the video. Accessibility for users who can't consume video content.
| @@ -0,0 +1,68 @@ | |||
| # ServiceNow Knowledge — Microsoft 365 Copilot Connector Setup Scripts | |||
|
|
|||
| Source: https://github.com/microsoft/copilot-servicenow-connector-setup-scripts | |||
There was a problem hiding this comment.
LOW — verify the linked GitHub repo is public.
https://github.com/microsoft/copilot-servicenow-connector-setup-scripts is referenced as the source. If this repo is internal-only or doesn't exist yet, the link 404s for external users.
Quick check before merge:
curl -I https://github.com/microsoft/copilot-servicenow-connector-setup-scripts
If the repo isn't public yet, either remove the "Source:" line, replace with the canonical Microsoft Learn doc that references those scripts, or wait to merge this PR until the linked repo is public.
|
This PR was auto-closed when |
Adds the ESS reference documentation under
solutions/ess-agent-kit/src/reference/ess-docs/:customization/ΓÇö agent customization patternsdeployment/ΓÇö deployment guidanceflightcheck/ΓÇö FlightCheck usage docsintegrations/ΓÇö ServiceNow, Workday integration guidesoperations/ΓÇö operational guidance46 markdown files. Pulled together from official Microsoft documentation; review for accuracy and any internal-only references.
Tracker: #10