1. Step

The tasks necessary to achieve the onboarded state of the application are encapsulated in different classes called steps. Each step has a well defined task.
The series of steps taken together is called the flow.

SAPFioriFlows includes several steps, each with different functionality. Steps can be grouped based on their functionality:

Configuration steps: Gather configuration/settings which are used later by other steps or the application itself:

Use the flat dictionary with given keys (OnboardingInfoKey) also referred to as info, to pass data between steps.

If a step gathers any data that might be needed in the future, for example in case of a restart, it should be persisted physically in the store by the step itself. The step that requires this data can then load it when needed.

2. Flow

There are two types of flows based on the state of the application:

onboarding flow – The application starts from an initial state (the first run or after a reset)

restoring flow – The application starts, but a persisted state already exists

A flow can contain any number of steps appropriate for the application. The steps used in a flow can be in any order that makes sense for the application, and is not controlled by the SDK. It is up to the application developer to configure and set up the flows properly. Each step has its own set of arguments which are needed to perform its task.

A general onboarding flow consist of:

the WelcomeScreenStep which also gathers configuration and stores it in the store

an authentication step which configures the SAPURLSession with the appropriate observer and authenticator, performs the authentication

the SAPcpmsSettingsDownloadStep which gathers the settings (for example PasswordPolicy) from the SAPcpms

StoreManagerStep which creates the store

A general restoring flow contains the same steps but starts with the StoreManagerStep which opens the existing SecureStore:

StoreManagerStep: opens the SecureStore

WelcomeScreenStep reloads the configuration from the store

an authentication step

the SAPcpmsSettingsDownloadStep which gather the settings, for example PasswordPolicy

3. Modes of running the flow

You can implement your own steps, or implement steps included in the SAPFioriFlows framework.

There are two ways to use the steps provided by the framework:

Automatic mode (recommended): a convenience way to run an onboarding flow. Use the OnboardingFlowController and OnboardingContext so that the flow and data transfer of steps is managed automatically in a convenient and simple-to-implement way. In this case the step must implement the OnboardingStep protocol. For more information please refer to the Automatic flow management
Other classes to support this mode:

Manual mode: Use the steps and manage the data transfer and flowmanually. As a naming convention, all steps should declare the onboard,restore,reset methods (similarly to OnboardingStep), with the list of parameters that the step needs for its operation to complete successfully.

Usually the steps are implemented a way where the automatic methods call the manual method internally so the methods behavior is guaranteed to be the same.

See OAuth2AuthenticationStep for an example. It declares a low-level onboard method and a higher-level onboard method (which conforms to OnboardingStep protocol supporting automatic flow management):

4. Presenting screens

The application can present a splash screen when the onboarding flow starts. This screen hides the application screen between the steps and also provides a consistent background for the onboarding flow. There are more splash screen use-cases. In every case, the developer must handle when to present the screen before the onboarding flow starts and dismiss the screen when the flow finishes.

There is no splash screen set to PresentationDelegate
The application screen is observable for a moment every time it moves between onboarding steps. If the app presents its splash screen before the onboarding flow starts, it will be visible. That screen can be replaced by the appropriate application screen at the end of the onboarding flow.

The application starts with InfoViewController as a root view controller: this can be set as a splash screen to the ModalUIViewControllerPresenter (when it is used as PresentationDelegate - default) and will be visible instead of application screen when moving between steps. The information text on the screen will be updated by the steps automatically. The developer has to replace it to the application view controllers at the end of the onboarding flow:

// instantiate the splashScreen, set it to `presentationDelegate` then start the flowletsplashScreen=FUIInfoViewController.createSplashScreenInstanceFromStoryboard()<#SetitastherootViewController#>// set as splash for onboardingpresentationDelegate.setSplashScreen(splashScreen)<#runtheonboardingorrestoringflow#>// when the onboarding flow was successful, clear the splash screen(context.presentationDelegateas!ModalUIViewControllerPresenter).presentationDelegate.clearSplashScreen()

You can use any custom ViewController as a splash screen if it conforms to the InfoTextSettable protocol, which can be implemented as an extension to any existing ViewController.

When starting the application, the main application screen is visible, then a splash screen must be opened over the application screen using the present method of the FlowPresentationDelegate. This splash screen is visible when switching between steps. The information text on the screen will be updated by the steps automatically. You must add code to close the screen by calling dismiss on the PresentationDelegate after the onboarding flow finishes:

// instantiate the splashScreen, call present on presentationDelegate, then in callback start the flowletsplashScreen=FUIInfoViewController.createSplashScreenInstanceFromStoryboard()presentationDelegate.present(splashScreen){_in<#runtheonboardingorrestoringflow#>}// when the onboarding flow was successful, call dismiss on presentationDelegatecontext.presentationDelegate.dismiss{_in}

Note: By default, the ModalUIViewControllerPresenter overrides the modalPresentationStyle property of the presented view controllers to .overFullScreen. This makes possible to correctly present view controllers on top of everything, including UIAlertController. However when using this presentation style, some of the underlying view controller’s methods (viewWillDisappear, viewWillAppear) won’t be called when they are hidden / showed again. You can change the default presentation style any time on ModalUIViewControllerPresenter.

5. Running the flow: an example

As described in Flow and Modes of running the flow sections, the following sample presents a general way of running an onboarding and restoring flow:

letpresentationDelegate=ModalUIViewControllerPresenter()<#Initialize,presentandsetthesplashscreen#>presentationDelegate.setSplashScreen(<#yoursplashscreeninstance#>)onboardOrRestore()// start the proper flowfunconboardOrRestore(){// declare the steps: you can use different instances as well for the onboarding/restoring flowsletwelcome=WelcomeScreenStep(providers:[<#listyourconfigurationproviders#>])// welcome and configuration managementletsessionConf=SAPcpmsSessionConfigurationStep()// SAPcpms compatibilityletauth=OAuth2AuthenticationStep()// authenticationletsettings=SAPcpmsSettingsDownloadStep()// download and apply the settingsletstore=StoreManagerStep()// store management// initialize contextvarcontext=OnboardingContext(presentationDelegate:presentationDelegate)letonboardingFlow:[OnboardingStep]=[welcome,sessionConf,auth,settings,store]letrestoringFlow:[OnboardingStep]=[store,welcome,sessionConf,auth,settings]ifletsavedUUIDString=UserDefaults.standard.string(forKey:"userOnboardingID"),letuuid=UUID(uuidString:savedUUIDString){context.onboardingID=uuidOnboardingFlowController.restore(on:restoringFlow,context:context){result<#handletheresult,starttheapplicationlogic#>}}else{OnboardingFlowController.onboard(on:onboardingFlow,context:context){result<#handletheresultandpersisttheonboardingIDincaseofsuccess#>UserDefaults.standard.set(context.onboardingID.uuidString,forKey:"userOnboardingID")<#Savetherequiredpropertiesfromthecontexttoyourapp:SAPURLSession,Store,etc.Neversavethewholecontext!#><#starttheapplicationlogic#>}}}

Declaration

This protocol describes a transformation from a specific value to an other object. It is used to transform a configuration to typed objects.
The config source of the transformation can be a Dictionary, an Array or any simple type. Since the config can be transformed to more objects (if it is a Dictionary describing more structures) the result is a dictionary which must contain the transformed typed objects.
The keys in the result dictionary must be declared first to avoid typos and provide a clear declared way of key usage

Declaration

Implementers must present appripriately the ViewControllers provided by the onboarding steps
Different implementers can present the ViewControllers differently but must be appropriate for the ViewController design of the used steps. For example if a step uses a ViewController designed to use NavigationController the presenter must put the ViewController into a NavigationController

Declaration

Class for Welcome Screen onboarding step handling
UI elements of the Welcome Screen are localizable through the step’s welcomeScreenCustomizationHandler
which will be called during the WelcomeStep onboarding process to configure the screen.

Declaration

Onboarding step implementation of Basic Authentication
Used in the onboarding/restoring flow, this step is responsible to configure the app’s URLSession to be able to communicate with basic authentication protected resources.
Creates and registers the BasicAuthenticationObserver to the SAPURLSession, then sends a validation request which will trigger an authentication flow.

Customization

During the onboarding flow, if there is a splash screen which shows a text, that text can be changed/localized.

Declaration

Used in the onboarding / restoring flow, this step is responsible to configure the app’s URLSession to be able to communicate with OAuth 2.0 protected resources.
Creates and registers the OAuth2Observer to the SAPURLSession, then sends a validation request which will trigger an authentication flow.

Customization

During the onboarding flow, if there is a splash screen which shows a text, that text can be changed/localized.
The presented webView will also have localizable components, but the localization of downloaded data depends on the server and is not customizable from the created client application.

Declaration

Used in the onboarding / restoring flow, this step is responsible to configure the app’s URLSession to be able to communicate with SAML 2.0 protected resources.
Creates and registers the SAMLObserver to the SAPURLSession, then sends a validation request which will trigger an authentication flow.

Customization

During the onboarding flow, if there is a splash screen which shows a text, that text can be changed/localized.
The presented webView will also have localizable components, but the localization of downloaded data depends on the server and is not customizable from the created client application.

Declaration

Onboarding step implementation of SLS certificate authentication
Used in the onboarding/restoring flow, this step is responsible to configure the app’s URLSession to be able to communicate with SLS authentication protected resources.
Creates and registers the UserIdentityObserver to the SAPURLSession, then sends a validation request which will trigger an authentication flow.

Customization

During the onboarding flow, if there is a splash screen which shows a text, that text can be changed/localized.

Declaration

Used in the onboarding / restoring flow, this step is responsible to configure the app’s URLSession to be able to communicate with OTP protected resources.
Creates and registers the OTPObserver. This step should be set before the authentication step (can be used with Basic, OAuth 2.0 and SAML 2.0 authentications).

Customization

During the onboarding flow, if there is a splash screen which shows a text, that text can be changed/localized.
The presented webView will also have localizable components, but the localization of downloaded data depends on the server and is not customizable from the created client application.

Declaration

Manages the End User License Agreement (EULA) handling.
The EULA version will be stored in the credentialStore of the OnboardingContext which is used to decide if a new EULA screen should be presented on the next run.
If the user has not confirmed EULA, or a new EULA content is present, a screen will be displayed to request user confirmation.

Usage

lettitle="SAP - EULA"lettext="""
This is a legally binding agreement (Agreement) between Company and SAP SE which provides the terms of your use of the SAP mobile application (Software). By clicking "Accept" or by installing and/or using the Software, you on behalf of the Company are agreeing to all of the terms and conditions stated in this Agreement. If you do not agree to these terms, do not click "Agree", and do not use the Software. You represent and warrant that you have the authority to bind the Company to the terms of this Agreement.
"""letattributes=[NSAttributedStringKey.font:UIFont(name:"Georgia",size:17.0)!]letcontent=NSAttributedString(string:content,attributes:attributes)leteulaContent=EULAContent(title:title,content:content,version:"1.0")leteulaStep=EULAStep(eulaContent:eulaContent)

Declaration

Manages the persistent store in the onboarding flow
Creates and opens a SecureKeyValueStore instance in the folder specified by SecureStoreFolderPath parameter or in applicationSupportDirectory when not specified including the OnboardingID in the file name.
The StoreManagerStep uses multiple screens from SAPFiori, for example TouchID and Passcode screens.
The texts on these screens are also customizable. The localizable UI components are grouped in FUIPasscodeController.
The following example code snippet describes how to change/localize elements of StoreManagerStep