IBM Support

Managing IBM Verse for iOS using AppConfig

White paper


Abstract

This article describes the steps required for an Enterprise Mobility Management (EMM) administrator to deploy the IBM Verse for iOS mobile app.

Content

The app deployed in this scenario is the base IBM Verse for iOS mobile app that is distributed from the Apple app store. This article applies to Verse for iOS version 9.4.0 and higher. This procedure requires a Mobile Device Management (MDM) profile to be provisioned to the device by your EMM. Any EMM can be used that has the capability of managing an Apple iOS device, though this article will provide examples based on IBM’s MaaS360 EMM.

Verse for iOS supports the Apple iOS Enterprise Management features which can be controlled using Mobile Device Management policies. Verse for iOS supports application management as described by the AppConfig.org Community and supported by Apple. The following management capabilities are examples of management features supported by the Verse for iOS app:

  • Custom App Configuration
  • App Tunnel using Per App VPN
  • Device Passcode and Touch ID
  • Managed Open In for Files
  • Prevent App Backup
  • Disable Screen Capture
  • Remotely Wipe App and Data
  • Disable Copy Paste

Managing Verse for iOS on managed devices

The first step in managing the Verse for iOS app is to define your EMM device policies that are important for your organization. A device policy is required to manage any native iOS app. When a user provisions their device with the device policy, any applications that are installed using the EMM enterprise app catalog or that are even listed in the EMM enterprise app catalog will be installed as managed apps. Managed apps get access to resources such as per app custom configuration and per app VPN tunnels that can be accessed only by your enterprise apps.

There are many device policies and customizable restrictions available for an Apple iOS device. The most common include:

  • Device passcode
  • Restricting access to managed files
  • Per App VPN for app tunneling
  • Disable screen capture
  • WiFi provisioning
  • Prevent app data backup

The steps for defining and assigning a device policy to an Apple iOS device will vary per EMM provider. See your EMM provider’s documentation to determine exactly how to create and assign a device policy. For IBM’s MaaS360 EMM, policy creation starts on the Security view, using the Add Policy action. Select a Type of iOS MDM for the Policy Type.

Once the policy is created in MaaS360, you can define device and advanced settings. Passcode, Restrictions, Application Compliance, VPN and many others.

Once your options are defined, save and publish the policy to users or devices.


Distributing Verse for iOS to devices

Verse for iOS must be placed into your EMM provider’s enterprise app catalog for it to be properly managed on an Apple device. Once the app is available in the app catalog, users can easily install it from your EMM provider’s app catalog on the device. Or, if you have enabled a setting to enforce management of all apps listed in the app catalog, then even if a user were to install Verse for iOS directly from Apple iTunes (or even Apple TestFlight), then the app will still become a managed app and behave like a managed app. The steps will vary from one EMM to another on how the app is loaded into the enterprise app catalog, so consult your EMM provider’s documentation.

For IBM’s MaaS360, follow these steps:

1. Make sure that you first have enabled the option which converts apps in the app catalog to ‘managed’ on devices where the app is stalled from another source. This setting is found under Settings->Deployment Settings as shown in the screenshot below. Note that while this is a global setting for MaaS360, some EMM providers ask that you make this decision for each app as you add it to the enterprise app catalog.

2. Navigate to Apps -> Catalog.

3. Select Add -> iTunes App Store App.

4. For the App Name, enter IBM Verse and select IBM Verse from the list when it is found.

5. Select the Policies and Distribution tab and enable desired policies and define which users or devices should receive this app.

6. The configuration tab could be completed at this point or can be done later. Review the section on custom app configuration in this document. Select Add and this app will appear in your enterprise app catalog for iOS devices.


Creating a custom app configuration profile
Verse for iOS supports custom managed configuration which allows the EMM administrator to preconfigure many Verse for iOS settings. Any setting defined using the EMM takes precedence over a similar setting or policy defined at the Traveler server. Setting custom app configuration will vary by EMM. All EMM providers support the concept of Apple managed configuration using custom keys and values. However, some EMM providers now support definition of these parameters using an app’s AppConfig XML definition file as defined by the AppConfig Community. Verse for iOS provides the file Verse_AppConfig.xml which defines the supported configuration settings for this app. If your EMM supports an AppConfig.xml file, it is recommended to use this file over manually entering in managed configuration keys and values. Not all EMM providers support AppConfig.xml, and if your provider does not support this format yet, you can still enter in configuration keys and values separately. See the Verse iOS App Configuration Reference below for a listing of keys and values supported by Verse for iOS.

Enterprise Mobility Manager Managed Configuration Keys AppConfig XML Notes
IBM MaaS360 Yes Yes MaaS360 supports direct upload of Verse_AppConfig.xml
MobileIron Yes Yes
VMWare AirWatch Yes Yes AirWatch supports direct upload of Verse_AppConfig.xml.
Citrix XenMobile Yes No While Citrix XenMobile does not support the file format of Verse_AppConfig.xml, it can provide the same managed configuration data using a device profile. See the section in this article called Custom App Configuration using Citrix XenMobile.

If your EMM is not listed in this table, it may still support AppConfig.xml files and will support Managed Configuration Keys assuming it also supports Apple iOS device management.

The following example shows how to set custom configuration for Verse using IBM’s MaaS360 EMM provider.

1. From the MaaS360 administration portal, navigate to Apps -> Catalog. This procedure assumes you have already added Verse for iOS to the app catalog as described in Distributing Verse for iOS to devices below, but it is also possible to follow these steps when you add Verse for iOS to the app catalog.

2. Select the View action for the Verse for iOS from the app catalog.

3. While viewing Verse for iOS in the app catalog, select More -> Edit App Configuration Values.

4. For App Config Source, verify that Config XML File is selected.

5. For the Config XML File, select Choose and pick the file Verse_AppConfig.xml.

6. Fill out the desired configuration settings as shown in the screen below. Make sure to scroll down to review all available settings.


Custom App Configuration using Citrix XenMobile

The following steps are based on Citrix XenMobile documentation for defining an App Configuration Device Policy for an iOS app. It is recommended that you consult the XenMobile documentation for your specific version of XenMobile to ensure that these steps have not changed. These steps are performed by your Citrix XenMobile administrator.

1. In the XenMobile console, click Configure > Device Policies. The Device Policies page appears.

2. Click Add. The Add a New Policy page appears.

3. Expand More, and then under Apps, click App Configuration. The App Configuration Policy information page appears.

4. In the Policy Information pane, enter the following information:

  • Policy Name: Type a descriptive name for the policy.
  • Description: Optionally, type a description of the policy.

5. In the Platforms list, uncheck all platforms other than iOS.

6. Click Next. The iOS Platform information page appears.

7. Configure the app identifier. In the list, click the app you want to configure or click Add new to add a new app to the list. The first time the Verse app is configured, you must click Add new. The app identifier to use is com.ibm.lotus.traveler.

8. Add the Dictionary content. Copy the text below to your clipboard and paste into the input field.
<dict>
 <key>appConfigOnly</key>
   <true/>
 <key>serverType</key>
   <string>choice</string>
 <key>serverURL</key>
   <string></string>  
 <key>user</key>  
   <string></string>  
 <key>password</key>  
   <string></string>  
 <key>restrictClipboard</key>  
   <false/>
 <key>disableShareMenu</key>  
   <false/>
 <key>disableRemoteImages</key>  
   <false/>
 <key>mamKey</key>
   <string></string>
 <key>mamKeyMismatchTimeout</key>
   <integer>24</integer>

 
<key>disableAttachmentExport</key>  
   <false/>
 <key>mailFilterDays</key>
   <integer>3</integer>

  <key>mailFilterDays.lock</key>  
   <false/>
 <key>previewLines</key>  
   <integer>2</integer>
 <key>previewLines.lock</key>  
   <false/>
 <key>confirmDelete</key>  
   <false/>
 <key>confirmDelete.lock</key>  
   <false/>
 <key>attachmentFilter</key>  
   <integer>100</integer>
 <key>attachmentFilter.lock</key>  
   <false/>
 <key>mailThreads</key>  
   <false/>
 <key>mailThreads.lock</key>  
   <false/>
 <key>useMailSignature</key>  
   <false/>
 <key>useMailSignature.lock</key>  
   <false/>
 <key>mailSignature</key>  
   <string></string>
 <key>mailSignature.lock</key>  
   <false/>
 <key>bccMyself</key>  
   <false/>
 <key>bccMyself.lock</key>  
   <false/>
 <key>calendarPastFilterDays</key>  
   <integer>14</integer>
 <key>calendarPastFilterDays.lock</key>  
   <false/>
 <key>calendarAlarms</key>  
   <true/>
 <key>calendarAlarms.lock</key>  
   <false/>
 <key>calendarAudioAlarms</key>  
   <true/>
 <key>calendarAudioAlarms.lock</key>  
   <false/>
 <key>weekStartDay</key>  
   <integer>0</integer>
 <key>weekStartDay.lock </key>  
   <false/>
 <key>exportContacts</key>  
   <false/>
 <key>exportContacts.lock</key>  
   <false/>
 <key>searchCorpDirectory</key>  
   <true/>
 <key>searchCorpDirectory.lock</key>  
   <false/>
 <key>contactSortOrder</key>  
   <string>lastfirst</string>
 <key>contactSortOrder.lock</key>  
   <false/>
 <key>contactDisplayOrder</key>  
   <string>firstlast</string>
 <key>contactDisplayOrder.lock</key>  
   <false/>
 <key>appPassword</key>
   <false/>
 <key>appPasswordType</key>
   <string>numeric</string>
 <key>appPasswordMinLetters</key>
   <integer>0</integer>
 <key>appPasswordMinNumeric</key>
   <integer>0</integer>
 <key>appPasswordMinNonLetters</key>
   <integer>0</integer>
 <key>appPasswordMinUppercase</key>
   <integer>0</integer>
 <key>appPasswordMinLowercase</key>
   <integer>0</integer>
 <key>appPasswordMinSymbols</key>
   <integer>0</integer>
 <key>appPasswordMinLength</key>
   <integer>4</integer>
 <key>appPasswordAutolock</key>
   <integer>30</integer>
 <key>appPasswordExpiration</key>
   <integer>0</integer>
 <key>appPasswordHistory</key>
   <integer>0</integer>
 <key>appPasswordWipeFailures</key>
   <integer>0</integer>
 <key>appPasswordProhibitSequences</key>
   <false/>
 <key>appPasswordProhibitTouchID</key>
   <false/>
</dict>

9. Edit the dictionary content to customize it for your organization. For details on each setting, see the section below named Verse iOS App Configuration Reference.

Note:
If you are deploying this profile to multiple users, then use Citrix XenMobile Macros to specify the value for the user parameter. For example, ${user.username} populates the user name value in the text field of any policy.

10. Click the Check Dictionary button to ensure that the XML is valid. If there are no errors, you see Valid XML below the content box. If any syntax errors appear below the content box, you must correct them before you can continue.

11. Click Next. The App Configuration Policy assignment page appears.

12. Next to Choose delivery groups, type to find a delivery group or select a group or groups in the list to which you want to assign the policy. The groups you select appear in the Delivery groups to receive app assignment list.

13. Click Save.


How do I restrict files from Verse for iOS from be shared with unmanaged apps?

This behavior can be configured by setting up a Restrictions Device Policy using your EMM administration portal. The exact label wording may vary from one EMM to another, but typically there will be two specific settings for restricting if files can be shared between managed apps and unmanaged apps. One setting will prohibit sharing of files from managed apps to unmanaged apps. This is the most common setting and is recommended if you are looking to prevent file data from being shared from the Verse for iOS app to other, unmanaged apps that are on the same device. The other setting will prohibit sharing of files from unmanaged apps to managed apps. This is more uncommon to set, but if you have a use case where you want to prevent files originating from an unmanaged apps from being emailed using Verse for iOS, then prohibit this file sharing.

For IBM’S MaaS360, these settings are in the Device Settings tab of the iOS MDM Policy, with the Restrictions section of the policy. They are named Allow Open from Managed to Unmanaged Apps and Allow Open from Unmanaged to Managed Apps.




How can I connect to my On-Premises IBM Traveler server?
Verse for iOS communicates with its Traveler server over a secured TLS channel using the HTTPS protocol. Depending on your network topology and the placement of your Traveler server, the server may or may not be directly accessible from the mobile application without deploying a network tunnel. The Planning your Network Topology article in the IBM Traveler Knowledge center describes three possible options.

  • Reverse Proxy
  • Virtual Private Network
  • Direct connection

If using a Reverse Proxy or a Direct Connection, then to set up Verse for iOS, just provide the Server URL to the Proxy or the Traveler server using custom configuration. However, if these topologies do not match your needs, you can also use a Per App Virtual Private Network (Per App VPN). A Per App VPN can be defined as a device policy and access to the tunnel can be restricted to only managed apps on the device, or even to just a subset of those managed apps. The tunnel is activated on demand and will close when no longer required.


Using the AirWatch Secure Email Gateway
IBM Verse for iOS supports connecting through the AirWatch Secure Email Gateway when connecting to the Traveler server. When using this configuration, make sure to set the deviceId AppConfig configuration parameter set to value {EASDeviceIdentifier}. This value is an AirWatch macro which will expand to a unique identifier for each device used, and it will cause the Verse iOS device to use this identifier when syncing with the Traveler server. The AirWatch Secure Email Gateway uses this value to determine if a device is managed or not so that it can enforce that only managed devices are allowed to connect to the Traveler server.
Note that when using the deviceId key, ensure that the IBM Traveler server is running version 9.0.1.19 or later.

How can the Verse app and data be removed or wiped from the device?
Since Verse for iOS is deployed as a managed app, removing the device profile will remove Verse and all Verse data from the device (this is true for all managed apps). A user could do this themselves if the policy allows for this, or the profile could be removed remotely by the EMM administrator.

Most EMM providers also allow the administrator to configure Automated Actions which can monitor various compliance scenarios. If one of the monitors is triggered, various actions can be automatically executed, ranging from wiping the enterprise apps and data from the device to notifying the user via an email. See your EMM documentation for more information.


Verse iOS App Configuration Reference
Use the table below as a reference for the custom app configuration XML. This table can be used if your EMM provider does not yet support the AppConfig schema as defined by the AppConfig Community. If your EMM does support an AppConfig.xml file, then use the Verse_AppConfig.xml file that has been provided with this article.

IMPORTANT NOTE: All keys and values in the table below are case sensitive. If you are manually copying these settings to your EMM, ensure that the case used matches this document.

Key Value Details
appConfigOnly Type: Boolean
Default: false
Values
:
true
false
Always enable this setting unless using MobileIron or MaaS360. Enable to force the use of AppConfig settings. Only disable this setting if you are using the older SDK integration of Verse with MobileIron and MaaS360.
Account Settings
serverType Type: String
Default: choice
Values:
choice
onpremises
cloud
Where is your Traveler server located? Set to ‘choice’ to give the user the choice.
serverURL Type: String
Default: none
Provide the hostname or a fully qualified URL to your company's Traveler server. Only provide this value if using ‘onpremises’ as the server type.
user Type: String
Default: none
Login user id or name. Macros are accepted if they are available. Consult your EMM documentation for the availability of substitution macros or variable names.
password Type: String
Default: none
Login password. Macros are accepted if they are available. Consult your EMM documentation for the availability of substitution macros or variable names.
deviceId Type: String
Default: none
Unique identifier for this device. Leave blank unless using an MDM provider which requires this to be set. This value must be unique for all devices used by a user so it must use an MDM provider macro as a value. Requires IBM Traveler server version 9.0.1.19 or later.
Restrictions
restrictClipboard Type: Boolean
Default: false
Values:
true
false
Enable to enforce that copy and paste operations are restricted to only this application. Information copied to the clipboard from inside the app can only be pasted within the same app.
disableShareMenu Type: Boolean
Default: false
Values:
true
false
Disabling the Share menu will disable the share and copy options from the apps context menus. Disable this option to prevent selected text from being shared with other apps such as Apple’s Notes app. This option also disables the attachment viewing options within the Verse app, since it is otherwise possible to share text within an attachment preview.
disableRemoteImages Type: Boolean
Default: false
Values:
true
false
Enable to prevent the user from loading and viewing images hosted on external web sites.
mamKey Type: String
Default: none
If your Traveler server has defined a MAM Required Signature, include the corresponding Signature Key here. See Configuring the Mobile Application Management required policy for Verse Mobile apps article for more information.
mamKeyMismatchTimeout Type: Integer
Default: 24
When changing the MAM Signature Key, allow up to Mismatch Timeout hours for the keys to be distributed before the application blocks. See Configuring the Mobile Application Management required policy for Verse Mobile apps article for more information.
disableAttachmentExport Type: Boolean
Default: false
Values:
true
false
If export is prohibited, attachments can only be viewed if there is an Apple viewer compatible with the file type.
Mail Settings
mailFilterDays Type: Integer
Default: 3
Values:
1
3
7
14
30
90
180
365
0
Sync up to this many days of mail. 0 means unlimited mail.
mailFilterDays.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Days to Sync setting.
previewLines Type: Integer
Default: 2
Values:
0
1
2
3
Lines of message text to display in the message preview. Set to zero to disable message preview.
previewLines.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Preview Lines setting.
confirmDelete Type: Boolean
Default: false
Values:
true
false
When enabled, prompt to confirm deletion of each mail message.
confirmDelete.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Confirm Delete setting.
attachmentFilter Type: Integer
Default: 100
Values:
0
25
100
500
2000
10000
Automatically download attachments that are smaller than the specified threshold (units are in Kilo-Bytes). Set to zero to disable automatic attachment download. Attachments that are not downloaded automatically can still be manually downloaded when a user views the message.
attachmentFilter.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Attachment Download setting.
mailThreads Type: Boolean
Default: false
Values:
true
false
Enable mail conversation threading.
mailThreads.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Organize by Thread setting.
useMailSignature Type: Boolean
Default: false
Values:
true
false
When enabled, append the mail signature to outbound mail messages.
useMailSignature.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Use Mail Signature setting.
mailSignature Type: String
Default: none
Specify the signature text to be used when composing a new message or reply.
mailSignature.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Mail Signature setting.
bccMyself Type: Boolean
Default: false
Values:
true
false
When enabled, add the composer's email address to the Blind Carbon Copy (BCC) for each new composed message or reply.
bccMyself.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Always BCC Myself setting.
mailNotification Type: Integer
Default: 0
Values:
0
1
2
Notification option when new mail arrives.
0 = All Mail
1 = Important People Only*
2 = None

* Important People Only is only valid when connecting to IBM Connections Cloud. Do not use this option if connecting to My Company's Server.
mailNotification.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Mail Notifications setting.
mailNotifyMeNow Type: Boolean
Default: false
Values:
true
false
Notify me immediately - Enable this option to be notified of new messages that arrive in your inbox but are not yet synced with your device.
mailNotifyMeNow.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Notify me immediately setting.
Calendar
calendarPastFilterDays Type: Integer
Default: 14
Values:
0
14
30
90
180
Sync up to this many days of past calendar events. Zero syncs all calendar entries.
calendarPastFilterDays.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Show Past Events setting.
calendarAlarms Type: Boolean
Default:true
Values:
true
false
Display a visual alert when a calendar alarm is triggered.
calendarAlarms.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Visual Alerts setting.
calendarAudioAlarms Type: Boolean
Default: true
Values:
true
false
Play a sound or vibrate the device when a calendar alarm is triggered.
calendarAudioAlarms.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Audio Alerts setting.
weekStartDay Type: Integer
Default: 0
Values:
0
1
2
3
4
5
6
Start a calendar week on the specified day. 0=Sunday, 1=Monday, 2=Tuesday, etc.
weekStartDay.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Start Week On setting.
Contacts
exportContacts Type: Boolean
Default: false
Values:
true
false
Enable to sync Verse contacts with the OS so they can be used by caller ID.
exportContacts.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Export Verse Contacts setting.
searchCorpDirectory Type: Boolean
Default: true
Values:
true
false
Include search results from your corporate directory enabled at the Traveler server.
searchCorpDirectory.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Corporate Directory Search setting.
contactSortOrder Type: String
Default: lastfirst
Values:
firstlast
lastfirst
Sort contacts by first or last name.
contactSortOrder.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Sort Order setting.
contactDisplayOrder Type: String
Default: firstlast
Values:
firstlast
lastfirst
Display contact entries starting with either the first or last name.
contactDisplayOrder.lock Type: Boolean
Default: false
Values:
true
false
Prevent users from changing the Display Order setting.
Application Password
appPassword Type: Boolean
Default: false
Values:
true
false
Enabling requires the user to set a unique password that must be entered when the Verse application is accessed. This is like a device passcode, but it applies only to the Verse application and not the entire device.
appPasswordType Type: String
Default: numeric
Values:
numeric
alphabetic
alphanumeric
complex
Password type:

Numeric – only allow numbers

Alphabetic – only allow alphabetic characters

Alphanumeric – Allow numbers and alphabetic characters

Complex – Require a mixture of Letters, Non-Letters, Uppercase, Lowercase and Symbols.

appPasswordMinLength Type: Integer

Default: 4

Minimum number of characters in an acceptable password. Must be 4 or higher. Applies to all password types.
appPasswordMinLetters Type: Integer

Default: 0

Minimum number of letters to require in a Complex password. Only applicable for Complex passwords.
appPasswordMinNonLetters Type: Integer

Default: 0

Minimum number of non-letters to require in a Complex password. Only applicable for Complex passwords.
appPasswordMinNumeric Type: Integer

Default: 0

Minimum number of numbers to require in a Complex password. Only applicable for Complex passwords.
appPasswordMinUppercase Type: Integer

Default: 0

Minimum number of uppercase letters to require in a Complex password. Only applicable for Complex passwords.
appPasswordMinLowercase Type: Integer

Default: 0

Minimum number of lowercase letters to require in a Complex password. Only applicable for Complex passwords.
appPasswordMinSymbols Type: Integer

Default: 0

Minimum number of symbols to require in a Complex password. Only applicable for Complex passwords.
appPasswordAutolock Type: Integer

Default: 30

The amount of time in minutes after which the app will require the user to re-enter the password. Range is 1 – 60 (minutes).
appPasswordWipeFailures Type: Integer

Default: 0

The number of times a user can enter an incorrect password before all data for the app is removed from the device. Zero disables wipe on failures.
appPasswordExpiration Type: Integer

Default: 0

The number of days a password can be used before the user is required to change it. Zero means the password will never expire.
appPasswordHistory Type: Integer

Default: 0

The number of prior passwords that can't be reused. Zero means no history is maintained.
appPasswordProhibitSequences Type: Boolean
Default: false
Values:
true
false
Prohibit ascending, descending, repeating sequences in the password. If set to true, the password cannot contain any repeating characters or 3 or more ascending/descending characters.
appPasswordProhibitTouchID Type: Boolean
Default: false
Values:
true
false
Prohibit a user from using Touch ID instead of entering the app password.





Document information

More support for: IBM Traveler
iOS

Software version: 9.0.1

Operating system(s): iOS

Reference #: 7049934

Modified date: 12 September 2017


Translate this page: