Using the Delegate Utility for Exchange 2007 or 2010
Overview
The Delegate Permissions Utility is a scriptable command-line tool for managing the Deem services integration with an organization’s Exchange Server infrastructure.
In order for Deem services to update a user’s calendar directly in Exchange, it is necessary that either a delegate user account be configured and used as the service account for calendar updates; or, alternatively, for Exchange 2010 only, a service account may be configured with impersonation rights.
When a delegate account is used, user permissions must be set to allow the delegate account access to write event updates. Additionally, it is necessary that the Groupware ID field of the user’s profile as stored in Deem be properly provisioned with the user’s primary SMTP address. Users may often have secondary SMTP addresses so it is possible (especially in the case where user profiles are created using “open enrollment”) that Groupware ID’s are incorrectly provisioned, causing calendar synchronization to fail for the particular user.
The utility performs the following:
- Sets up or removes delegate permissions for primary calendar and/or contacts folders of specified Exchange Server users.
- Automates the updating of the Deem user profile database with a user’s Exchange primary SMTP addresses in the Deem Groupware ID field by resolving an incorrectly provisioned secondary SMTP address in the Groupware ID field. This operation is useful even if impersonation is configured instead of delegate access for Exchange 2010.
The utility is primarily used to operate on a list of users derived directly by the tool from the Deem Profile database using a configured Profile Web Services subscription. Although the delegate permission function may optionally be configured to operate on a list of users from a specified input file, the web services subscription usage mode is required for updating the Deem user profile with primary SMTP addresses.
Deem supports two protocols for Exchange: EWS (Exchange Web Services), which is supported by Exchange 2007 and 2010, and WebDav (Web Distributed Authoring and Versioning), which is supported by Exchange 2003 and 2007. Each protocol has a different server type, which is configured in the Partner Dashboard. This utility may be used only in conjunction with the Deem EWS groupware provider, as it relies on EWS to communicate with an Exchange Server.
Note: If you are using a web service subscription as the source of the user list, a valid profile web services subscription must exist and the credentials must be available for the desired target domain to pull users from. The subscription must have "batch read" and "PCI suppression" configured. "Update" permission must also be configured if Groupware IDs are to be updated.
Installing the Utility
Download the Delegate Permissions Utility
The Delegate Permissions Utility is provided as a ".zip" file. Unzipping creates a directory named “delegate”. You may want to add the path to this directory in your system %PATH% variable. Once a properties file is created, the command may be scheduled for routine execution using the Windows Scheduled Tasks feature.
You also will need to install Java JRE 6.0 or newer in order to run the utility. You can find that application at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Running the Utility
The utility is invoked from the Windows command line as follows:
rcdelegate <optional path>
If the optional path is specified and it refers to an existing file with read permission, the properties are read from that file. If the file name ends with ".xml", the file must conform to Java property XML file specifications. Otherwise, the file must conform to the Java property name-value pair file specification. The attributes and values are as described in the next section.
If the optional path is not specified or it does not refer to an existing file with read permission, an interactive interview is conducted to ascertain properties.
We recommend that you run the utility the first time with the name of a non-existent file for optional path. If the optional path is specified for a non-existing file, then an interactive interview will be conducted, and then a properties file is written once the utility has completed its work. The generated file will either be an XML file (with an ".xml" extension) or a name-value pair file. An example properties file in each format is available in the installation directory. The example property files contain comments describing each of the properties.
Property File Options
The following is a brief synopsis of the properties.
Using the Interview for Properties
The interactive interview is conducted only if no pre-existing properties file is available. The interview is divided into sections corresponding to the different categories of properties: exchange, operation, folder, user, logging, and csv.
The first question asked is whether the interview should be conducted in novice or expert mode. In novice mode, additional information is provided to assist in entering responses to the questions. Sometimes the assistance is in the form of example answers, and sometimes the valid choices are provided. In novice mode, the default answer may be provided and can be chosen simply by not answering the question.
The default is to conduct the interactive interview in expert mode. In either mode, all answers are immediately sanity-checked and an unreasonable answer results in the question being asked again. In many cases, the questions being asked depend upon previous answers. 
Validity Check
Whether properties are determined by properties file or by the interactive interview, once all of the properties are available, they are checked for validity. If one or more issues are raised, then all of the validity issues are shown on the console and the utility immediately exits.
Processing Steps
Assuming that the validity checks all pass, the utility begins processing each of the specified users. The list of users is determined in one of three ways:
single: A single user's primary SMTP address is specified.
list: A CSV file containing a list of primary SMTP addresses is specified. Only one column of the CSV file is significant. The column named "mail" is the column that is used. If there is only one column, or if the interesting column is the first column, then the first line does not need to specify names for the columns.
profile: The Deem user profile pull service is used. All users in the specified domain subscription and that specify a groupware ID are processed. In the case where the profile is used as the source for the list of users, the groupware IDs as found in profile need not correctly specify primary SMTP addresses, but may alternatively specify non-primary SMTP addresses. If the groupware IDs are not all accurately known to be primary SMTP addresses, then request resolution via the user.profile.resolve.option property. Each user with a resolved non-primary groupware ID will have its groupware ID replaced with the primary SMTP address within the Deem user profile.
For each specified user, the following actions are taken:
- If the logging level is default, verbose, or debug, the user name is written to the console.
- Optionally, the user name is resolved to a primary SMTP address. This only happens if the Deem user profile pull service is used and this feature is enabled by the user.profile.resolve.option property. For each resolved user:
- The user profile groupware ID is updated with the primary SMTP address.
- If the logging level is verbose or debug, the primary SMTP address is written to the console.
- If a resolutions CSV file is specified, then the original groupware ID, the updated groupware ID, and the profile's external ID are written to the user.profile.resolve.file.path CSV file.
- The delegate permissions are either set up or removed for either the primary calendar folder, the primary contacts folder, or both. If unable to complete the change, and the logging level is verbose or debug, then the reason for the failure is written to the console.
- If a logging CSV file is specified, then the date and time, the original user name, the resolved primary SMTP address (if applicable), the operation ("get", "set" or "unset"), and either "OK" or the reason for failure are written to the logging CSV file.
- If the logging level is progress, a dot is written to the console.