Skip to content

feat(servicenow): Connect auto-Setup handoff, merged connection step and Test/Prod realm workflow - #507

Open
DapheneShao wants to merge 32 commits into
mainfrom
servicenow-connect-auto-setup-handoff-pr
Open

DapheneShao wants to merge 32 commits into
mainfrom
servicenow-connect-auto-setup-handoff-pr

Conversation

@DapheneShao

@DapheneShao DapheneShao commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Description

ServiceNow Connect (HR and IT) for solutions/ess-maker-skills. This PR combines two parts: the Setup handoff, UX and wording work (formerly this PR) and the independent Test/Prod realm workflow (formerly #509, merged into this branch with no conflicts).

Part 1: Setup handoff, UX and wording

  • Auto-Setup handoff. Connect starts Setup automatically when the workspace or agent isn't prepared (no /setup typing), follows the UX design copy for message 1, and resumes when Setup is incomplete. Setup cancel or blocked wording asks the maker to fix the blocker and then ask to finish setup and connect again. Links to a different environment go through Setup's conflicting-environment flow. Setup's final summary is skipped when resumed from Connect. Supersedes the earlier b303ba7a idea.
  • Create and connect ServiceNow (merged step). Connection creation and agent binding are one maker-visible phase (credential; HR 9 to 8 steps, IT 8 to 7). The maker confirms the connection is created and shows Connected. One merged CREDENTIAL-001 flightcheck verifies the connection inventory and the agent's saved connection reference, with specific recovery wording. Lifecycle schema v13 migrates existing state automatically.
  • Maker-facing wording. Phase cards show only the main-journey wording (lead-in, numbered steps or Ready-to-send message). The Current task, Where and how, Expected evidence and Completion boundary blocks stay in controller JSON and action docs. Native questions no longer show technical key/value headers, and the portal URL question is one plain question.
  • Other copy and flow changes. Learn links in the administrator instructions, shorter legend, Maker role asked once, topic list moved to the agent reply, no Directory (tenant) ID in the Entra message, ServiceNow message always uses the Entra-confirmed claim, fenced copy blocks for the administrator messages, and wording bridges around each step.
  • Conversational-flow messages. Unsupported-agent chooser result and entry-doc Messages for permission denied/unavailable, HR plugin not ready, administrator pause/resume, conflicting Client IDs, unconfirmed custom claim, and existing SSO/Graph conflict.

Part 2: Independent Test and Prod realm workflow (from #509)

The maker says the agent was promoted to Test or Prod, or pastes the Test or Prod agent link, in the same /connect ServiceNow flow (no new slash commands). The controller proves the exact promoted sibling of the recorded Dev agent; a Dev link or a link outside the family is rejected.

  • No Dev lifecycle gate and no Test-before-Prod gate. With no Dev record, Connect asks only for the missing instance and client ID, then the administrator confirms.
  • Read-only checks per realm, reported per item: connection exists, is connected and bound to this agent; instance, client ID and auth type match; required topics are on; portal URL is set.
  • Connection problems are blocked with a plain message and no repair steps; the Dev connection is never suggested. Topics and portal are never edited: fix in Dev, promote again, re-check.
  • State is kept per realm; Dev changes do not invalidate Test or Prod.
  • Wording follows the UX spec (S5): realm intro, Test-pane request, "Done"-only replies are never recorded, "Which destination" question, denied vs. inconclusive access, completion message that says what was and was not verified, and short recovery rules.

BEFORE / AFTER

  • BEFORE: Connect told the maker to type /setup; credential and binding were two steps with a manual attestation; cards showed internal blocks; Test and Prod could not be checked independently.
  • AFTER: Connect hands off to Setup automatically; one "Create and connect ServiceNow" step with an automatic check; maker-only wording; Test and Prod are checked per realm in the same flow.

Unverified and open items

  • No live-tenant run: connection creation, saved-draft binding, topic activation, portal write and Test pane were tested with mocks and fixtures only.
  • Not implemented, pending product decisions: finish without testing, and a follow-up question after a failed test.
  • The portal instance-root rule is agent guidance and is not enforced by the controller.
  • The instance question still contains an environment/realm header.
  • Repair of Test/Prod connections is not yet defined (blocked message only).

Unchanged: Workday, the Entra/ServiceNow administrator instruction files and their SHA pins.

Related issue

Combines #507 and #509 (no GitHub issue).

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactor / cleanup

Testing

  • python -m ruff check solutions tests/scripts tests/setup tests/flightcheck: passed.
  • python -m pytest tests/scripts/test_connect_servicenow_da.py tests/scripts/test_connect_servicenow_realms.py tests/scripts/test_connect_lifecycle.py tests/setup tests/flightcheck (plus telemetry tests): 3410 passed, 2 skipped, 1 failed.
  • The one failure, tests/setup/test_workday_da_orchestration.py::test_workday_topic_activation_uses_complete_mapped_scope, is pre-existing on main and unrelated.

Checklist

  • My code follows the existing style
  • I have added/updated tests where applicable
  • I have updated documentation as needed

Static validation (samples/ only)

Not applicable: this PR does not touch samples/.

S5 wording alignment

Copy-only alignment of the Test/Prod realm wording to conversational_flow.md S5 (spec rev 11): spec-form completion message, "Validation is paused" connection findings, "Retry the access check", new recovery sentences (Dev connection offered, Dev untested, realm change, different instance, empty results, full sign-in admin message), and tone cleanup (no all-caps BLOCKED, "we" instead of "Connect", "your own deployment process" instead of ALM). No logic, state, SHA-pin or administrator-doc changes.

Also replaced the technical preflight discovery message (HTTP timeout wording) with a plain conversational sentence in both admin-preflight actions.

The portal-URL step now shows "Next, we'll make sure the agent's HR case / IT ticket links open in the right employee portal." as a normal reply before the question (HR and IT).

  • Test/Prod: finish without testing is saved as untested, never counted as a pass, and can be resumed later.
    S3/S4: the claim name is now read from the Entra administrator's reply (no up-front claim question), and custom-claim and Knowledge-coexistence recovery messages were added to the Dev flow.

  • Tenant ID is no longer requested from the maker or administrators; the ServiceNow OIDC Metadata URL is filled from the verified environment tenant, and a mismatching tenant in an admin reply is still rejected.

Daphne Shao and others added 10 commits November 16, 2026 13:58
…orkspace or agent is not prepared

Chooser returns an automatic Setup handoff for an unprepared workspace (with or without a pasted agent link) and for a link to an agent new to the workspace. Entry docs follow the Workday prepare-at-entry pattern and the UX continue copy. Replaces the unpushed copy-only commit b303ba7a.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b83a72e2-ae5b-43db-a6be-06dd7e2dcdd8
…er to resume

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b83a72e2-ae5b-43db-a6be-06dd7e2dcdd8
…arate cancel wording

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b83a72e2-ae5b-43db-a6be-06dd7e2dcdd8
Use the design wording for the first handoff message, hand off to Setup's
conflicting-environment flow for links in a different environment, return
directly to Connect without Setup's summary, and name the canonical
environment display-name source.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b83a72e2-ae5b-43db-a6be-06dd7e2dcdd8
Add a setup-incomplete chooser status so a Dev agent with pending Setup steps
is not reported as unavailable. Connect resumes Setup's readiness checks once
per invocation, confirms the agent only after the chooser returns ready, and
passes the environment display name to Setup's attach command.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b83a72e2-ae5b-43db-a6be-06dd7e2dcdd8
Add a full-steps Learn link below each administrator instruction heading and update the pinned instruction hashes and a structure assertion in tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…clause

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…o agent reply

- Reword the Maker configuration availability question to include the
  ESS Maker / Agent Developer role; the phase-start Yes is recorded by the
  controller as the lifecycle role attestation, so agent-connection, topics
  and portal-url no longer show the Confirm role prompt.
- topic-action-handoff returns replyBeforeQuestion (agent, environment,
  hash, inventory and inactive topic list) to show before the card; the card
  question is reduced to the enable/keep decision.
- Align the two legend assertions with the shortened legend text.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Discover the promoted Test or Prod sibling of the recorded Dev agent from natural language or an agent link, reuse the Dev tenant foundation, and check Connections, Runtime configuration and Maker validation per realm.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daphne Shao and others added 16 commits November 16, 2026 23:36
… message

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…he copy block

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add short wording before the fenced message for the HRSD plugin card,
the Entra handoff and the ServiceNow handoff. Fenced bodies unchanged.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…st-result finish

Wording only: connection, agent-connection, portal-url and test lead-ins; new first sentence of the portal URL question; final text states what the Maker-reported Test result covers.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Merge the credential and agent-connection phases into a single 'Create and connect ServiceNow' phase (HRSD 9->8, ITSM 8->7).

- One instruction card; the maker confirms the connection is created and Connected.
- One merged CREDENTIAL-001 flightcheck: connector-scoped inventory proof AND the agent's saved draft connection-reference proof. No manual attestation gate.
- Recovery wording for not-selected, bound-elsewhere and binding-mismatch.
- Lifecycle schema v13 migrates old credential + agent-connection states.
- Merge prepare-credential.md and connect-agent.md; update docs and tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove Current task, Where and how, Expected nonsecret evidence, and
Completion boundary from maker-visible cards (HR + ITSM). Cards now keep the
main-journey lead-in, numbered steps or Ready-to-send message. Internal facts
stay in controller JSON and action docs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Portal URL, portal fallback, reuse, test, credential, plugin and topics questions no longer show key/value headers; portal question is one plain paragraph. Wording only.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…sages

Add the unsupported-agent chooser result and entry-doc Messages for permission denied/unavailable, HR plugin not ready, admin pause/resume, conflicting Client IDs, unconfirmed custom claim, and existing SSO/Graph conflict, with tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove the Dev-Ready and Test-Ready gates; Dev record is an optional reference. Per-item read-only connection, topic and portal checks per realm. Connection problems are blocked with no repair or handoff and never reuse the Dev connection. Admin-confirmed values are retained only when they still apply to the agent, tenant and instance.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add the realm intro, Test-pane request, Done follow-up, completion scope, destination question, denied vs inconclusive access, and J/K/L/M recovery wording. Wording only; no state changes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@DapheneShao DapheneShao changed the title feat(servicenow): hand off from Connect to Setup automatically feat(servicenow): Connect auto-Setup handoff, merged connection step and Test/Prod realm workflow Nov 18, 2026
Daphne Shao and others added 2 commits November 17, 2026 22:00
…onal flow S5

Copy-only alignment with the S5 spec (rev 11): spec-form completion message, 'Validation is paused' connection findings, 'Retry the access check', recovery sentences for Dev-connection offers, untested Dev, realm changes, different instance, empty results and the full sign-in admin message. Tone cleanup: no all-caps BLOCKED, 'we' instead of 'Connect', 'your own deployment process' instead of ALM. No logic changes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the technical timeout wording in the maker-visible preflight message with a short conversational sentence. Agent-facing progress-marker instructions are unchanged.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daphne Shao and others added 4 commits November 17, 2026 22:27
Add the maker-visible message before the portal URL question in both HR and IT action docs, and use 'ticket' wording in the IT controller lead-in. Wording only.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add an untested outcome for realm maker validation: saved in realms.json,
never counted as a pass, shown as untested in status, and replaced by a
later pass or fail run. Dev flow is unchanged.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Stop asking the maker for the User Claim up front; read it from the Entra administrator reply and ask a follow-up only when it is missing. Add the S4 coordination asks to the Entra handoff lead-in and S3/S4 branch Messages to the shared entry guide.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove the tenant ID from the maker-supplied values, the realms re-approval
trigger, the ServiceNow OIDC guide and the servicenow-stage error. The OIDC
Metadata URL stays auto-filled from the verified environment tenant and a
mismatching admin-supplied tenant is still rejected.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant