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 HCL Traveler server. However, you must configure the Microsoft Exchange account on the device so that it can use Exchange ActiveSync to connect to the HCL 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.

HCL Traveler ships with a default Apple profile that includes all of the information necessary for the mobile device to connect directly to the HCL Traveler server. Table 1 describes the profiles and includes their locations. When a mobile user on an Apple device accesses the HCL 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 HCL 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 HCL 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 HCL 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 HCL Traveler user home page to configure their devices.

Apple.xml should handle most HCL 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, HCL Traveler does not modify the file. However, if the file is corrupted and needs to be recreated from scratch, delete Apple.xml and HCL Traveler uses AppleTemplate.xml to recreate it.
Note: Beginning with Traveler 11, AppleTemplate.xml has been updated to refer to HCL instead of IBM. If you have customized Apple.xml, you need to manually change Apple.xml if you want any of the HCL changes in AppleTemplate.xml. If you want to recreate Apple.xml from scratch, delete Apple.xml and Traveler will use AppleTemplate.xml to recreate Apple.xml.

.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 HCL 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 HCL 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 HCL 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 HCL Traveler settings, it is recommended that you merge your new custom .mobileconfig file with Apple.xml using the following steps:
  1. Generate the custom profile using the iPhone Configuration Utility without signing it. For this example, the profile is named custom.mobileconfig.
  2. Edit custom.mobileconfig and Apple.xml.
  3. 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 -  Traveler</string>
    
      <!-- Customizable, but not known to be displayed on the Apple UI anywhere. -->
      <key>PayloadDescription</key>
      <string> Traveler for ILNT_User.</string>
    
      <!-- Customizable, but not known to be displayed on the Apple UI anywhere. -->
      <key>PayloadOrganization</key>
      <string> 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 -  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 " 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>
  4. 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 HCL Traveler High Availability pool, Apple.xml must be the same on all servers.
  5. Test the new profile by logging into the HCL 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 HCL 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 HCL 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 HCL Traveler tab in the server document. If the generated value is incorrect, you should fix the External URL on the HCL 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 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 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 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 HCL 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, HCL Traveler asks the user to confirm the Logon Name before proceeding.

In an effort to help users, HCL Traveler prefills this value with a best guess. If the HTTP authorization header is present, HCL Traveler uses that for the prefill. If the HTTP authorization header is not present (normally because a cookie is used -- HCL Traveler cannot lookup cookies to find user names), the system will use the configured default entry (Canonical, Internet, or Blank), based on the HCL 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.