--- url: /software_partners/build/onboarding_sessions/lifecycle.md --- # Lifecycle of an onboarding session Unlike [other entities](/software_partners/start/entities/index.html) in the SuperAPI system, onboarding sessions follow a very defined lifecycle of events as they are designed to be created when we need an employee to take a discrete set of actions in the SuperAPI system vs say setting up some configuration as you might do with an employer. As such, we provide some additional webhooks which allow you to take actions in your system based on how the user is progressing through the onboarding session. It's worth noting that an onboarding session is conceptually the same as a state machine (or rather a state chart as we nest state machines). Thinking about them like this may help with understanding how to model them in your system. A diagram can speak for a thousand words: ```mermaid stateDiagram-v2 classDef movement font-style:italic initial --> custom_steps note right of initial All workflows will start here then move to the first custom_step as defined by your workflow slug end note state custom_steps { phone_verification --> tfn_declaration tfn_declaration --> bank_accounts bank_accounts --> disclaimers disclaimers --> super_selection } custom_steps --> abandoned: Moved after two weeks of inactivity custom_steps --> cancelled: You cancel the session via the API custom_steps --> post_onboarding: User completed onboarding post_onboarding --> pending_completion pending_completion --> completed note right of pending_completion We wait in this state for all actions in the custom steps to be completed, e.g. waiting for super registration to complete end note note right of custom_steps Defined by which workflow slug is used when creating the onboarding session end note note right of completed Here we emit a event notifying you that the onboarding session has completed. end note abandoned --> pending_completion note left of abandoned Actions taken here are dependent on what steps are in your custom_steps. E.g. if super selection is used, here we will staple the user then default them. After abandonment actions have been triggered, it then moves to wait for the results. end note class custom_steps movement ``` One of the benefits of using SuperAPI is that we have abstracted away from you most of the logic that surrounds handling some of the more complex actions that need to be taken, e.g. MRR registration. ## Events that move the onboarding session workflow automatically Workflow states can be moved by events outside of the user's control. These are: | Event | Effect | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Abandoned | Fired after two weeks if the onboarding session has not been completed. Will trigger abandonment behavior then wait for the results. This for example will be to start the stapling and defaulting behavior | | Cancelled | You cancelled the session with `DELETE /api/v1/onboarding-session/:id`. Only possible while no response from a super fund is pending. No abandonment behaviour runs | ## Outcomes Each module in the workflow will record an `outcome` key which details the 'outcome' of the user interacting with that module. Outcomes for most modules usually fall into either a 'complete' or 'incomplete'. Take for example the bank accounts module, if the employee enters their bank account details and clicks next then the outcome of the bank account module will be that it was 'complete'. One special exception to the complete / incomplete outcome is the `onboarding_session_super_selection` module as this has more possible end states. These outcomes are recorded in the following table along with some possible actions you may want to take in your system: | Outcome | Reason | Possible actions | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | complete | The user completed all steps required to provide details for payment to their nominated super fund. | Submit the employee's details to payroll | | complete\_without\_member\_number | The user did not complete the form, we were unable to find their stapled superfund and we did not receive a response from sending a request (MRR) to join them to the employers default super fund. | Notify the employer to either collect superfund details directly from the employee, staple the employee or join the employee to their default fund. This is an uncommon outcome where the employer will have to manually resolve the issue. | | incomplete | You requested details via the API about an onboarding session where the user is in the process of selecting a superfund. | Wait for the user to complete their onboarding | ## Super selection and abandonment Unlike most onboarding modules, the super selection module has special abandonment behavior designed to ensure we capture member numbers for superannuation payments even when employees don't complete the process. When abandoned, the system follows this decision flow: ```mermaid flowchart TD A[Start: Super selection abandoned] --> B{Has an existing super fund been provided?} B -- Yes --> C[Return existing super fund details] B -- No --> D{Has employer set up ATO connection?} D -- No --> E[Return: Could not find a member number] D -- Yes --> F{Use stapling API to look up fund} F -- Found --> G[Return stapled fund details] F -- Not found --> H[Trigger MRR to default fund] H --> I{Did MRR return a response?} I -- Response found --> J[Return default fund details] I -- No response --> K[Return: Could not find a member number] ```