Welcome Screen Step

WelcomeScreenStep gets the configuration data required for authentication and registration on the server. This is the second step of the onboarding scenario.

This step is not used for the restore and reset scenarios.

(The iOS equivalent is WelcomeScreenStep.swift - onboard method.)

Input Parameters

Mandatory input parameters:

• Application identifier – Provided on the step itself.

• Application version – For example, "1.0". This setting has to be provided on the step itself.

• flowPresentationActionHandler – Specifies the Action Handler for Flow Presentation. If the user does not want to specify it's functionality, the default implementation can be used instead. (This setting has to be provided on the initial FlowContext.)

• Context – Specifies the android context initiating the flow such as the caller Activity. This setting has to be provided on the initial FlowContext.

Optional input parameters:

• Device identifier – Provided on the step itself.

• welcomeScreenSettings – Specifies the settings for the Welcome Screen. If there are no specified values passed for the view objects of the screen, the default string values are set. Please note that there is no need to set the action handler because the flows implementation sets a default action handler if one is not set. (This is provided on the step itself.) In addition the onboarding type cannot be specified directly, because the flows implementation integrates the foundation library's configuration loader with the screens and therefore the onboarding type is determined indirectly by the provider list setting of the configuration loader. Therefore the flows implementation always uses the STANDARD onboarding for the welcome screen and dynamically sets at runtime the appropriate type for the activation screen according to the configuration loader's callback behavior which is controlled by the provider list setting.

• activationSettings – Specifies the settings for the Activation Screen. If there are no specified values passed for the view objects of the screen, the default string values are set. Please note that there is no need to set the action handler because the flows implementation sets a default action handler if one is not set. (This is provided on the step itself.)

• qrCodeReaderSettings – Specifies the settings for the QR Code Reader Screen. If there are no specified values passed for the view objects of the screen, the default string values are set.

• qrCodeConfirmSettings – Specifies the settings for the QR Code Confirm Screen. If there are no specified values passed for the view objects of the screen, the default string values are set.

• Providers – Specifies the configuration providers used by the foundation layer's configuration loader. If this is not specified, then the default providers of the configuration loader are used. The default provider list sets the OnboardingType.BARCODE_OR_DISCOVERY_SERVICE_ONBOARDING if there was no configuration file found by the FileConfigurationProvider and ManagedConfigurationProvider, otherwise the default STANDARD_ONBOARDING will be executed. OnboardingType.DISCOVERY_SERVICE_ONBOARDING can be forced by using only the DiscoveryServiceConfigurationProvider.OnboardingType.BARCODE_ONBOARDING can be forced by using only the JsonConfigurationProvider. ACTIVATION_MAIL_ONBOARDING is not supported by the flows. (This is provided on the step itself.)

• OAuth configuration – Specifies the OAuth configuration in case of OAuth-based authorization used by OAuthStep.

Output Parameters

• onboardingParameters – This step initializes the onboardingParameters on the flowContext. The onboardingParameters encapsulates the foundation layer's SettingsParameters object consisting of BackendURL, Application identifier, Application version, Device identifier, and optionally the OAuth configuration.

The output of the step can be accessed using the getOnboardingParameters method of the OnboardingContext.

Using WelcomeScreenStep

1. Set the Context and the Flow Presentation Action Handler in the flowContext.

     flowContext.setContext(callerActivity);
     flowContext.setFlowPresentationActionHandler(new FlowPresentationActionHandlerImpl(callerActivity));
   

2. Initiate the step setting the application id and version and optionally the welcomeScreenSettings, activationSettings, qrCodeReaderSettings, and qrCodeConfirmSettings:

     WelcomeScreenStep welcomeScreenStep = new WelcomeScreenStep();
     welcomeScreenStep.setApplicationId("com.sap.test.odata");
     welcomeScreenStep.setApplicationVersion("1.0");
     LaunchScreenSettings welcomeScreenSettings = new LaunchScreenSettings();
     welcomeScreenSettings.setDemoAvailable(false);
     welcomeScreenStep.setWelcomeScreenSettings(welcomeScreenSettigs);
     ActivationSettings activationSettings = new ActivationSettings();
     welcomeScreenStep.setActivationScreenSettings(activationSettigs);
     QRCodeReaderSettings qrCodeReaderSettings = new QRCodeReaderSettings();
     welcomeScreenStep.setQrCodeReaderSettings(qrCodeReaderSettings);
     QRCodeConfirmSettings qrCodeConfirmSettings = new QRCodeConfirmSettings();
     welcomeScreenStep.setQrCodeConfirmSettings(qrCodeConfirmSettings);
   

3. Specify the execute method's FlowActionHandler parameter's "onFailure" and "onSuccess" behavior:

    flowManagerService.execute(flow, flowContext, new FlowActionHandler() {
           @Override
           public void onFailure(Throwable t) {
               //error handling: set the status, update the caller activity
           }
   
           @Override
           public void onSuccess(FlowContext result) {
               //set the status, update the caller activity
               //read the result
           }
       });
   

Behavior of WelcomeScreenStep

The step displays the UI layer's LaunchScreenActivity first. All the customizing options of the UI layer are also available for the step through the same LaunchScreenSettings object.

When the end user taps on the Get started button of the launch screen, the WelcomeScreenStep initializes the ConfigurationLoader of the foundation layer and tries to load the configuration data. If the configuration data is available in a file and the loader could access it, then the output parameters of the step are filled out on the flowContext and the step terminates successfully.

If the loader cannot access the configuration data and there is discovery service provider on the provider list of the configuration loader, then the UI layer's ActivationActivity are displayed on top of the LaunchScreenActivity. On the ActivationActivity, the end user is able to set the email/onboarding code or use the QR-code for the access of the discovery service.

If the email/onboarding code or the QR-code was provided properly then the configuration loader accesses the configuration data from the discovery service, the step terminates successfully, and the output parameter of the step is filled out with the downloaded configuration data.

Please note that this step does not persist the configuration data. This functionality was extracted into a new WelcomeScreenStoreStep. This change makes it possible to persist this information only after the creation of the secure store. The store created that way already fulfills the server-side criteria (passcode policy) which is important from a security point-of-view.

---

Last update: November 24, 2020