Onboarding - automatic mode

Automatic 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.

Note: The reset() method clears all step-related information, but does not clear context information.

Advanced

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. The CompositeStep can be used with default subflows which can be found in the SAPcpmsDefaultSteps. Other use-cases are not supported currently out of the box by the SDK, but can be implemented by developers.

OnboardingContext

The 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 OnboardingContext.

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.

  • This structure contains the parameters for an OnboardingStep in case the automatic flow management mode is used for Onboarding

    See more

    Declaration

    Swift

    public struct OnboardingContext
  • 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.
    See more

    Declaration

    Swift

    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 the state property of the FlowPresentationDelegate according to the current flow, and sets it back to general at the end of the flow.

    See more

    Declaration

    Swift

    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.
    See more

    Declaration

    Swift

    public enum OnboardingResult
  • Represents the presentation state. Onboarding steps must specify the state on their FlowPresentationDelegateClient.

    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
    See more

    Declaration

    Swift

    public enum PresentationState : Int