Home / admin / client-onboarding-design
client-onboarding-design
Use this skill when designing the FSC client onboarding process — mapping document collection touchpoints, approval steps, compliance checkpoint sequencing, and welcome journey handoffs. Trigger keywords: client onboarding design, onboarding workflow requirements, document collection flow, compliance checkpoint, welcome journey, intake process design. NOT for configuring the Action Plan template itself — use admin/fsc-action-plans. NOT for OmniScript screen and branching requirements — use admin/omniscript-flow-design-requirements.
Open the skill folder on GitHub
Client Onboarding Design
This skill activates when a practitioner needs to design the end-to-end FSC client onboarding process: document collection touchpoints, compliance checkpoint sequencing, approval steps, and welcome journey handoffs, before any platform configuration begins. It does NOT cover Action Plan template configuration mechanics (see admin/fsc-action-plans), OmniStudio component implementation, or Flow construction.
Licence gate: Action Plan templates need the IndustriesActionPlans license (plus Customize Application to create them). Document checklist items are documented in the Financial Services Cloud developer guide, and some of their fields exist only with Integrated Onboarding for Agentforce Financial Services enabled.
Before Starting
Gather this context before working on anything in this domain:
- Confirm whether OmniStudio is available in the org (check installed packages and licences). If it is not, standard Screen Flows are the native fallback for guided intake. UNVERIFIED (2026-10-03): that OmniStudio is always a separately licensed add-on to FSC is a commercial claim not stated in the guides read.
- Identify the regulatory sequencing rules (KYC before account funding, consent before data processing). They drive the workflow structure and cannot be traded for UX convenience.
- Understand template versioning before designing governance. Each template has versions (
ActionPlanTemplateVersion) whoseStatusisDraft,Final(published),Obsolete, orReadOnly, and a plan can only be created from a published version. Design who owns new versions and how in-flight plans are handled. - Establish the anchor record. The Metadata API lists supported template parents as Account, BusinessMilestone, Campaign, Case, Claim, Contact, Contract, InsurancePolicy, InsurancePolicyCoverage, Lead, Opportunity, PersonLifeEvent, Visit, and custom objects with activities. The object reference lists Financial Account as a plan parent from API 48.0. Confirm the anchor in a sandbox before committing.
Questions to Ask Before Configuring
Ask these before drawing the process map. Each one traces to a gotcha in references/gotchas.md.
| Question | Why it matters | What a good answer adds | What proper configuration adds over just doing it |
|---|---|---|---|
| "Which steps must finish before the next can start, by regulation?" | Sequencing between items is an explicit dependency (OnPreviousItemCompleted), not a side effect of marking a task required (gotcha 2) | The dependency pairs, each with its legal basis | A plan that cannot send funding instructions before KYC is complete |
| "Which record anchors onboarding: Account, Financial Account, Opportunity?" | Template parent support differs between the Metadata API list and the plan object list (gotcha 3) | One anchor object, tested in a sandbox | Templates that launch from the record users actually work on |
| "Which documents are required, and can a document ever be waived?" | Document checklist items have Status values Accepted, New, Pending, Waived, and IsRequired cannot be changed after creation (gotcha 5) | A document list with required flags and a waiver policy | Document tracking that matches compliance rules from the first client |
| "How will the process change after go-live, and what happens to clients mid-onboarding?" | A plan stays bound to the published version it was created from (gotcha 1) | A version owner, a change protocol, and an in-flight policy | Regulatory changes shipped as a reviewed new version, not an emergency edit |
| "Are SLAs in calendar days, weekdays, or business days with holidays?" | Due dates come from StartDate + N formulas; holiday handling is a plan-level flag (gotcha 4) | The SLA definition per gate | Due dates that compliance agrees with |
| "Is OmniStudio available, or is Screen Flow the intake tool?" | Designing OmniScript intake without the product causes rework (gotcha 6) | The intake tool with its licence basis | An intake design the team can build |
What a proper onboarding design adds over "just building tasks": the platform enforces the regulatory order, document status is auditable, and process changes reach new clients without disturbing clients already in flight.
Core Concepts
Action Plan Templates as the Task Execution Layer
An Action Plan template is a reusable blueprint (ActionPlanTemplate) with versions (ActionPlanTemplateVersion) holding ordered items (ActionPlanTemplateItem). Each item has an ItemEntityType of Task, Event (API 63.0), RecordAction, or Document Checklist Item, a DisplayOrder, and an IsRequired flag. Item field values are set with actionPlanTemplateItemValue entries; a due date is a formula such as StartDate + 10 on ActivityDate. From API 59.0, actionPlanTemplateItemDependencies make one item wait for another, with creationType OnPreviousItemCompleted in the guide's sample. The deployable form is in references/metadata-examples.md.
Versions and immutability: a version carries IsLocked, MayEdit, ActivationDateTime, and a Version index. A plan's ActionPlanTemplateVersionId must reference a published version at creation. UNVERIFIED (2026-10-03): the exact UI path for revising a published template (clone the template, or create a new version of the same template) is help-only; design governance around "a new published version", whichever path the org's release uses.
OmniStudio vs Screen Flow for Guided Intake
Guided intake can be an OmniScript (where OmniStudio is available) or a Screen Flow. Screen Flow is a standard platform capability and is sufficient for most onboarding intake. Choose after confirming availability.
Compliance Checkpoint Sequencing
Financial services onboarding is regulated. Identify each mandated checkpoint, the minimum sequence, who can clear it, and the escalation path. Common checkpoints: identity verification (KYC/AML), suitability assessment, consent capture, document collection confirmation, and advisor or compliance sign-off. In the platform, a checkpoint becomes a required item, and the order between checkpoints becomes an item dependency or an approval step.
Document Collection
Document checklist items (DocumentChecklistItem, API 47.0) track a required upload against a parent record (ParentRecordId). Status is Accepted, New, Pending, or Waived; IsRequired is set at creation only; IsFrozen locks the item. Document types are deployable as DocumentType metadata (API 59.0), and org behavior as DocumentChecklistSettings (API 55.0).
Welcome Journey Handoffs
The welcome journey starts after the client clears the onboarding gates. Specify the trigger event (a record status change, the plan's ActionPlanState reaching Complete, or an approval outcome), the channel, the timing, and the data payload, clearly enough that the implementation team can configure it without guessing.
Common Patterns
Phased Onboarding with Compliance Gates
When to use: Regulation requires certain steps to finish and be verified before later steps begin, for example KYC clearance before funding instructions.
How it works:
- Map the journey into phases: Pre-Onboarding, Document Collection, Compliance Review, Account Activation, Welcome Journey.
- Define a gate at the end of each phase: a required item whose completion releases the next phase's items through a dependency, or an approval step.
- For each gate record the owner, the SLA, and the escalation path.
- Map the sequence to template items (required gate items, dependencies between them) and to the intake Screen Flow or OmniScript.
- Deliver the process map as a design brief before configuration begins.
Template Versioning Governance
When to use: The business must update onboarding steps after go-live without disrupting clients already in onboarding.
How it works:
- Name a template owner (a role, not a person).
- Define the change protocol: who requests, who approves, and the lead time.
- Publish changes as a new version; plans already created stay on the version they started with.
- Use a naming convention with a version indicator (for example "Client Onboarding v3").
- Define the in-flight rule: clients complete on their starting version unless a regulator-mandated correction requires remediation of open plans.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| OmniStudio available | Guided intake as OmniScript | Purpose-built for multi-step intake |
| OmniStudio not available | Guided intake as Screen Flow | Standard platform capability |
| Regulation requires step order | Required items plus OnPreviousItemCompleted dependencies | The dependency, not the required flag, creates the order |
| Process changes expected after launch | Version governance from day one | Plans stay bound to their published version |
| Simple welcome (single email) | Record-triggered Flow on the trigger field | No Marketing Cloud dependency |
| Multi-step or multi-channel welcome | Marketing Cloud journey entry event | Specify the trigger field and payload at design time |
| Many document types with conditional requirements | Document checklist items as template items, typed with DocumentType | Status per document is visible and auditable |
Recommended Workflow
- Confirm licences and baseline. Check OmniStudio availability, the IndustriesActionPlans license, and the anchor object's support for Action Plans in a sandbox.
- Gather requirements from every stakeholder. Advisors (ownership, SLAs), compliance (mandated checkpoints, legal basis, escalation), operations (document types, waivers, storage), integration (systems notified at handoff).
- Map stages and compliance gates. Produce a phased map with gates, owners, SLAs, and escalation paths, and list each regulatory ordering rule as a dependency pair.
- Define the template item inventory. Per item: name,
ItemEntityType, owner role or queue, due-date formula (StartDate + N), required flag, document type, and the item it depends on. - Specify the intake design. Document the OmniScript or Screen Flow screens, data elements, branching, and record operations for the implementation team.
- Define the welcome journey handoff. Trigger field and value, channel, timing, and payload.
- Deliver governance. Template owner, change protocol, naming convention, and in-flight policy, in place before the first version is published. Hand
references/metadata-examples.mdto the builder as the configuration target.
Review Checklist
- [ ] OmniStudio availability confirmed; intake tool chosen accordingly
- [ ] Every compliance checkpoint has a legal or regulatory basis recorded
- [ ] Every regulatory ordering rule is an item dependency or approval step, not only a required flag
- [ ] Anchor object tested as an Action Plan parent in a sandbox
- [ ] Item inventory complete (name, type, owner, due-date formula, required, document type, dependency)
- [ ] Document waiver policy defined, with
IsRequireddecided at creation - [ ] Version governance documented with a named owner and change protocol
- [ ] Welcome journey handoff specified with trigger, channel, timing, and payload
- [ ] In-flight plan policy documented for version transitions
Salesforce-Specific Gotchas
The deep versions, with sources, live in references/gotchas.md.
| # | Gotcha | One-line consequence |
|---|---|---|
| 1 | Plans stay bound to the published version they started from | A new version does not fix clients already in flight |
| 2 | Order between items needs a dependency, not just IsRequired | Gate tasks exist but nothing stops the next phase |
| 3 | Template parent lists differ between guides | Financial Account anchoring must be tested |
| 4 | Due dates are StartDate + N formulas; holiday handling is a plan flag | "Business day" SLAs drift from compliance's definition |
| 5 | Document checklist IsRequired is fixed at creation | Waivers must use Waived, not an edit to the flag |
| 6 | OmniStudio availability must be confirmed | OmniScript designs stall without the product |
| 7 | A 75-item ceiling is unconfirmed | Very large templates need a sandbox test |
Output Artifacts
| Artifact | Description |
|---|---|
| Onboarding process map | Phases with gates, owners, SLAs, and compliance checkpoints |
| Template item inventory | Per item: type, owner, due-date formula, required flag, document type, dependency |
| Technology selection rationale | OmniStudio vs Screen Flow with licence basis |
| Welcome journey handoff spec | Trigger, channel, timing, and data payload |
| Version governance | Owner, change protocol, naming convention, in-flight policy |
Related Skills
admin/fsc-action-plans: Action Plan template configuration mechanics; use after this skill's item inventory is completeadmin/compliance-documentation-requirements: which compliance checkpoints are legally mandatoryadmin/financial-account-setup: the FinancialAccount data model when it is the onboarding anchoradmin/hipaa-workflow-design: HIPAA constraints for Health Cloud onboarding contexts