AppSuite:Client Onboarding

2021-05-05T10:54:21Z

Daniel.dickhaus:

<div class="title">Client Onboarding</div>

{{VersionFrom|7.8.1}}

With version 7.10.5 we introduced a new wizard.
This config is still valid since the old wizard can still be enabled via setting.
See https://documentation.open-xchange.com/7.10.5/ui/configuration/settings-list-of.html#onboarding for details on the new wizard.

__TOC__

= Configuration guide for Open-Xchange Client Onboarding =

With Open-Xchange Server v7.8.1 a new module is added allowing users to integrate several different clients and devices with Open-Xchange; such as providing a link to a commercial App Store to install certain apps on mobile devices.

By default, Open-Xchange ships with several built-in providers; thereof

* CalDAV
* CardDAV
* OX Mail App
* OX Drive App
* Connector for Microsoft Outlook®
* Sync App for Android
* Microsoft ActiveSync
* Mail (IMAP/SMTP)
* Generic Mobile App provider

Those providers allow accessing and/or synchronizing with certain data held by Open-Xchange on a supported device.

== Installation ==

To install the Client Onboarding module, the package open-xchange-client-onboarding needs to be installed.

Moreover the property <code>"com.openexchange.client.onboarding.enabled"</code>; in installed file <code>/opt/open-xchange/etc/client-onboarding.properties</code> needs to be set to <code>"true"</code> (default). So getting rid off the entire client on-boarding module simply requires setting the mentioned property to <code>"false"</code> (and executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool).

== Onboarding scenarios ==

The way to specify what and how a certain device is able to get “on-boarded” is mainly determined by so called scenarios. A scenario describes what gets deployed using which providers that contribute their onboarding possibilities and how it is made accessible to the client’s device.

A scenario consists of the following configuration attributes/options

* A unique scenario identifier
* A flag determining if scenario is enabled or not. If set to 'false' the scenario will not be available, useful for testing/enabling the scenario later on
* A scenario type, which is one of "plist", "manual", or "link"
** "plist" for generating a PLIST configuration file for iOS and OSX devices,
** "manual" for a description for the user for a manual set-up/configuration
** "link" for a link/URL to either Apple App Store / Google Play Store or to downloadable executable
* The "link" attribute, which is only considered it type is set to "link". That attribute consists of the sub-attributes "url" and "type".
** "url" provides the actual link/URL to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. For specifying a property that provides the actual link, please use special "property" scheme; e.g. "property://com.openexchange.client.onboarding.app.mylink"
** "type" indicates if "url" holds a link for either Apple App Store, Apple Mac Store or Google Play Store. Must only be specified in case "url" points either of those commercial stores. Supported values are "appstore", "macstore" and "playstore"
* The identifiers for the providers, which contribute to the scenario; 
please check command-line tool <code>/opt/open-xchange/sbin/listonboardingproviders</code> to check, which ones are available
* The identifiers for alternative scenarios. This is typically used to provide alternative manual setup possibility.
* The comma-separated names of Font Awesome icons that are supposed to be displayed for the scenario 
(only the ones from v4.4.0 are currently supported)
* The translatable display name; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts
* The translatable description; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts

== Onboarding providers ==

As described in the previous section, a scenario specifies what providers contribute to it. A provider represents a certain App or (synchronization) protocol that a device can install, download and/or communicate with.

Moreover a provider specifies what Onboarding types are supported ("plist", "manual", and/or "link"). Hence, once a provider is chosen to contribute to a certain scenario, the supported on-boarding type needs to match the one of the scenario itself. E.g. a scenario, which indicates to be of type "link", will always fail if the associated provider signals to support types "plist" and "manual".

To check what providers are available on your system, please execute the <code>/opt/open-xchange/sbin/listonboardingproviders</code> command-line tool, which outputs something like:

[[File:onboarding_1.png]]

Each provider might require one or more capabilities/permissions to be available for the requesting user. If capabilities/permissions are not satisfied, the associated scenario cannot be applied, but will be displayed to the user for upsell opportunities.

=== Generic Onboarding provider for Apps ===

Identifier: <code>app</code>

The generic onboarding provider for apps allows specifying custom scenarios of type "link" for arbitrary links/URLs pointing to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. The link can be set directly or via a property.

This provider requires no capability/permission.

An exemplary section in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file might look like (check "Configuring Onboarding scenarios" chapter for more details):

[[File:onboarding_2.png]]

=== CalDAV/CardDAV ===

Identifiers: <code>caldav</code> & <code>carddav</code>

In order for a scenario (having CalDAV/CardDAV in its provider listing) to be executable by a user, the "caldav" capability and "carddav" capability respectively are required.

Moreover, the appropriate *DAV end-points are supposed to be configured through property <code>com.openexchange.client.onboarding.caldav.url</code> in <code>client-onboarding-caldav.properties</code> file and property <code>com.openexchange.client.onboarding.carddav.url</code> in <code>client-onboarding-carddav.properties</code> file.

=== Drive/Mail Apps ===

Identifiers: <code>driveapp</code> & <code>mailapp</code>

Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the "drive" capability and the Mail App requires the "mobile_mail_app" one.

The appropriate links to the apps in the corresponding stores are configured in associated .properties files:

* <code>client-onboarding-driveapp.properties</code>
* <code>client-onboarding-mailapp.properties</code>

By default the links to the official apps are set, but may be changed to ones for branded versions.

=== Drive Windows Client ===

Identifier: <code>drivewindowsclient</code>

The provider for the windows Drive Client. Requires the "drive" capability, but has no configuration options. However, this provider requires the "open-xchange-drive-client-windows" and the orderly configured binaries (e.g. through installing appropriate package according to the brand).

Please check [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive#OX_Drive_for_Windows ''this''] documentation for more details.

=== Sync App ===

Identifier: <code>syncapp</code>

The provider for the Sync App for Android. Requires "caldav" and "carddav" capabilities.

The link to Google Play Store is specified via property <code>com.openexchange.client.onboarding.syncapp.store.google.playstore</code> in <code>client-onboarding-syncapp.properties</code> file. -->

=== Mail (IMAP/SMTP) ===

Identifier: <code>mail</code>

The provider for deploying the IMAP/STMP account on target device using native/stock mail app. All IMAP/SMTP related settings are settable in file 'client-onboarding-mail.properties'.

=== Microsoft ActiveSync (EAS) ===

Identifier: <code>eas</code>

Configures the ActiveSync account on target device. Allows specifying the EAS end-point through <code>com.openexchange.client.onboarding.eas.url</code> property in 'client-onboarding-eas.properties'.

== Configuring Onboarding scenarios ==

Onboarding scenarios are configured through the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Each scenario starts with its own "section" in that YAML file by typing its unique identifier. All further attributes as outlined in chapter "Onboarding scenarios" are nested below that identifier.

=== Easily enabling/disabling scenarios ===

By default, Open-Xchange ships with a set of pre-defined scenarios that might apply to the most common installations. Each scenario can easily be enabled/disabled through its "enabled" Boolean attribute in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool applies the changes without the need for restart.

=== Translatable strings ===

Those attributes ending with "_t10e" refer to localizable strings and are placed into "client-onboarding-scenarios.pot" file. Once such attributes ending with "_t10e" are changed/customized and/or added, the appropriate "client-onboarding-scenarios.pot" file needs to be re-created in order to get translated. For generating that "client-onboarding-scenarios.pot" file, please execute the /opt/open-xchange/sbin/parsei18nyaml command-line tool. That .pot file needs then be turned to the .po files for the individual languages.

Thus changing any of the attributes ending with "_t10e" requires (provided that appropriate .po files are available in <code>/opt/open-xchange/i18n</code> directory) either a restart or executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool together with stop/start of the "com.openexchange.i18n" bundle.

=== Scenarios' scope and order ===

While the previously mentioned "enabled" attribute offers some kind of generic on/off switch, the properties outlined in this section allow defining the device-scope for a scenario and in which order/precedence they are offered to the client. Scope in terms of

* For what devices (from the set of those specified by providers) are what scenarios in which order available and
* For which users they are available

As explained above, each scenario specifies one or more type-compatible providers associated with it. In turn, each provider determines to which devices the scenario applies. In order to further control, which device and which users are allowed to access a certain scenario, there are appropriate options available in file <code>/opt/open-xchange/etc/client-onboarding.properties</code>. Every option is fully [http://oxpedia.org/wiki/index.php?title=ConfigCascade ''config-cascade''] aware and therefore can be controlled on a global, per context set, per context and per user basis.

Thus, to make a scenario available for certain devices (as dictated by scenario’s providers) and for users as well, the scenario identifier needs to be added to the appropriate properties ending with ".scenarios" (for devices) and added to the "com.openexchange.client.onboarding.enabledScenarios" property (for user) as well.

The following properties accept a comma-separated list of scenario identifiers. The order of listed scenarios reflects the order in which they are offered to the client

<blockquote>
com.openexchange.client.onboarding.apple.mac.scenarios 
com.openexchange.client.onboarding.apple.ipad.scenarios 
com.openexchange.client.onboarding.apple.iphone.scenarios 
com.openexchange.client.onboarding.android.tablet.scenarios 
com.openexchange.client.onboarding.android.phone.scenarios 
com.openexchange.client.onboarding.windows.desktop.scenarios

com.openexchange.client.onboarding.enabledScenarios
</blockquote>

Example:
<blockquote>
com.openexchange.client.onboarding.apple.iphone.scenarios=mailappinstall, driveappinstall, eassync, mailsync, davsync
</blockquote>

This exemplary setting specifies that Mail App, Drive App, EAS, Native Mail (IMAP/SMTP) and CalDAV/CardDAV are available in given order for iPhone devices.

Once a scenario is made accessible through configuration it is visible to users trying to perform a client onboarding using one of associated devices. However, whether a user is effectively allowed to execute that scenario is determined by the required capabilities of the denoted providers; if not allowed it gets displayed as an upsell opportunity.

=== Configuring actions ===

The type for a scenario determines what actions are associated with it to "''transport''" the onboarding information to the client. The types "manual" and "link" only show static information like displaying a link. In contrast the type "plist" allows several actions to transport the configuration profile onto the client. Thereof

* E-Mail
* SMS

In order to utilize the "E-Mail" action, a special transport must be configured for system-composed E-Mails [http://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode#Share_Notifications ''as it is for using the sharing functionality'']. This transport is configured in noreply.properties. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.

Using the SMS action requires an according implementation being available. OX App Suite comes with an optional sipgate implementation. Please check [http://oxpedia.org/wiki/index.php?title=AppSuite:SMS_Sipgate ''this documentation''] how to setup App Suite accordingly.

==== Implementing your own SMS gateway ====

To use an SMS gateway other than sipgate, you can provide your own implementation. Therefore the Java interface <code>com.openexchange.sms.SMSServiceSPI</code> needs to be implemented and published as an OSGi service. For parsing phone numbers provided by users <code>com.openexchange.sms.PhoneNumberParserService</code> can be used. That one is also available as an OSGi service and can be tracked accordingly. You can have a look at bundle <code>com.openexchange.sms.sipgate</code> as implementation reference.

'''Important:''' You must not install the <code>open-xchange-sms-sipgate</code> package if you provide your own implementation.

==== PLIST-signing ====
Scenarios of type "plist" require having PLIST-signing enabled. Otherwise the device will show a warning when importing a received PLIST configuration profile. Please follow the instructions as outlined in [http://oxpedia.org/wiki/index.php?title=AppSuite:PList_signing ''this article''] how to enable and configure signing for PLIST files.

== Adding custom scenarios ==

The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.

<blockquote>
mygoogleapp: 
  enabled: true 
  type: link 
  link: 
    url: http://play.google.com/store/apps?id=mygoogleapp.invalid 
    type: playstore 
    image: http://my.fine.host/image001.png 
  providers: [app] 
  alternatives: [] 
  icon: fa-cloud 
  displayName_t10e: "My App for synchronizing files" 
  description_t10e: "Synchronize your files with our Drive application."
</blockquote>

The next step is to make that scenario accessible through adapting 'client-onboarding.properties' file. Hence, the scenario identifier needs to be added to the devices, to which it applies (Android devices in this case):

<blockquote>
com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp 
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp
</blockquote>
Furthermore, that scenario needs to be made accessible to users as well:

<blockquote>
com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp
</blockquote>
At last, a .pot file is supposed to be generated from the translatable strings using /opt/open-xchange/sbin/parsei18nyaml command-line tool to yield the .po files for the individual languages.

Provided that target users do hold appropriate capabilities, they are allowed to execute that scenario. In the example above the "app" provider is specified, which does no require any capabilities. Hence, that scenario is available.

== HowTos ==

=== How can I quickly setup a default/test configuration ? ===

# Install open-xchange-client-onboarding package
# Edit <code>/opt/open-xchange/etc/client-onboarding.properties</code> and set <code>com.openexchange.client.onboarding.enabled</code> to <code>true</code>
# Edit <code>noreply.properties</code> to enable autoconfig sending via email. PS: Have a fully working smtp login available like “noreply@yourdomain.tld”
# Edit client-onboarding-scenarios.yml and set “enable” for : “driveappinstall” , “davsync” “davmanual” “mailsync” “mailmanual” to <code>true</code>
# Now set the correct caldav/carddav server FQDNs in the corresponding files for your setup
#*<code>client-onboarding-caldav.properties</code>
#*<code>client-onboarding-carddav.properties</code>
# Restart OX process
# Login to AppSuite. Click on Settings - Connect your device
# Verify that you have following onboarding options available:
#* windows -> imap/smtp details
#* android/fon+tablet -> imap/smtp details
#* android/fon+tablet -> drive app
#* apple -> iphone -> imap/smtp config button
#* apple -> iphone -> imap/smtp details for experts
#* apple -> iphone -> calendar/addressbok -> config button
#* apple -> iphone -> calendar/addressbok -> details for dav setup
#* apple -> iphone -> drive app
#* apple -> ipad -> imap/smtp config send email
#* apple -> ipad -> imap/smtp config button
#* apple -> ipad -> imap/smtp details for experts
#* apple -> ipad -> calendar/addressbook config send email
#* apple -> ipad -> calendar/addressbook config button
#* apple -> ipad -> calendar/addressbook details for experts
#* apple -> ipad -> drive app

=== How can I quickly disable a certain scenario ===

Simply enter the 'client-onboarding-scenarios.yml' file and go to the section specifying the target scenario. Switch the 'enabled' flag to "false" and execute /opt/open-xchange/sbin/reloadconfiguration command-line tool.

E.g. to disable the OX Drive App:

[[File:onboarding_3.png]]

=== How can I disable the outdated ui parts like 'Downloads'? ===

The wizard replaces and extends the functionality of the old Download Section in settings and the corresponding widgets. We recommend to disable these outdated parts:
# widget: get ox drive
# widget: update
# settings entry: downloads

'''Remove settings section 'Downloads' '''

Edit ''/opt/open-xchange/etc/settings/appsuite.properties'' and add or change the value to true:
* ''io.ox/core//settings/downloadsDisabled''

'''Remove widgets'''

To remove the both related portal widget/tiles please refer to the
[[AppSuite:Configuring_portal_plugins#Disabling_a_tile_completely | portal plugins wiki page ]]

* ''io.ox/portal/widget/oxdriveclients''
* ''io.ox/portal/widget/updater''

=== How can I add my own App? ===

Provided that the App is accessible by a link (pointing to a commercial App Store or to a downloadable executable/installer), the generic "app" is the suitable provider to choose.

Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and "provider" attribute set to "[app]":

<blockquote>
mygoogleapp: 
  enabled: true 
  type: link 
  link: 
    url: http://play.google.com/store/apps?id=mygoogleapp.invalid 
    type: playstore 
    image: http://my.fine.host/image001.png 
  providers: [app] 
  alternatives: [] 
  icon: fa-cloud 
  displayName_t10e: "My App for synchronizing files" 
  description_t10e: "Synchronize your files with our Drive application."
</blockquote>
The attribute "type" needs to be set to "link".

The attribute "link" should be configured with:

* "url" sub-attribute containing the actual link pointing to the URL location
* "type" sub-attribute specifying of what type that link is: either "appstore", "macappstore", "playstore" or "common". The type "common" is supposed to be used for links that do not point to a commercial App Store, but to a downloadable executable/installer file.
* "image" sub-attribute containing the link pointing to the App's image. Supported with v7.8.4

The "icon" attribute is supposed to contain a comma-separated list of Font Awesome icons (only the ones from v4.4.0 are currently supported) that represent the App; e.g.

* "fa-cloud" for Drive/file-related nature
* "fa-calendar, fa-users" for Calendar and Address Book synchronization
* "fa-envelope-o" for Mail nature

Next, the translatable display name and description should be set through setting the attributes "displayName_t10e" and "description_t10e". As described previously, executing the /opt/open-xchange/sbin/parsei18nyaml command-line tool yields an appropriate .pot file, which can then be used for generating the individual .po file for the different translations.

Finally, the 'client-onboarding.properties' file needs to be modified to specify the "scope" for that new scenario. Add the scenario’s unique name to the appropriate device properties and add it to "com.openexchange.client.onboarding.enabledScenarios" property as well.

After executing /opt/open-xchange/sbin/reloadconfiguration command-line tool the new client onboarding scenario is available for the selected users/devices.

=== How can I upsell my own app? ===

Having the same prerequisites/steps as for "How can I add my own App?" the scenario description in the 'client-onboarding-scenarios.yml' file simply needs to be extended by the desired capabilities, which are supposed to be used for managing the upsell.

Example

<blockquote>
mygoogleapp: 
  enabled: true 
  type: link 
  link: 
    url: http://play.google.com/store/apps?id=mygoogleapp.invalid 
    type: playstore 
  '''capabilities: "mygoogleapp_capability"''' 
  providers: [app] 
  alternatives: [] 
  icon: fa-cloud 
  displayName_t10e: "My App for synchronizing files" 
  description_t10e: "Synchronize your files with our Drive application."
</blockquote>
The special "capabilities" attribute is only supported for scenarios of type "link" with the special "app" provider.

With such a "capabilities" attribute only users, which have the "mygoogleapp_capability" capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.

<blockquote>[[File:onboarding_4.png]]
</blockquote>

Open-Xchange - User contributions [en]

AppSuite:Client Onboarding