AppSuite:Client Onboarding: Difference between revisions

From Open-Xchange
No edit summary
 
(51 intermediate revisions by 6 users not shown)
Line 2: Line 2:


{{VersionFrom|7.8.1}}
{{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__
__TOC__
Line 18: Line 22:
* Sync App for Android
* Sync App for Android
* Microsoft ActiveSync
* Microsoft ActiveSync
* eM Client
* Mail (IMAP/SMTP)
* Mail (IMAP/SMTP)
* Generic Mobile App provider
* Generic Mobile App provider
Line 59: Line 62:
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".
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 /opt/open-xchange/sbin/listonboardingproviders command-line tool, which outputs something like:
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:media/image1.png]]
[[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.
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.
Line 67: Line 70:
=== Generic Onboarding provider for Apps ===
=== Generic Onboarding provider for Apps ===


Identifier: app
Identifier: <code>app</code>


The generic Onboarding provider for apps allows specifying custom scenarios of type &quot;link&quot; 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.
The generic onboarding provider for apps allows specifying custom scenarios of type &quot;link&quot; 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.
This provider requires no capability/permission.


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


[[File:media/image2.png]]
[[File:onboarding_2.png]]


=== CalDAV/CardDAV ===
=== CalDAV/CardDAV ===


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


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


Moreover, the appropriate *DAV end-points are supposed to be configured through property &quot;com.openexchange.client.onboarding.caldav.url&quot; in 'client-onboarding-caldav.properties' file and property &quot;com.openexchange.client.onboarding.carddav.url&quot; in 'client-onboarding-carddav.properties' file.
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 ===
=== Drive/Mail Apps ===


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


Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the &quot;drive&quot; capability and the Mail App requires the &quot;mobile_mail_app&quot; one.
Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the &quot;drive&quot; capability and the Mail App requires the &quot;mobile_mail_app&quot; one.
Line 93: Line 96:
The appropriate links to the apps in the corresponding stores are configured in associated .properties files:
The appropriate links to the apps in the corresponding stores are configured in associated .properties files:


* client-onboarding-driveapp.properties
* <code>client-onboarding-driveapp.properties</code>
* client-onboarding-mailapp.properties
* <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.
By default the links to the official apps are set, but may be changed to ones for branded versions.
Line 100: Line 103:
=== Drive Windows Client ===
=== Drive Windows Client ===


Identifier: drivewindowsclient
Identifier: <code>drivewindowsclient</code>


The provider for the windows Drive Client. Requires the &quot;drive&quot; capability, but has no configuration options. However, this provider requires the &quot;open-xchange-drive-client-windows&quot; and the orderly configured binaries (e.g. through installing appropriate package according to the brand).
The provider for the windows Drive Client. Requires the &quot;drive&quot; capability, but has no configuration options. However, this provider requires the &quot;open-xchange-drive-client-windows&quot; 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.
Please check [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive#OX_Drive_for_Windows ''this''] documentation for more details.
=== eM Client ===
Identifier: emclient
The provider for the eM Client needs the &quot;emclient&quot; capability.
Allows to configure the URL pointing to the executable file through &quot;com.openexchange.client.onboarding.emclient.url&quot; in file 'client-onboarding-emclient.properties' file.


=== Sync App ===
=== Sync App ===


Identifier: syncapp
Identifier: <code>syncapp</code>


The provider for the Sync App for Android. Requires &quot;caldav&quot; and &quot;carddav&quot; capabilities.
The provider for the Sync App for Android. Requires &quot;caldav&quot; and &quot;carddav&quot; capabilities.


The link to Google Play Store is specified via property &quot;com.openexchange.client.onboarding.syncapp.store.google.playstore&quot; in 'client-onboarding-syncapp.properties' file.
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) ===
=== Mail (IMAP/SMTP) ===


Identifier: mail
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'.
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'.
Line 130: Line 125:
=== Microsoft ActiveSync (EAS) ===
=== Microsoft ActiveSync (EAS) ===


Identifier: eas
Identifier: <code>eas</code>


Configures the ActiveSync account on target device. Allows specifying the EAS end-point through &quot;com.openexchange.client.onboarding.eas.url&quot; property in 'client-onboarding-eas.properties'.
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'.
 
=== OX Updater ===
 
Identifier: oxupdater
 
The provider offering the download for the OX Client Updater ([http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''http:''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''//oxpedia''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''org/wiki/index''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''php''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''?''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''title=AppSuite''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater '':''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''Open-Xchange_Updater'']). The provider is available as soon as the according package is installed and at least one product can be installed/updated via it by the user. A pre-configured scenario 'oxupdaterinstall' is already contained in '/opt/open-xchange/etc/client-onboarding-scenarios.yml'.


== Configuring Onboarding scenarios ==
== Configuring Onboarding scenarios ==


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


=== Easily enabling/disabling scenarios ===
=== 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 &quot;enabled&quot; Boolean attribute in the '/opt/open-xchange/etc/client-onboarding-scenarios.yml' YAML file. Executing /opt/open-xchange/sbin/reloadconfiguration command-line tool applies the changes without the need for restart.
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 &quot;enabled&quot; 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 ===
=== Translatable strings ===
Line 152: Line 141:
Those attributes ending with &quot;_t10e&quot; refer to localizable strings and are placed into &quot;client-onboarding-scenarios.pot&quot; file. Once such attributes ending with &quot;_t10e&quot; are changed/customized and/or added, the appropriate &quot;client-onboarding-scenarios.pot&quot; file needs to be re-created in order to get translated. For generating that &quot;client-onboarding-scenarios.pot&quot; 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.
Those attributes ending with &quot;_t10e&quot; refer to localizable strings and are placed into &quot;client-onboarding-scenarios.pot&quot; file. Once such attributes ending with &quot;_t10e&quot; are changed/customized and/or added, the appropriate &quot;client-onboarding-scenarios.pot&quot; file needs to be re-created in order to get translated. For generating that &quot;client-onboarding-scenarios.pot&quot; 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 &quot;_t10e&quot; requires (provided that appropriate .po files are available in '/opt/open-xchange/i18n' directory) either a restart or executing /opt/open-xchange/sbin/reloadconfiguration command-line tool together with stop/start of the &quot;com.openexchange.i18n&quot; bundle.
Thus changing any of the attributes ending with &quot;_t10e&quot; 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 &quot;com.openexchange.i18n&quot; bundle.


=== Scenario scope ===
=== Scenarios' scope and order ===


While the previously mentioned &quot;enabled&quot; attribute offers some kind of generic on/off switch, the properties outlined in this section allow defining the scope for a scenario. Scope in terms of
While the previously mentioned &quot;enabled&quot; 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) is that scenario available and
* For what devices (from the set of those specified by providers) are what scenarios in which order available and
* For which users is it available
* 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 '/opt/open-xchange/etc/client-onboarding.properties'. 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.
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 &quot;.scenarios&quot; (for devices) and added to the &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property (for user) as well:
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 &quot;.scenarios&quot; (for devices) and added to the &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property (for user) as well.


<blockquote>com.openexchange.client.onboarding.apple.mac.scenarios<br />
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<br />
com.openexchange.client.onboarding.apple.ipad.scenarios<br />
com.openexchange.client.onboarding.apple.ipad.scenarios<br />
com.openexchange.client.onboarding.apple.iphone.scenarios<br />
com.openexchange.client.onboarding.apple.iphone.scenarios<br />
Line 174: Line 166:
com.openexchange.client.onboarding.enabledScenarios
com.openexchange.client.onboarding.enabledScenarios
</blockquote>
</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.
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.


Line 185: Line 185:
In order to utilize the &quot;E-Mail&quot; 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.
In order to utilize the &quot;E-Mail&quot; 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 a SIP Gate being available. Please check [http://oxpedia.org/wiki/index.php?title=AppSuite:SMS_Sipgate ''this documentation''] how to setup a SIP Gate for sending SMS to capable clients.
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.


Moreover, scenarios of type &quot;plist&quot; 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.
==== PLIST-signing ====
Scenarios of type &quot;plist&quot; 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 ==
== Adding custom scenarios ==
Line 193: Line 200:
The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.
The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.


<blockquote>mygoogleapp:<br />
<blockquote>
enabled: true<br />
mygoogleapp:<br />
type: link<br />
&nbsp;&nbsp;enabled: true<br />
link:<br />
&nbsp;&nbsp;type: link<br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
&nbsp;&nbsp;link:<br />
type: playstore<br />
&nbsp;&nbsp;&nbsp;&nbsp;url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
providers: [app]<br />
&nbsp;&nbsp;&nbsp;&nbsp;type: playstore<br />
alternatives: []<br />
&nbsp;&nbsp;&nbsp;&nbsp;image: http://my.fine.host/image001.png<br />
icon: fa-cloud<br />
&nbsp;&nbsp;providers: [app]<br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br />
&nbsp;&nbsp;alternatives: []<br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;
&nbsp;&nbsp;icon: fa-cloud<br />
&nbsp;&nbsp;displayName_t10e: &quot;My App for synchronizing files&quot;<br />
&nbsp;&nbsp;description_t10e: &quot;Synchronize your files with our Drive application.&quot;
</blockquote>
</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):
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<br />
<blockquote>
com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp<br />
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp
</blockquote>
</blockquote>
Furthermore, that scenario needs to be made accessible to users as well:
Furthermore, that scenario needs to be made accessible to users as well:


<blockquote>com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp
<blockquote>
com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp
</blockquote>
</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.
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.
Line 219: Line 231:


== HowTos ==
== 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 ===
=== How can I quickly disable a certain scenario ===
Line 226: Line 266:
E.g. to disable the OX Drive App:
E.g. to disable the OX Drive App:


[[File:media/image3.png]]
[[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? ===
=== How can I add my own App? ===
Line 234: Line 294:
Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and &quot;provider&quot; attribute set to &quot;[app]&quot;:
Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and &quot;provider&quot; attribute set to &quot;[app]&quot;:


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


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


The &quot;icon&quot; 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.
The &quot;icon&quot; 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.
Line 272: Line 334:
Example
Example


<blockquote>mygoogleapp:<br />
<blockquote>
enabled: true<br />
mygoogleapp:<br />
type: link<br />
&nbsp;&nbsp;enabled: true<br />
link:<br />
&nbsp;&nbsp;type: link<br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
&nbsp;&nbsp;link:<br />
type: playstore<br />
&nbsp;&nbsp;&nbsp;&nbsp;url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
'''capabilities: &quot;mygoogleapp_capability&quot;'''<br />
&nbsp;&nbsp;&nbsp;&nbsp;type: playstore<br />
providers: [app]<br />
&nbsp;&nbsp;'''capabilities: &quot;mygoogleapp_capability&quot;'''<br />
alternatives: []<br />
&nbsp;&nbsp;providers: [app]<br />
icon: fa-cloud<br />
&nbsp;&nbsp;alternatives: []<br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br />
&nbsp;&nbsp;icon: fa-cloud<br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;
&nbsp;&nbsp;displayName_t10e: &quot;My App for synchronizing files&quot;<br />
&nbsp;&nbsp;description_t10e: &quot;Synchronize your files with our Drive application.&quot;
</blockquote>
</blockquote>
The special &quot;capabilities&quot; attribute is only supported for scenarios of type &quot;link&quot; with the special &quot;app&quot; provider.
The special &quot;capabilities&quot; attribute is only supported for scenarios of type &quot;link&quot; with the special &quot;app&quot; provider.
Line 289: Line 352:
With such a &quot;capabilities&quot; attribute only users, which have the &quot;mygoogleapp_capability&quot; capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.
With such a &quot;capabilities&quot; attribute only users, which have the &quot;mygoogleapp_capability&quot; capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.


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

Latest revision as of 10:54, 5 May 2021

Client Onboarding
This information is valid from 7.8.1 on.

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.

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 "com.openexchange.client.onboarding.enabled"; in installed file /opt/open-xchange/etc/client-onboarding.properties needs to be set to "true" (default). So getting rid off the entire client on-boarding module simply requires setting the mentioned property to "false" (and executing /opt/open-xchange/sbin/reloadconfiguration 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 /opt/open-xchange/sbin/listonboardingproviders 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 /opt/open-xchange/sbin/parsei18nyaml command-line tool to generate a .pot file from translatable texts
  • The translatable description; check /opt/open-xchange/sbin/parsei18nyaml 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 /opt/open-xchange/sbin/listonboardingproviders command-line tool, which outputs something like:

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: app

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 /opt/open-xchange/etc/client-onboarding-scenarios.yml YAML file might look like (check "Configuring Onboarding scenarios" chapter for more details):

Onboarding 2.png

CalDAV/CardDAV

Identifiers: caldav & carddav

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 com.openexchange.client.onboarding.caldav.url in client-onboarding-caldav.properties file and property com.openexchange.client.onboarding.carddav.url in client-onboarding-carddav.properties file.

Drive/Mail Apps

Identifiers: driveapp & mailapp

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:

  • client-onboarding-driveapp.properties
  • client-onboarding-mailapp.properties

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

Drive Windows Client

Identifier: drivewindowsclient

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 this documentation for more details.

Sync App

Identifier: syncapp

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

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

Mail (IMAP/SMTP)

Identifier: mail

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: eas

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

Configuring Onboarding scenarios

Onboarding scenarios are configured through the /opt/open-xchange/etc/client-onboarding-scenarios.yml 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 /opt/open-xchange/etc/client-onboarding-scenarios.yml YAML file. Executing /opt/open-xchange/sbin/reloadconfiguration 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 /opt/open-xchange/i18n directory) either a restart or executing /opt/open-xchange/sbin/reloadconfiguration 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 /opt/open-xchange/etc/client-onboarding.properties. Every option is fully 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

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

Example:

com.openexchange.client.onboarding.apple.iphone.scenarios=mailappinstall, driveappinstall, eassync, mailsync, davsync

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 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 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 com.openexchange.sms.SMSServiceSPI needs to be implemented and published as an OSGi service. For parsing phone numbers provided by users com.openexchange.sms.PhoneNumberParserService can be used. That one is also available as an OSGi service and can be tracked accordingly. You can have a look at bundle com.openexchange.sms.sipgate as implementation reference.

Important: You must not install the open-xchange-sms-sipgate 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 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.

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

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):

com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp

Furthermore, that scenario needs to be made accessible to users as well:

com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp

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 ?

  1. Install open-xchange-client-onboarding package
  2. Edit /opt/open-xchange/etc/client-onboarding.properties and set com.openexchange.client.onboarding.enabled to true
  3. Edit noreply.properties to enable autoconfig sending via email. PS: Have a fully working smtp login available like “noreply@yourdomain.tld”
  4. Edit client-onboarding-scenarios.yml and set “enable” for : “driveappinstall” , “davsync” “davmanual” “mailsync” “mailmanual” to true
  5. Now set the correct caldav/carddav server FQDNs in the corresponding files for your setup
    • client-onboarding-caldav.properties
    • client-onboarding-carddav.properties
  6. Restart OX process
  7. Login to AppSuite. Click on Settings - Connect your device
  8. 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:

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:

  1. widget: get ox drive
  2. widget: update
  3. 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 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]":

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

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

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

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.

Onboarding 4.png