Updated Nov 29, 2009 by eofster
Labels:	Featured, Phase-Deploy
Locales:	en, ru

PreconfigureForYourUsers

Preconfiguration instructions.

Introduction

Telephone can be preconfigured before user launches it. You can include an XML property list file with settings which will be imported on first launch.

Details

Applications in Mac OS X are really directories called bundles. All you need to preconfigure Telephone is to generate an XML file named Settings.plist and copy it into Telephone.app/Contents/Resources directory. Then you archive the whole Telephone.app directory and deliver it to a user. When a user unarchives and launches it, settings from Settings.plist are imported to the standard user defaults database, password is securely stored in Keychain, and Settings.plist file is removed.

Telephone.app/
    ...
     Contents/
        Resources/
            ...
            Settings.plist
            ...
    ...

Here’s the minimum you need to setup an account. AccountSettingsExample.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Accounts</key>
	<array>
		<dict>
			<key>AccountEnabled</key>
			<true/>
			<key>Domain</key>
			<string>example.com</string>
			<key>FullName</key>
			<string>John Smith</string>
			<key>Realm</key>
			<string>*</string>
			<key>Username</key>
			<string>1234567</string>
			<key>Password</key>
			<string>secret</string>
		</dict>
	</array>
</dict>
</plist>

The easiest way to make your own template for Settings.plist is with Apple’s Property List Editor application. It is part of Developer Tools package which comes with every Mac OS X installation disc. However, you can use any text editor you like.

The following table shows two accounts and some other settings configured. FullSettingsExample.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Accounts</key>
	<array>
		<dict>
			<key>AccountEnabled</key>
			<true/>
			<key>Description</key>
			<string>The First Provider</string>
			<key>Domain</key>
			<string>example.com</string>
			<key>FullName</key>
			<string>John Smith</string>
			<key>PlusCharacterSubstitutionString</key>
			<string>00</string>
			<key>ProxyHost</key>
			<string></string>
			<key>ProxyPort</key>
			<integer>0</integer>
			<key>Realm</key>
			<string>*</string>
			<key>Registrar</key>
			<string></string>
			<key>ReregistrationTime</key>
			<integer>0</integer>
			<key>SIPAddress</key>
			<string></string>
			<key>SubstitutePlusCharacter</key>
			<false/>
			<key>UseProxy</key>
			<false/>
			<key>Username</key>
			<string>1234567</string>
			<key>Password</key>
			<string>secret1</string>
		</dict>
		<dict>
			<key>AccountEnabled</key>
			<true/>
			<key>Description</key>
			<string>The Second Provider</string>
			<key>Domain</key>
			<string>company.com</string>
			<key>FullName</key>
			<string>John Smith</string>
			<key>PlusCharacterSubstitutionString</key>
			<string></string>
			<key>ProxyHost</key>
			<string>sip.company.com</string>
			<key>ProxyPort</key>
			<integer>0</integer>
			<key>Realm</key>
			<string>*</string>
			<key>Registrar</key>
			<string></string>
			<key>ReregistrationTime</key>
			<integer>1800</integer>
			<key>SIPAddress</key>
			<string>john@company.com</string>
			<key>SubstitutePlusCharacter</key>
			<true/>
			<key>UseProxy</key>
			<true/>
			<key>Username</key>
			<string>john</string>
			<key>Password</key>
			<string>secret2</string>
		</dict>
	</array>
	<key>ConsoleLogLevel</key>
	<integer>3</integer>
	<key>LogLevel</key>
	<integer>4</integer>
	<key>STUNServerHost</key>
	<string>stun.example.com</string>
	<key>STUNServerPort</key>
	<integer>0</integer>
	<key>TransportPort</key>
	<integer>5060</integer>
	<key>UseDNSSRV</key>
	<true/>
	<key>UseICE</key>
	<true/>
	<key>VoiceActivityDetection</key>
	<false/>
</dict>
</plist>

Comment by NormDancy, Aug 12, 2009

Thank you for showing me this capability. It is really handy when handing out a new account.

Comment by bs.ramin, Sep 25, 2009

Is possible to auto-install this PropertyList? for our customer ? We can auto-generate this PropertyList? and our customer download this from the web panel.

Comment by eofster, Sep 25, 2009

Settings from the property list file are being applied on the first launch. You just need to generate the plist, copy it to the appropriate place inside Telephone.app directory (application bundle), archive the directory and deliver it to the user.

Applications in Mac OS X are really directories called bundles. All you need to preconfigure Telephone is to generate an XML file named Settings.plist and copy it into Telephone.app/Contents/Resources directory. Then you archive the whole Telephone.app directory and deliver it to a user. When a user unarchives and launches it, settings from Settings.plist are imported to the standard user defaults database, password is securely stored in Keychain, and Settings.plist file is removed.

Comment by bs.ramin, Sep 25, 2009

Good, but is not possible to download and "execute" the Settings.plist without download this included in the App ? Help us to distribute the settings for all accounts without need to force our customer to download more copy of telephone.app!

Comment by eofster, Sep 25, 2009

You can take ~/Library/Preferences/com.tlphn.Telephone.plist from a configured Telephone on a test machine. When the user manually replaces her com.tlphn.Telephone.plist file with yours, new settings should take place. But Telephone must not be launched when you copy your com.tlphn.Telephone.plist file to its distribution location and when a user overwrites her file with yours. And it’s not possible to overwrite user’s password this way because it is stored in the Keychain.

I don’t see any other options to change user’s settings.