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.
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
.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
andApple.xml
. - Copy the entire
<dict>
entry fromApple.xml
that contains aPayloadType
ofcom.apple.eas.account
into the<array>
section ofcustom.mobileconfig
. For example, you would copy the following section intocustom.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>
- Once your edit of
custom.mobileconfig
is complete, copy and rename the file toApple.xml
so that it overwrites the filetraveler\cfg\client\Apple.xml
. In a HCL Traveler High Availability pool,Apple.xml
must be the same on all servers. - 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.
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 |
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.