Customizing the device configuration process for Apple

There is no additional client code that must be installed on an Apple device for it to connect to an IBM Traveler server. However, you must configure the Microsoft™ Exchange account on the device so that it can use Exchange ActiveSync to connect to the IBM Traveler server. Apple devices can be configured either manually or by using profiles. This topic also describes how to customize profiles (also known as .mobileconfig files) to work in your environment.

IBM Traveler ships with a default Apple profile that includes all of the information necessary for the mobile device to connect directly to the IBM Traveler server. Table 1 describes the profiles and includes their locations. When a mobile user on an Apple device accesses the IBM Traveler user home page and selects the Configure your Apple iPhone/iPad/iPod Touch link, a page prompts the user to generate an Apple profile. When the user does so, the profile data from traveler\cfg\client\Apple.xml is converted to the file ILNT.mobileconfig and automatically downloaded to the Apple device. When the Apple device detects a download of a file with the extension .mobileconfig, it automatically starts the installation of the profile.

Table 1. Apple client configuration files
File	Description
AppleTemplate.xml	This is the Apple client configuration template file, which contains all the default configuration information. Do not edit this file in case the original default information is needed again later. When the IBM Traveler server is installed, AppleTemplate.xml is installed in the `Domino data directory`\traveler\cfg\client directory on the server. If the client configuration file Apple.xml does not exist when the IBM Traveler task on the server starts, the file generates from the AppleTemplate.xml file in the same directory on the server.
Apple.xml	This is the Apple client configuration file on the IBM Traveler server (located in the `Domino data directory`\traveler\cfg\client directory). The Apple.xml file contains variables (described in the following table) that are used to pass default values to the client configuration file. These values are passed on Apple devices at run time when users log into the IBM Traveler user home page to configure their devices. Apple.xml should handle most IBM Traveler server setups using the values provided. However, if an administrator would like add additional Apple configuration sections, they can do so by following the additional instructions outlined below. Note: After Apple.xml is created, IBM Traveler does not modify the file. However, if the file is corrupted and needs to be recreated from scratch, delete Apple.xml and IBM Traveler uses AppleTemplate.xml to recreate it.
.mobileconfig	This is the Apple client configuration file that goes on user devices. The .mobileconfig file is dynamically generated for a user based on the Apple.xml file when the user logs on to the IBM Traveler user home page and creates an Apple account using an Apple profile (by selecting Configure your Apple iPhone/iPad/iPod Touch) rather than creating the Apple account manually. Note: Because the .mobileconfig file is dynamically generated, it cannot be digitally signed which means users get a prompt on the device saying that the file is not signed. Despite this, users should select Install Now.

Customizing the profile

A profile can be utilized to configure more than just the Exchange ActiveSync account which IBM Traveler uses. For example, there are additional settings for controlling the iCloud services on the Apple devices. Review the iOS Enterprise Support Documentation for information about profiles which can be created with the iPhone Configuration Utility. This guide explains how to create profiles which, in addition to Exchange account settings, contain device security policies, WiFi setup, VPN configuration and more. These profiles can then be distributed to your users or you could decide to replace the contents of Apple.xml with the new profile that was created with the iPhone Configuration Utility. If you decide to merge the profiles and have the IBM Traveler user home page deploy them, then you cannot sign the profile and therefore should not include any passwords with it.

Merging a custom profile from the iPhone Configuration Utility

If you are using the iPhone Configuration Utility to create a custom profile and want to merge it with the IBM Traveler settings, it is recommended that you merge your new custom .mobileconfig file with Apple.xml using the following steps:

Generate the custom profile using the iPhone Configuration Utility without signing it. For this example, the profile is named custom.mobileconfig.
Edit custom.mobileconfig and Apple.xml.

Copy the entire <dict> entry from Apple.xml that contains a PayloadType of com.apple.eas.account into the <array> section of custom.mobileconfig. For example, you would copy the following section into custom.mobileconfig:

<dict>

  <key>PayloadUUID</key>
  <string>837AE5F3-1380-4234-BAD0-8246A644AC2F-ILNT_HostNameILNT_HostPortHTTPILNT_HostPortHTTPS-ILNT_User</string>

  <!-- 
  Customizable and displayed on the Apple UI.
  During Profile installation, this shows up under More Details as the "Exchange Account"
  along with the Host and EmailAddress values.
  This is the account name shown at the bottom of the password prompt during Profile installation.
  This is the account name shown under General - Mail, Contacts, Calendar - Account.
  This is the account name shown in the Mail, Contact, and Calendar applications as needed.
  -->
		
  <key>PayloadDisplayName</key>
  <string>ILNT_User - IBM Traveler</string>

  <!-- Customizable, but not known to be displayed on the Apple UI anywhere. -->
  <key>PayloadDescription</key>
  <string>IBM Traveler for ILNT_User.</string>

  <!-- Customizable, but not known to be displayed on the Apple UI anywhere. -->
  <key>PayloadOrganization</key>
  <string>IBM Traveler</string> 
  <key>PayloadVersion</key>
  <integer>1</integer>

  <!-- Customizable, but not known to be displayed on the Apple UI anywhere. -->
  <key>PayloadIdentifier</key>
  <string>ILNT_User - IBM Traveler</string>

  <key>PayloadType</key>
  <string>com.apple.eas.account</string>

  <!-- Whether or not the user should be prevented from creating mail using 
  this account from apps other than the Mail app (for example, the Photos app). 
  This only applies to iOS5 or later devices. Default: <false/>. -->
  <key>PreventAppSheet</key>
  <false/>

  <!-- Whether or not mails should be prevented from being moved from the 
  Traveler (Exchange) account into a different account. This only applies to 
  iOS5 or later devices. Default: <true/>. -->
  <key>PreventMove</key>
  <true/>

  <!-- Default value for the number of past days of mail to sync; this 
  is the "Mail Days to Sync" value on the Apple UI. The user can still change the 
  setting (higher and lower) on the Apple UI.
  Valid values are 1, 3, 7, 14, 31, and 0 (unlimited/no limit). -->
  <key>MailNumberOfPastDaysToSync</key>
  <integer>3</integer>

  <key>UserName</key>
  <string>ILNT_User</string>

  <key>EmailAddress</key>
  <string>ILNT_Address</string>

  <!--  If you are using a proxy between the client and the Traveler server,
  you should set the "External Server URL" on the "IBM Traveler" tab
  in the server document.
  You should not need to modify the Host or SSL values (use the ILNT wildcards).
  If you do modify this value, it cannot have "http://" or "https:// at 
  the beginning as that is automatically prepended based on the SSL key's value.
  ILNT_HostPath has been removed from the string below. 
  If there is a "/" at the end of the string (for example, /traveler), Apple considers 
  this an "invalid" account and may clear the HTTP password used to connect to the server. 
  That is why we don't include the /traveler by default. The device will always add 
  /Microsoft-Server-ActiveSync, but not in the UI, so if /Microsoft-Server-ActiveSync 
  is not configured to route to Traveler on the server, the ILNT_HostPath must be added 
  back into the Host value. 
  For example, if you are using a proxy along with /travelertest01/traveler to point to 
  your test Traveler server instead of your production Traveler server where the proxy 
  changed it to /traveler and routed it to the test Traveler server based on the /travelertest01 
  part, you would need the ILNT_HostPath in Apple.xml. -->
  <key>Host</key>
  <string>ILNT_HostNameILNT_HostPortHTTPILNT_HostPortHTTPS</string>

  <!-- Actual values are <true/> or <false/> if not using the ILNT_HostProtocol wildcard. -->
  <key>SSL</key>
  ILNT_HostProtocol

</dict>

Once your edit of custom.mobileconfig is complete, copy and rename the file to Apple.xml so that it overwrites the file traveler\cfg\client\Apple.xml. In a IBM Traveler High Availability pool, Apple.xml must be the same on all servers.
Test the new profile by logging into the IBM Traveler user home page and generating a profile using your device.

If an administrator would like to change some of the displayed values in the profile, they can modify the Apple.xml using the information in the following tables and the comments in the file itself as guidelines.

Table 2. Apple.xml variables
Variable	Replacement value
ILNT_Address	The email address of the user
ILNT_HostName	The server host name
ILNT_HostPath	The servlet path name (for example, /servlet/traveler)
ILNT_HostPortHTTP	The server host port when using HTTP (for example, 80)
ILNT_HostPortHTTPS	The server host port when using HTTPS (for example, 443)
ILNT_HostProtocol	The server host protocol (<false/> or <true/> for SSL off or SSL on)
ILNT_User	The name of the user

Table 3. .mobileconfig parameters
Parameter	Default value	Description
UserName	ILNT_User	User name used to log into HTTP. ILNT_User is replaced with the IBM Traveler login user ID used when the profile is generated.
EmailAddress	ILNT_Address	ILNT_Address is replaced by the email address of the user when the profile is generated.
Host	ILNT_HostName ILNT_HostPortHTTP ILNT_HostPortHTTPS ILNT_HostPath	IBM Traveler server host name or IP address and the path, /servlet/traveler. This value should never need to be changed in the `Apple.xml` file as it is based on the External URL from the IBM® Traveler tab in the server document. If the generated value is incorrect, you should fix the External URL on the IBM® Traveler tab in the server document instead of in this file.
SSL	ILNT_HostProtocol	Use <false/> to force off SSL and <true/> to force SSL on. Otherwise, ILNT_HostProtocol is replaced based on your current connection type when the profile is generated.
PayloadDisplayName	IBM Traveler for `user name`	The name of the profile which displays when the profile is presented for installation. This can be any string. There are multiple PayloadDescription values in the file, and only the first level is known to be displayed in the UI on the device; the others are not displayed.
PayloadDescription	Configures the device for use with IBM Traveler for `user name`	The description of the profile, shown with the display name, which displays when the profile is presented for installation. There are multiple PayLoadOrganization values in the file, and only the first level is known to be displayed in the UI on the device; the others are not displayed.
PayloadOrganization	IBM Traveler	The organization of the profile, shown with the display name and description, which displays when the profile is presented for installation.
PreventAppSheet	False	Whether or not the user should be prevented from creating mail using this account from apps other than the Mail app (for example, the Photos app). This only applies to iOS5 or later devices.
PreventMove	True	Whether or not mails should be prevented from being moved from the Traveler (Exchange) account into a different account. This only applies to iOS5 or later devices.
MailNumberOfPastDaysToSync	3	Default value for the number of past days of mail to sync. This is the "Mail Days to Sync" value on the Apple UI. The user can still change the setting (higher and lower) on the Apple UI. Valid values are 1, 3, 7, 14, 31, and 0 (no limit).

Logon Name field considerations

When users generate the profile for their Apple device to use IBM Traveler, they are presented with a login screen that asks for their "Logon Name". The Logon Name is the name a user enters as their ID when signing into HTTP to acquire the profile. The user must enter this ID correctly, as Apple devices do not allow the alteration of the Logon Name once the profile is on the device. As a result, IBM Traveler asks the user to confirm the Logon Name before proceeding.

In an effort to help users, IBM Traveler prefills this value with a best guess. If the HTTP authorization header is present, IBM Traveler uses that for the prefill. If the HTTP authorization header is not present (normally because a cookie is used -- IBM Traveler cannot lookup cookies to find user names), the system will use the configured default entry (Canonical, Internet, or Blank), based on the IBM Traveler configuration setting NTS_CLIENT_CONFIG_DEFAULT_LOGON_NAME. If that is inaccurate, the user must correct it.

For more information, refer to Notes.ini settings.