Onboarding - automatic mode
flow is always a one-way iteration of the steps which stops at the first failure. Write steps to effectively handle errors:
Write a step in a way that, if it can handle the error, it:
- Continues the task in a different manner
- Repeats the action.
Write a step so that any error within the step is solved internally, and the complete step does not fail. For example:
- When a configuration step fails to get information from one source, it uses another source.
- When an authentication step prompts the user for credentials and fails to authenticate, it again prompts the user for credentials.
If a step reports a failure then the current onboarding/restoring flow stops. For example:
- When onboarding flow stops, call
reset()in every step. If the onboarding flow restarts, create a new context to start with a clean status.
- When restoring flow stops, the developer must decide what the application will do.
reset() method clears all step-related information, but does not clear context information.
More complicated scenarios can be implemented as a single “composite” step (multiple steps wrapped into one). This could wrap other existing steps, the logic which step should be used, and controls their run. The composite step behaves as a normal step in the onboarding flow. The main use-cases for composite steps can be:
- Choose from multiple steps but run only one. For example, decide on authentication methods to use (SAML or OAuth):
- Based on some configuration parameter
- Detected automatically by a request/response to the server
- Implement a “best-effort” flow where if a step fails, it triggers another step to run and the first non-failing step completes the compound step.
- Run all the steps as a subflow
The SDK from version 2.2 supports the case when all the assigned steps are run as a subflow. It is called
CompositeStep can be used with default subflows which can be found in the
Other use-cases are not supported currently out of the box by the SDK, but can be implemented by developers.
OnboardingContext, which is a fixed structure, is used by the steps to communicate with each other and to receive and publish all required data.
The application developer can provide, preconfigure, and change the content of the
OnboardingContext fields. The step defines the data that it requires, and the app developer must ensure it is available when needed.
All fields are initialized with default values when the context is created. For more details see
Automatic mode of Steps
Every step must declare the
OnboardingInfoKey, which allows the step to search for required data at a later time. This key (
OnboardingInfoKey) is located in the
info field of the
OnboadingContext. Configuration steps that use transformers are the typical feeders of this data.
Context as a result
At the end of the onboard or restore flow, the
OnboardingContext contains all relevant data for the application developer, including:
- OnboardingId : Must be persisted (UserDefaults, Keychain) after successful onboarding and must be used for restoring.
- SAPURLSession : The networking component which should be passed to all other components using networking e.g. SAPOData.
- CredentialStore : Composite store that contains credential or other sensitive data. If the application needs a secure storage for large data set like images or OData objects, a secure key must be generated separately and only the key should be stored.
Important: It is highly recommended that you save the values to variables.
Set of error that could occur during onboarding.
- shouldUseAlternateOperation: an alternate operation should be started which isn’t a real error but the flow has to stop. For example Demo mode on Welcome
- authenticationFailed: The authentication / validation request failed. The configured SAPURLSession is not able to communicate with the backend.
- missingArgument: Missing argument.
- invalidArgument: Invalid argument.
public enum OnboardingError : Error
Runs an onboarding / restoring flow by calling the steps asynchronously one by one in order they stored in the array. Stops the iteration if a step fails. Changes theSee more
stateproperty of the
FlowPresentationDelegateaccording to the current flow, and sets it back to
generalat the end of the flow.
public class OnboardingFlowController
OnboardingResult specifies the result of an operation related to Onboarding.
- success: The operation successfully finished. The context in the parameter can contain modified information.
- failed: The operation failed. The parameter contains the reason of the failure.
public enum OnboardingResult
Represents the presentation state. Onboarding steps must specify the state on their
The presenters use this information to decide if they can show an info screen before the presentation.
- general: during application run
- onboarding: during onboarding flow
- restoring: during restoring flow
public enum PresentationState : Int