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.