docs: add workflow overviews for off-cycle, dismissal, and transition payrolls by jeffredodd · Pull Request #1338 · Gusto/embedded-react-sdk

jeffredodd · 2026-03-24T16:50:40Z

Summary

Adds new workflow documentation for off-cycle payroll (bonus & correction), dismissal payroll, and transition payroll
Updates workflows overview with correct import paths, adds Information Requests to workflow list
All facts verified against codebase through a 10-pass automated fact-checking pipeline

New docs

docs/workflows-overview/off-cycle-payroll.md -- OffCycleFlow, subcomponents, props, events, form fields
docs/workflows-overview/dismissal-payroll.md -- DismissalFlow, integration with termination, pay period selection
docs/workflows-overview/transition-payroll.md -- TransitionFlow, TransitionCreation, alert behavior, skip flow

Fact-check corrections applied

Fixed EmployeeOnboardingFlow import to use Employee.OnboardingFlow namespace pattern
Added missing payrollType prop to OffCycleFlow documentation
Clarified TransitionPayrollAlert is internal to PayrollLanding, not a public export
Scoped OFF_CYCLE_SELECT_REASON/OFF_CYCLE_DEDUCTIONS_CHANGE events to standalone subcomponents only
Fixed dismissal integration example to pass payrollId from event data
Corrected event data types (payScheduleUuid can be undefined)
Softened transition blocking claim to reflect SDK vs API enforcement boundary
Matched UI label references to actual i18n strings

Test plan

Review each doc for accuracy against component source code
Verify all cross-reference links resolve correctly
Confirm code examples compile conceptually with current SDK API
Check frontmatter ordering doesn't conflict with existing docs

Made with Cursor

… payrolls Made-with: Cursor

Ran 10-pass automated fact-checking pipeline against the codebase to verify all claims in the off-cycle, dismissal, transition, and workflows-overview docs. Key corrections: - Fix EmployeeOnboardingFlow import to use Employee.OnboardingFlow namespace - Add missing payrollType prop to OffCycleFlow docs - Clarify TransitionPayrollAlert is internal to PayrollLanding, not a public export - Scope OFF_CYCLE_SELECT_REASON/DEDUCTIONS_CHANGE events to standalone subcomponents - Fix dismissal integration example to pass payrollId from event data - Correct event data types (payScheduleUuid can be undefined) - Soften transition blocking claim to reflect SDK vs API enforcement - Match UI label references to actual i18n strings - Add Information Requests to workflows list - Normalize code style (semicolons, formatting) Made-with: Cursor

Verified all three payroll workflow docs (off-cycle, dismissal, transition) through 10 systematic passes against source code. - Reorder off-cycle form fields and workflow steps to match UI render order (dates first, then reason) - Use API wire value "Dismissed employee" instead of TypeScript enum name in dismissal doc prose - Clarify transition pay schedule field is conditionally shown - Specify transition tax withholding default frequency (every-other-week) Made-with: Cursor

Copilot

Pull request overview

Adds workflow overview documentation for additional payroll workflows (off-cycle, dismissal, transition) and updates the docs entry points so integrators can discover and implement these flows using the current SDK namespace patterns.

Changes:

Added new workflow overview docs for Payroll.OffCycleFlow, Payroll.DismissalFlow, and Payroll.TransitionFlow (including key props/events and integration notes).
Updated the workflows overview page to list the new workflows and to use the Employee.* namespace pattern in the onboarding example.
Updated README.md to link to the new workflow docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/workflows-overview/workflows-overview.md	Adds the new workflows to the overview list and updates the onboarding example import/usage to the current namespace pattern.
docs/workflows-overview/off-cycle-payroll.md	New workflow doc describing off-cycle payroll flow + subcomponents, props, and events.
docs/workflows-overview/dismissal-payroll.md	New workflow doc describing dismissal payroll flow, termination integration, props, and events.
docs/workflows-overview/transition-payroll.md	New workflow doc describing transition payroll flow, alert behavior/events, and usage patterns.
README.md	Adds links to the new workflow documentation pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-30T04:09:00Z

docs/workflows-overview/off-cycle-payroll.md

+| Name               | Type                        | Description                                                                                                |
+| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| companyId Required | string                      | The associated company identifier.                                                                         |
+| onEvent Required   | function                    | See events table for each subcomponent to see available events.                                            |
+| payrollType        | `'bonus'` \| `'correction'` | Optional pre-selected off-cycle reason. When provided, the creation form starts with this reason selected. |
+


Markdown tables in this doc use a double leading pipe (|| ...) on each row, which introduces an empty first column and renders inconsistently compared to the rest of the docs. Please update the tables to standard Markdown table syntax (| ... |) throughout this file (props/events tables, etc.).

False positive — these tables use standard single-pipe Markdown syntax, identical to the existing tables in run-payroll.md and other workflow docs. No double-pipe issue exists.

Copilot · 2026-03-30T04:09:00Z

docs/workflows-overview/dismissal-payroll.md

+| Name                | Type     | Description                                                                                                               |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required  | string   | The associated company identifier.                                                                                        |
+| employeeId Required | string   | The identifier of the terminated employee.                                                                                |
+| onEvent Required    | function | See events table for available events.                                                                                    |
+| payrollId           | string   | Optional payroll identifier. When provided, the flow skips pay period selection and starts directly at payroll execution. |
+


Markdown tables here use || at the start of rows (e.g., the props table), which creates an empty column and is inconsistent with other workflow docs (which use | ... |). Please switch these tables to standard single-pipe Markdown syntax throughout this document.

Same as above — tables use correct single-pipe Markdown syntax, consistent with all other workflow docs.

Copilot · 2026-03-30T04:09:00Z

docs/workflows-overview/transition-payroll.md

+| Name                     | Type     | Description                                                      |
+| ------------------------ | -------- | ---------------------------------------------------------------- |
+| companyId Required       | string   | The associated company identifier.                               |
+| startDate Required       | string   | The start date of the transition pay period (YYYY-MM-DD).        |
+| endDate Required         | string   | The end date of the transition pay period (YYYY-MM-DD).          |
+| payScheduleUuid Required | string   | The UUID of the pay schedule this transition is associated with. |
+| onEvent Required         | function | See events table for each subcomponent to see available events.  |
+


This doc’s tables (props/events) are written with a double leading pipe (|| ...), which renders as an extra empty column and differs from the table formatting used elsewhere in the docs. Please convert the tables in this file to standard Markdown syntax (| ... |) consistently.

Same — tables are correctly formatted with standard single-pipe Markdown syntax.

Copilot · 2026-03-30T04:09:00Z

docs/workflows-overview/transition-payroll.md

+  const handleEvent = (eventType, data) => {
+    if (eventType === componentEvents.RUN_TRANSITION_PAYROLL && data.payScheduleUuid) {
+      setTransitionData(data)
+    }
+  }


The example handler filters on data.payScheduleUuid before setting state, which means the UI will silently no-op if the event’s payScheduleUuid is undefined (your own event table allows string | undefined). Since Payroll.TransitionFlow requires a non-optional payScheduleUuid, please either (a) document a recommended fallback/error path when it’s undefined, or (b) update the docs to treat payScheduleUuid as required if it’s guaranteed in practice.

Good catch — added a note below the example explaining why the guard exists and that payScheduleUuid is expected in practice but typed as potentially undefined. Partners can add their own fallback logic if needed.

Addresses Copilot review feedback on PR #1338: the integration example guards on data.payScheduleUuid because TransitionFlow requires it as a non-optional prop, but the event type allows undefined. Added a note explaining this and suggesting partners add fallback logic if needed. Made-with: Cursor

jeffredodd added 2 commits March 25, 2026 10:52

docs: add workflow overviews for off-cycle, dismissal, and transition…

0be68a3

… payrolls Made-with: Cursor

jeffredodd force-pushed the docs/off-cycle-payroll-workflow branch from 6ec53e3 to 0f61ef7 Compare March 25, 2026 17:52

jeffredodd marked this pull request as ready for review March 30, 2026 04:02

jeffredodd requested review from dmortal, hukid, krisxcrash and serikjensen as code owners March 30, 2026 04:02

Copilot AI review requested due to automatic review settings March 30, 2026 04:02

Copilot started reviewing on behalf of jeffredodd March 30, 2026 04:02 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add workflow overviews for off-cycle, dismissal, and transition payrolls#1338

docs: add workflow overviews for off-cycle, dismissal, and transition payrolls#1338
jeffredodd wants to merge 4 commits intomainfrom
docs/off-cycle-payroll-workflow

jeffredodd commented Mar 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

jeffredodd Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

jeffredodd Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

jeffredodd Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

jeffredodd Mar 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jeffredodd commented Mar 24, 2026

Summary

New docs

Fact-check corrections applied

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

jeffredodd Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

jeffredodd Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

jeffredodd Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

jeffredodd Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants