Product Documentation

XenMobile Mail Manager 10.x

For the most recent information about XenMobile Mail Manager, see the XenMobile Service documentation on XenMobile Mail Manager.

XenMobile Mail Manager provides the functionality that extends the capabilities of XenMobile in the following ways:

  • Dynamic Access Control for Exchange Active Sync (EAS) devices. EAS devices can be automatically allowed or blocked access to Exchange services.
  • The ability for XenMobile to access EAS device partnership information provided by Exchange.
  • The ability for XenMobile to perform an EAS Wipe on a mobile device.
  • The ability for XenMobile to access information about Blackberry devices, and to perform control operations such as Wipe and ResetPassword.

To download XenMobile Mail Manager, go to the Server Components section under XenMobile 10 Server on Citrix.com.

What’s new in version 10.1.4.11

XenMobile Mail Manager version 10.1.4.11 contains the following fixed issues:

  • Due to its weakening security, TLS 1.0 is being deprecated by the PCI Council. Support for TLS 1.1 and 1.2 is added to XenMobile Mail Manager. [CXM-38573, CXM-32560]
  • XenMobile Mail Manager includes a new diagnostic file. When Enable Diagnostics is selected in the Exchange specification, a new Snapshot History file is generated. With every snapshot attempt, a line is added to the file with the results of the snapshot. [CXM-49631]
  • In the Commands diagnostic file, the list of devices allowed or blocked did not appear for the Set-CASMailbox command. Instead the internal class name was shown in the file for the related arguments. XenMobile Mail Manager now shows the list of deviceIDs as a comma-delimited list. [CXM-50693]
  • When an attempt to acquire a connection to Exchange fails due to a bad specification: The error message is overridden by an incorrect message: “All connections in use”. More descriptive messages now appear, such as “All connections are inoperable”, “Connection pool is empty”, “All connections are throttled”, and “No available connections”. [CXM-50783]
  • In some cases, Allow/Block/Wipe commands are queued up in the XenMobile Mail Manager internal cache multiple times. This issue causes a delay in the command being sent to Exchange. XenMobile Mail Manager now only queues up one instance of each command. [CXM-51524]

What’s new in version 10.1.3

  • Google Analytics support: We want to know how you use XenMobile Mail Manager so we can focus on where we can make the product better.
  • Setting for enabling diagnostics: An Enable Diagnostic check box appears in the Configure console on the Configuration dialog box.

Image of Mail Manager Console

Fixed issues in version 10.1.3

  • In the Snapshot History window, tooltips that show the current state of the snapshot do not reflect the actual state. [CXM-5570] Occasionally, XenMobile Mail Manager cannot write to the Commands diagnostics file. When this occurs, the command history is not logged in its entirety. [CXM-49217]
  • When an error occurs with a connection, the connection may not be marked as “errored”. As a result, a subsequent command may attempt to use the connection and cause another error. [CXM-49495]
  • When throttling from the Exchange Server occurs, an exception could be thrown in the Check Health routine. As a result, connections that have experienced an error or have expired might not be purged. Also, XenMobile Mail Manager might not create connections until the throttling time expires. [CXM-49794].
  • When the max session count for Exchange is exceeded, XenMobile Mail Manager reports the error “Device Capture Failed,” which is not an accurate message. Instead, the message should indicate that the two sessions that XenMobile Mail Manager normally uses for Exchange communication are in use. [CXM-49994]

What’s new in version 10.1.2

  • Improved connection to Exchange: XenMobile Mail Manager uses PowerShell sessions to communicate with Exchange. A PowerShell session, especially when dealing with Office 365, can become unstable after awhile, blocking subsequent commands from succeeding. XenMobile Mail Manager can now set an expiration period for connections. When the connection reaches its expiration time, XenMobile Mail Manager gracefully shuts down the PowerShell session and creates a session. By doing so, the PowerShell session is less likely to become unstable, significantly reducing the chance of a snapshot failure.
  • Improved snapshot workflow: Major snapshots are a time-consuming and process-intensive operation. If an error occurs during a snapshot, XenMobile Mail Manager now attempts multiple times (up to three) to complete a snapshot. Subsequent attempts do not start from the beginning. XenMobile Mail Manager continues from where it left off. This enhancement improves the success rate of snapshots in general by allowing transient errors to pass while a snapshot is still in progress.
  • Improved diagnostics: Troubleshooting snapshot operations are now easier with three new diagnostics files optionally generated during a snapshot. These files help identify PowerShell command issues, mailboxes with missing information, and devices that cannot be related to a mailbox. An admin can use these files to identify data that may not be correct in Exchange.
  • Improved memory usage: XenMobile Mail Manager is now more efficient in its use of memory. Admins can schedule XenMobile Mail Manager to restart automatically to provide a clean slate to the system.
  • Microsoft .NET Framework 4.6 prerequisite: The prerequisite for Microsoft .NET Framework is now version 4.6.

Fixed issues

  • Prompt for credentials error: Office 365 session instability often caused this error. The Improved Connection to Exchange enhancement addresses the problem. (XMHELP-293, XMHELP-311, XMHELP-801)
  • Mailbox and device count inaccuracies: XenMobile Mail Manager has an improved Mailbox-to-Device association algorithm. The Improved Diagnostics feature helps in the identification of mailboxes and devices that XenMobile Mail Manager deems are not within its realm of responsibility. (XMHELP-623)
  • Allow/Block/Wipe commands not being recognized: A bug was fixed where sometimes, XenMobile Mail Manager allow/block/wipe commands are not recognized. (XMHELP-489)
  • Memory management: Better memory management and mitigation. (XMHELP-419)

Architecture

The following diagram shows the main components of XenMobile Mail Manager. For a detailed reference architecture diagram, see the XenMobile Deployment Handbook article, Reference Architecture for On-Premises Deployments.

Diagram of XenMobile Mail Manager architecture

The three main components are:

  • Exchange ActiveSync Access Control Management: Communicates with XenMobile to retrieve an Exchange ActiveSync policy from XenMobile, and merges this policy with any locally defined policy to determine the Exchange ActiveSync devices that should be allowed or denied access to Exchange. Local policy allows extending the policy rules to allow access control by Active Directory Group, User, Device Type, or Device User Agent (generally the mobile platform version).
  • Remote PowerShell Management: Responsible for scheduling and invoking remote PowerShell commands to enact the policy compiled by Exchange ActiveSync Access Control Management. Periodically takes a snapshot of the Exchange ActiveSync database to detect new or changed Exchange ActiveSync devices.
  • Mobile Service Provider: Provides a web service interface so that XenMobile can query Exchange ActiveSync, query Blackberry devices, and issue control operations such as Wipe against ActiveSync and Blackberry devices.

System requirements and prerequisites

The following minimum system requirements are required to use XenMobile Mail Manager:

  • Windows Server 2012 R2, Windows Server 2008 R2 (must be an English-based server)
  • Microsoft SQL Server 2016, SQL Server 2014, SQL Server 2012, SQL Server 2012 Express LocalDB, or SQL Server Express 2008
  • Microsoft .NET Framework 4.6
  • Blackberry Enterprise Service, version 5 (optional)

Minimum supported versions of Microsoft Exchange Server:

  • Microsoft Office 365
  • Exchange Server 2016
  • Exchange Server 2013
  • Exchange Server 2010 SP2

Prerequisites:

  • Windows Management Framework must be installed.
    • PowerShell V5, V4, and V3
  • The PowerShell execution policy must be set to RemoteSigned via Set-ExecutionPolicy RemoteSigned.
  • TCP port 80 must be open between the computer running XenMobile Mail Manager and the remote Exchange Server.

Device email clients: Not all email clients consistently return the same ActiveSync ID for a device. Because XenMobile Mail Manager expects a unique ActiveSync ID for each device, only email clients that consistently generate the same, unique ActiveSync ID for each device are supported. These email clients have been tested by Citrix and performed without errors:

  • HTC native email client
  • Samsung native email client
  • iOS native email client
  • TouchDown for Smartphones

Exchange: The requirements for on-premises computer running Exchange are as follows:

The credentials specified in the Exchange Configuration UI must be able to connect to the Exchange Server and be given full access to execute the following Exchange-specific PowerShell cmdlets.

  • For Exchange Server 2010 SP2:
    • Get-CASMailbox
    • Set-CASMailbox
    • Get-Mailbox
    • Get-ActiveSyncDevice
    • Get-ActiveSyncDeviceStatistics
    • Clear-ActiveSyncDevice
    • Get-ExchangeServer
    • Get-ManagementRole
    • Get-ManagementRoleAssignment
  • For Exchange Server 2013 and Exchange Server 2016:
    • Get-CASMailbox
    • Set-CASMailbox
    • Get-Mailbox
    • Get-MobileDevice
    • Get-MobileDeviceStatistics
    • Clear-MobileDevice
    • Get-ExchangeServer
    • Get-ManagementRole
    • Get-ManagementRoleAssignment
  • If XenMobile Mail Manager is configured to view the entire forest, permission must have been granted to run: Set-AdServerSettings -ViewEntireForest $true
  • The supplied credentials must have been granted the right to connect to the Exchange Server via the remote Shell. By default, the user who installed Exchange has this right.
  • Per the Microsoft TechNet article, about_Remote_Requirements, to establish a remote connection and run remote commands, the credentials must correspond to a user who is an administrator on the remote machine. You can use Set-PSSessionConfiguration to eliminate the administrative requirement, but discussion of that command is beyond the scope of this document. For more information, see this blog post, You Don’t Have to Be An Administrator to Run Remote PowerShell Commands.
  • The Exchange Server must be configured to support remote PowerShell requests via HTTP. Typically, an administrator running the following PowerShell command on the Exchange Server is all that is required: WinRM QuickConfig.
  • Exchange has many throttling policies. One of the policies controls how many concurrent PowerShell connections are allowed per user. The default number of simultaneous connections allowed for a user is 18 on Exchange 2010. When the connection limit is reached, XenMobile Mail Manager is not able to connect to Exchange Server. There are ways to change the maximum allowed simultaneous connections via PowerShell that are beyond the scope of this documentation. If interested, investigate Exchange throttling policies as related to remote management with PowerShell.

Requirements for Office 365 Exchange

  • Permissions: The credentials specified in the Exchange Configuration UI must be able to connect to Office 365 and be given full access to execute the following Exchange-specific PowerShell cmdlets:
    • Get-CASMailbox
    • Set-CASMailbox
    • Get-Mailbox
    • Get-MobileDevice
    • Get-MobileDeviceStatistics
    • Clear-MobileDevice
    • Get-ExchangeServer
    • Get-ManagementRole
    • Get-ManagementRoleAssignment
  • Privileges: The supplied credentials must have been granted the right to connect to the Office 365 server via the remote Shell. By default, Office 365 online administrator has the requisite privileges.
  • Throttling policies: Exchange has many throttling policies. One of the policies controls how many concurrent PowerShell connections are allowed per user. The default number of simultaneous connections allowed for a user is three on Office 365. When the connection limit is reached, XenMobile Mail Manager is not able to connect to Exchange Server. There are ways to change the maximum allowed simultaneous connections via PowerShell that are beyond the scope of this documentation. If interested, investigate Exchange throttling policies as related to remote management with PowerShell.

Install and configure

  1. Click the XmmSetup.msi file and then follow the prompts in the installer to install XenMobile Mail Manager.

    Image of Mail Manager Setup screen

  2. Leave Launch the Configure utility selected in the last screen of the setup wizard. Or, from the Start menu, open XenMobile Mail Manager.

    Image of Mail Manager Setup screen

  3. Configure the following database properties:

    • Select the Configure > Database tab.
    • Enter the name of the SQL Server (defaults to localhost).
    • Keep the database as the default CitrixXmm.
  4. Select one of the following authentication modes used for SQL:

    • SQL: Enter the user name and password of a valid SQL user.
    • Windows Integrated: If you select this option, the logon credentials of the XenMobile Mail Manager Service must be changed to a Windows account that has permissions to access the SQL Server. To do this, open Control Panel > Administrative Tools > Services, right-click the XenMobile Mail Manager Service entry and then click the Log On tab.

    If Windows Integrated is also chosen for the BlackBerry database connection, the Windows account specified here must also be given access to the BlackBerry database.

  5. Click Test Connectivity to check that a connection can be made to the SQL Server and then click Save.

  6. A message prompts you to restart the service. Click Yes.

    Image of Mail Manager setup screen

  7. Configure one or more Exchange Servers:

    • If managing a single Exchange environment, specify a single server only. If managing multiple Exchange environments, specify a single Exchange Server for each Exchange environment.
    • Click the Configure > Exchange tab and then click Add.

    Image of Mail Manager setup screen

  8. Select the type of Exchange Server environment: On Premise or Office 365.

    Image of Mail Manager setup screen

    • If you select On Premise, enter the name of the Exchange Server to use for Remote PowerShell commands.
    • Enter the user name of a Windows identity that has appropriate rights on the Exchange Server as specified within the Requirements section and then enter the Password for the user.
    • Select the schedule for running Major snapshots. A major snapshot detects every Exchange ActiveSync partnership.
    • Select the schedule for running Minor snapshots. A minor snapshot detects newly created Exchange ActiveSync partnerships.
    • Select the Snapshot Type: Deep or Shallow. Shallow snapshots are typically much faster and are sufficient to perform all the Exchange ActiveSync Access Control functions of XenMobile Mail Manager. Deep snapshots may take longer and are only needed if the Mobile Service Provider is enabled for ActiveSync. This option allows XenMobile to query for unmanaged devices.
    • Select the Default Access: Allow, Block, or Unchanged. This setting controls how all devices other than those devices identified by explicit XenMobile or Local rules are treated. If you select Allow, ActiveSync access to all such devices is allowed. If you select Block, access is denied. If you select Unchanged, no change is made.
    • Select the ActiveSync Command Mode: PowerShell or Simulation.
    • In PowerShell mode, XenMobile Mail Manager issues PowerShell commands to enact the desired access control. In Simulation mode, XenMobile Mail Manager does not issue PowerShell commands, but logs the intended command and intended outcomes to the database. In Simulation mode, the user can then use the Monitor tab to see what would have happened if PowerShell mode was enabled.
    • In Connection Expiration, set the hours and minutes for the life of a connection. When a connection reaches the age specified, the connection is marked as expired, so that the connection is never used again. When the expired connection is no longer used, XenMobile Mail Manager gracefully shuts down the connection. When a connection is needed again, a new connection is initialized if none is available. If none is specified, the default of 30 minutes is used.
    • Select View Entire Forest to configure XenMobile Mail Manager to view the entire Active Directory forest in the Exchange environment.
    • Select the authentication protocol: Kerberos or Basic. XenMobile Mail Manager supports Basic authentication for on-premises deployments. This enables XenMobile Mail Manager to be used when the XenMobile Mail Manager server is not a member of the domain in which the Exchange server resides.
    • Click Test Connectivity to check that a connection can be made to the Exchange Server and then click Save.
    • A message prompts you to restart the service. Click Yes.
  9. Configure the access rules: Select the Configure > Access Rules tab, click the XMS Rules tab, and then click Add.

    Image of Mail Manager Console

  10. On the XenMobile Server Service Properties page, modify the URL string to point to the XenMobile Server. For example, if the instance name is zdm, enter http://<XdmHostName>/zdm/services/MagConfigService. In the example, replace XdmHostName with the IP or DNS address of the XenMobile Server.

    Image of Mail Manager Console

    • Enter an authorized user of the server.
    • Enter the password of the user.
    • Keep the default values for the Baseline Interval, Delta Interval, and Timeout values.
    • Click Test Connectivity to check the connection to the server and then click OK.

    If the Disabled check box is selected, the XenMobile Mail Service doesn’t collect policies from XenMobile.

  11. Click the Local Rules tab.

    Image of Mail Manager Console

    • You can add local rules based on ActiveSync Device ID, Device Type, AD Group, User, or device UserAgent. In the list, select the appropriate type.
    • Enter text or text fragments in the text box. Optionally, click the query button to view the entities that match the fragment.

    For all types other than Group, the system relies on the devices that have been found in a snapshot. Therefore, if you are just starting and haven’t completed a snapshot, no entities are available.

    • Select a text value and then click Allow or Deny to add it to the Rule List pane on the right side. You can change the order of rules or remove them using the buttons to the right of the Rule List pane. The order is important because, for a given user and device, rules are evaluated in the order shown and a match on a higher rule (nearer the top) causes subsequent rules to have no effect. For example, if you have a rule allowing all iPad devices and a subsequent rule blocking the user Matt, Matt’s iPad will still be allowed because the iPad rule has a higher effective priority than the Matt rule.
    • To perform an analysis of the rules within the rules list to find any potential overrides, conflicts, or supplemental constructs, click Analyze and then click Save.
  12. If you want to construct local rules that operate on Active Directory Groups, click Configure LDAP and then configure the LDAP connection properties.

    Image of Mail Manager Console

  13. Configure the Mobile Service Provider.

    The Mobile Service Provider is optional. That setting is necessary only if XenMobile is also configured to use the Mobile Service Provider interface to query unmanaged devices.

    • Click the Configure > MSP tab.

    Image of Mail Manager Console

    • Set the Service Transport type as HTTP or HTTPS for the Mobile Service Provider service.
    • Set the Service port (typically 80 or 443) for the Mobile Service Provider service. If you use port 443, the port requires an SSL certificate bound to it in IIS.
    • Set the Authorization Group or User. This sets the user or set of users who will be able to connect to the Mobile Service Provider service from XenMobile.
    • Set whether ActiveSync queries are enabled or not. If ActiveSync queries are enabled for the XenMobile Server, the Snapshot type for one or more Exchange Servers must be set to Deep. That setting might have significant performance costs for taking snapshots.
    • By default, ActiveSync devices that match the regular expression Secure Mail.* will not be sent to XenMobile. To change this behavior, alter the Filter ActiveSync field as necessary. Blank means that all devices are forwarded to XenMobile.
    • Click Save.
  14. Optionally, configure one or more instances of BlackBerry Enterprise Server (BES): Click Add and then enter the server name of the BES SQL Server

    Image of Mail Manager Console

    • Enter the database name of the BES management database.
    • Select the Authentication mode. If you select Windows Integrated authentication, the user account of the XenMobile Mail Manager service is the account that is used to connect to the BES SQL Server. If you also choose Windows Integrated for the XenMobile Mail Manager database connection, the Windows account specified here must also be given access to the XenMobile Mail Manager database.
    • If you select SQL authentication, enter the user name and password.
    • Set the Sync Schedule. This is the schedule used to connect to the BES SQL Server and checks for any device updates.
    • Click Test Connectivity to check connectivity to the SQL Server. If you select Windows Integrated, this test uses the current logged on user and not the XenMobile Mail Manager service user and therefore does not accurately test SQL authentication.
    • To support remote Wipe and ResetPassword of BlackBerry devices from XenMobile, select the Enabled check box.
    • Enter the BES fully qualified domain name (FQDN).
    • Enter the BES port used for the admin web service.
    • Enter the fully qualified user and password required by the BES service.
    • Click Test Connectivity to test the connection to the BES.
    • Click Save.

Enforce email policies with ActiveSync IDs

Your corporate email policy may dictate that certain devices are not approved for corporate email use. To comply with this policy, you want to ensure that employees cannot access corporate email from such devices. XenMobile Mail Manager and XenMobile work together to enforce such an email policy. XenMobile sets the policy for corporate email access and, when an unapproved device enrolls with XenMobile, XenMobile Mail Manager enforces the policy.

The email client on a device advertises itself to Exchange Server (or Office 365) using the device ID, also known as the ActiveSync ID, which is used to identify the device. Secure Hub obtains a similar identifier and sends the identifier to XenMobile when the device is enrolled. By comparing the two device IDs, XenMobile Mail Manager can determine whether a specific device should have corporate email access. The following figure illustrates this concept:

Diagram of Detect ActiveSync ID workflow

If XenMobile sends XenMobile Mail Manager an ActiveSync ID that is different from the ID the device publishes to Exchange, XenMobile Mail Manager cannot indicate to Exchange what to do with the device.

Matching ActiveSync IDs works reliably on most platforms. However, Citrix has found that on some Android implementations, the ActiveSync ID from the device is different from the ID that the mail client advertises to Exchange. To mitigate this problem, you can do the following:

  • On the Samsung SAFE platform, push the device ActiveSync configuration from XenMobile.
  • On all other Android platforms, push both the TouchDown app and the TouchDown ActiveSync configuration from XenMobile.

This does not, however, prevent an employee from installing an email client other than TouchDown on an Android device. To guarantee that your corporate email access policy is enforced properly, you can adopt a defensive security stance and configure XenMobile Mail Manager to block emails by setting the static policy to Deny by default. This means that if an employee does configure an email client on an Android device other than TouchDown, and if ActiveSync ID detection does not work properly, the employee is denied corporate email access.

Access control rules

XenMobile Mail Manager provides a rule-based approach for dynamically configuring access control for Exchange ActiveSync devices. A XenMobile Mail Manager access control rule consists of two parts: a matching expression and a desired access state (Allow or Block). A rule may be evaluated against a given Exchange ActiveSync device to determine if the rule applies to, or matches the device. There are multiple kinds of matching expressions; for example, a rule may match all devices of a given Device Type, or a specific Exchange ActiveSync device ID, or all devices of a specific user, and so on.

At any point during the adding, removing, and rearranging of the rules in the rule list, clicking the Cancel button reverts the rules list back to the state at which it was when first opened. Unless you click Save, any changes made to this window are lost if you close the Configure tool.

XenMobile Mail Manager has three types of rules: local rules, XenMobile Server rules (also known as XDM rules), and the default access rule.

Local rules: Local rules have the highest priority: If a device is matched by a local rule, rule evaluation stops. Neither XenMobile Server rules nor the default access rule will be consulted. Local rules are configured locally to XenMobile Mail Manager via the Configure > Access Rules > Local Rules tab. Support matching is based upon a user’s membership within a given Active Directory group. Support matching is based on regular expressions for the following fields:

  • Active Sync Device ID
  • ActiveSync Device Type
  • User Principal Name (UPN)
  • ActiveSync User Agent (typically the device platform or email client)

As long as a major snapshot has completed and found devices, you should be able to add either a normal or regular expression rule. If a major snapshot has not completed, you can only add regular expression rules.

XenMobile Server rules: XenMobile Server rules are references to an external XenMobile Server that provides rules about managed devices. The XenMobile Server can be configured with its own high-level rules that identify the devices to be allowed or blocked based on properties known to XenMobile, such as whether the device is jailbroken or whether the device contains forbidden apps. XenMobile evaluates the high-level rules and produces a set of allowed or blocked ActiveSync Device IDs, which are then delivered to XenMobile Mail Manager.

Default access rule: The default access rule is unique in that it can potentially match every device and is always evaluated last. This rule is the catch-all rule, which means that if a given device does not match a local or XenMobile server rule, the desired access state of the device is determined by the desired access state of the default access rule.

  • Default Access – Allow: Any device that is not matched by either a local or XenMobile server rule will be allowed.
  • Default Access – Block: Any device that is not matched by either a local or XenMobile server rule will be blocked.
  • Default Access - Unchanged: Any device that is not matched by either a local or XenMobile server rule will not have its access state modified in any way by XenMobile Mail Manager. If a device has been placed into Quarantine mode by Exchange, no action is taken; for example, the only way to remove a device from Quarantine mode is to have an explicitly Local or XDM rule override the quarantine.

About Rule Evaluations

For each device that Exchange reports to XenMobile Mail Manager, the rules are evaluated in sequence, from highest to lowest priority as follows:

  • Local rules
  • XenMobile Server rules
  • Default access rule

When a match is found, evaluation stops. For example, if a local rule matches a given device, the device will not be evaluated against any of the XenMobile Server rules or the default access rule. This holds true within a given rule type as well. For example, if there’s more than a single match for a given device in the local rule list, when the first match is encountered, evaluation stops.

XenMobile Mail Manager reevaluates the currently defined set of rules when device properties change, or when devices are added or removed, or when the rules themselves change. Major snapshots pick up device property changes and removals at configurable intervals. Minor Snapshots pick up new devices at configurable intervals.

Exchange ActiveSync has rules governing access as well. It is important to understand how these rules work in the context of XenMobile Mail Manager. Exchange may be configured with three levels of rules: personal exemptions, device rules, and organization settings. XenMobile Mail Manager automates access control by programmatically issuing Remote PowerShell requests to affect the personal exemptions lists. These are lists of allowed or blocked Exchange ActiveSync device IDs associated with a given mailbox. When deployed, XenMobile Mail Manager effectively takes over management of the exemption lists capability within Exchange. For details, see this Microsoft article.

Analyzing is particularly useful in situations in which multiple rules for the same field have been defined. You can troubleshoot the relationships between rules. You perform analysis from the perspective of rule fields; for example, rules are analyzed in groups based on the field that is being matched, such as ActiveSync device ID, ActiveSync device type, User, User Agent, and so on.

Rule terminology

  • Overriding rule: An override occurs when more than a single rule could apply to the same device. Because rules are evaluated by priority in the list, the later rule instance(s) which might apply might never be evaluated.
  • Conflicting rule: A conflict occurs when more than a single rule could apply to the same device but the access (Allow/Block) does not match. If the conflicting rules are not regular expression rules, a conflict always implicitly connotes an override
  • Supplemental rule: A supplement occurs when more than one rule is a regular expression rule and hence there might be a need to ensure that the two (or more) regular expressions can either be combined into a single regular expression rule, or are not duplicating functionality. A supplementary rule may also conflict in its access (Allow/Block).
  • Primary rule: The primary rule is the rule that has been clicked within the dialog box. The rule is indicated visually by a solid border line that surrounds it. The rule will also have one or two green arrows pointing up or down. If an arrow points up, the arrow indicates that there are ancillary rules that precede the primary rule. If an arrow points down, this indicates that there are ancillary rules that come after the primary rule. Only a single primary rule can be active at any time.
  • Ancillary rule: An ancillary rule is related in some way to the primary rule either through override, conflict, or a supplementary relationship. The rules are indicated visually by a dashed border that surrounds them. For each primary rule, there can be one to many ancillary rules. When clicking on any underlined entry, the ancillary rule or rules that are highlighted are always from the perspective of the primary rule. For example, the ancillary rule is overridden by the primary rule, and/or the ancillary rule will conflict in its access with the primary rule, and/or the ancillary rule will supplement the primary rule.

How types of rules appear in the Rule Analysis dialog box

When there are no conflicts, overrides, or supplements, the Rule Analysis dialog box has no underlined entries. Clicking any of the items has no impact; for example, normal selected item visuals occur.

The Rule Analysis window has a check box which, when selected, displays only those rules which are conflicts, overrides, redundancies, or supplements.

Image of Mail Manager Console

When an override occurs, at least two rules will be underlined: the primary rule and the ancillary rule or rules. At least one ancillary rule appears in a lighter font to indicate that the rule has been overridden by a higher priority rule. You can click the overridden rule to find out which rule or rules have overridden the rule. Any time an overridden rule has been highlighted either as a result of the rule being the primary or ancillary rule, a black circle appears next to it as a further visual indication that the rule is inactive. For example, before clicking the rule, the dialog box appears as follows:

Image of Mail Manager Console

When you click the highest-priority rule, the dialog box appears as follows:

Image of Mail Manager Console

In this example, the regular expression rule WorkMail.* is the primary rule (indicated by the solid border) and the normal rule workmailc633313818 is an ancillary rule (indicated by the dashed border). The black dot next to the ancillary rule is a visual cue that further indicates that the rule is inactive (will never be evaluated) due to the higher-priority regular expression rule that precedes it. After clicking the overridden rule, the dialog box appears as follows:

Image of Mail Manager Console

In the preceding example, the regular expression rule WorkMail.* is the ancillary rule (indicated by the dashed border) and the normal rule workmailc633313818 is a primary rule (indicated by the solid border). For this simple example, there’s not much difference. For a more complicated example, see the complex expression example later in this topic. In a scenario with many rules defined, clicking the overridden rule would quickly identify which rule or rules had overridden it.

When a conflict occurs, at least two rules will be underlined, the primary rule and the ancillary rule or rules. The rules in conflict are indicated by a red dot. Rules that only conflict with one another are only possible with two or more regular expression rules defined. In all other conflict scenarios, there will not only be a conflict, but an override at play. Prior to clicking either of the rules in a simple example, the dialog box appears as follows:

Image of Mail Manager Console

By inspecting the two regular expression rules, it’s evident that the first rule allows all devices with a device ID that contains “App” and that the second rule denies all devices with a device ID that contains “Appl”. In addition, even though the second rule denies all devices with a device ID that contains “Appl”, no devices with that match criteria will ever be denied because of the higher precedence of the allow rule. After clicking the first rule, the dialog box appears as follows:

Image of Mail Manager Console

In the preceding scenario, both the primary rule (regular expression rule App.*) and the ancillary rule (regular expression rule Appl.*) are both highlighted in yellow. This is simply a visual warning to alert you to the fact that you have applied more than a single regular expression rule to a single matchable field, which could mean a redundancy issue or something more serious.

In a scenario with both a conflict and override, both the primary rule (regular expression rule App.*) and the ancillary rule (regular expression rule Appl.*) are highlighted in yellow. This is simply a visual warning to alert you to the fact that you have applied more than a single regular expression rule to a single matchable field, which could mean a redundancy issue or something more serious.

Image of Mail Manager Console

It is easy to see in the preceding example that the first rule (regular expression rule SAMSUNG.*) not only overrides the next rule (normal rule SAMSUNG-SM-G900A/101.40402), but that the two rules differ in their access (primary specifies Allow, ancillary specifies Block). The second rule (normal rule SAMSUNG-SM-G900A/101.40402) is displayed in lighter text to indicate that it has been overridden and is therefore inactive.

After clicking the regular expression rule, the dialog box appears as follows:

Image of Mail Manager Console

The primary rule (regular expression rule SAMSUNG.*) is followed by a red dot to indicate that its access state conflicts with one or more ancillary rules. The ancillary rule (normal rule SAMSUNG-SM-G900A/101.40402) is followed by a red dot to indicate that its access state conflicts with the primary rule. That rule is also followed by a black dot to indicate that it is overridden and therefore inactive.

At least two rules will be underlined, the primary rule and the ancillary rule or rules. Rules that only supplement one another will only involve regular expression rules. When rules supplement one another, they are indicated with a yellow overlay. Prior to clicking either of the rules, in a simple example, the dialog box appears as follows:

Image of Mail Manager Console

Visual inspection easily reveals that both rules are regular expression rules which have both been applied to the ActiveSync device ID field in XenMobile Mail Manager. After clicking the first rule, the dialog box looks as follows:

Image of Mail Manager Console

The primary rule (regular expression rule WorkMail.*) is highlighted with a yellow overlay to indicate that there exists at least one more ancillary rule which is a regular expression. The ancillary rule (regular expression rule SAMSUNG.*) is highlighted with a yellow overlay to indicate that both it and the primary rule are regular expression rules being applied to the same field within XenMobile Mail Manager. In this case, that field is the ActiveSync device ID. The regular expressions may or may not overlap. It is up to you to decide if your regular expressions are properly crafted.

Example of a complex expression

Many potential overrides, conflicts, or supplements can occur, making it impossible to give an example of all possible scenarios. The following example discusses what not to do, while also serving to illustrate the full power of the rule analysis visual construct. Most of the items are underlined in the following figure. Many of the items render in a lighter font, which indicates that the rule in question has been overridden by a higher priority rule in some manner. A number of regular expression rules are included in the list as well, as indicated by the Image of icon icon.

Image of Mail Manager Console

How to Analyze an Override

To see which rule or rules have overridden a particular rule, you click the rule.

Example 1: This example examines why zentrain01@zenprise.com has been overridden.

Image of Mail Manager Console

The primary rule (AD-Group rule zenprise/TRAINING/ZenTraining B, of which zentrain01@zenprise.com is a member) has the following characteristics:

  • Is highlighted in blue and has a solid border.
  • Has an upwards pointing green arrow (to indicate that the ancillary rule or rules are all to be found above it).
  • Is followed by both a red circle and black circle to indicate respectively that one or more ancillary rule conflicts with its access and that the primary rule has been overridden and is hence inactive.

When you scroll up, you see the following:

Image of Mail Manager Console

In this case, there are two ancillary rules that override the primary rule: the regular expression rule zen.* and the normal rule zentrain01@zenprise.com (of zenprise/TRAINING/ZenTraining A). In the case of the latter ancillary rule, what has occurred is that the Active Directory Group rule ZenTraining A contains the user zentrain01@zenprise.com, and the Active Directory Group rule ZenTraining B also contains the user zentrain01@zenprise.com. Because the ancillary rule has a higher precedence than the primary rule, however, the primary rule has been overridden. The primary rule’s access is Allow, and because both of the ancillary rule’s access is Block, all are followed with a red circle to further indicate an access conflict.

Example 2: This example shows why the device with an ActiveSync device ID of 069026593E0C4AEAB8DE7DD589ACED33 has been overridden:

Image of Mail Manager Console

The primary rule (normal device ID rule 069026593E0C4AEAB8DE7DD589ACED33) has the following characteristics:

  • Is highlighted in blue and has a solid border.
  • Has an upwards pointing green arrow (to indicate that the ancillary rule is to be found above it).
  • Is followed by a black circle to indicate an ancillary rule has overridden the primary rule and is hence inactive.

Image of Mail Manager Console

In this case, a single ancillary rule overrides the primary rule: The regular expression ActiveSync device ID rule is 3E.* Because the regular expression 3E.* would match 069026593E0C4AEAB8DE7DD589ACED33, the primary rule will never be evaluated.

How to analyze a supplement and conflict

In this case, the primary rule is the regular expression ActiveSync device type rule touch.* The characteristics are as follows:

  • Is indicated by a solid border with a yellow overlay as a warning that there is more than a single regular expression rule operating against a particular rule field, in this case ActiveSync device type.
  • Two arrows are pointing up and down respectively, indicating that there is at least one ancillary rule with higher priority and at least one ancillary rule with lower priority.
  • The red circle next to it indicates that at least one ancillary rule has its access set to Allow which conflicts with the primary rule’s access of Block
  • There are two ancillary rules: the regular expression ActiveSync device type rule SAM.* and the regular expression ActiveSync device type rule Andro.*.
  • Both of the ancillary rules are bordered with dashes to indicate that they are ancillary.
  • Both of the ancillary rules are overlaid with yellow to indicate that they are also applied to the rule field of ActiveSync device type.
  • You should ensure in such scenarios that their regular expression rules are not redundant.

Image of Mail Manager Console

How to further analyze the rules

This example explores how rule relationships are always from the perspective of the primary rule. The preceding example showed how a click the regular expression rule applied to the rule field of device type with a value of touch.*. Clicking the ancillary rule Andro.* shows a different set of ancillary rules highlighted.

Image of Mail Manager Console

The example shows an overridden rule that is included in the rule relationship. This rule is the normal ActiveSync device type rule Android, which is overridden (indicated by the lightened font and the black circle next to it) and also conflicts in its access with the primary rule regular expression ActiveSync device type rule Andro.*. That rule was formerly an ancillary rule prior to being clicked. In the preceding example, the normal ActiveSync device type rule Android, was not displayed as an ancillary rule because, from the perspective of the then primary rule (the regular expression ActiveSync device type rule touch.*), it was not related to it.

To configure a normal expression local rule

  1. Click the Access Rules tab.

    Image of Mail Manager Console

  2. In the Device ID list, select the field for which you want to create a Local Rule.

  3. Click the magnifying glass icon to display all of the unique matches for the chosen field. In this example, the field Device Type has been chosen and the choices are shown below in the list box.

    Image of Mail Manager Console

  4. Click one of the items in the results list box and then click one of the following options:

    • Allow means that Exchange will be configured to allow ActiveSync traffic for all matching devices.
    • Deny means that Exchange will be configured to deny ActiveSync traffic for all matching devices.

    In this example, all devices that have a device type of TouchDown are denied access.

    Image of Mail Manager Console

To add a regular expression

Regular expression local rules can be distinguished by the icon which appears next to them - Image of icon. To add a regular expression rule, you can either build a regular expression rule from an existing value from the results list for a given field (as long as a major snapshot has completed), or you can simply type in the regular expression that you want.

To build a regular expression from an existing field value

  1. Click the Access Rules tab.

    Image of Mail Manager Console

  2. In the Device ID list, select the field for which you want to create a regular expression Local Rule.

  3. Click the magnifying glass icon to display all of the unique matches for the chosen field. In this example, the field Device Type has been chosen and the choices are shown below in the list box.

    Image of Mail Manager Console

  4. Click one of the items in the results list. In this example, SAMSUNGSPHL720 has been selected and appears in the text box adjacent to Device Type.

    Image of Mail Manager Console

  5. To allow all device types that have “Samsung” in their device type value, add a regular expression rule by following these steps:

    1. Click within the selected item text box.

    2. Change the text from SAMSUNGSPHL720 to SAMSUNG.*.

    3. Ensure that the regular expression check box is selected.

    4. Click Allow.

    Image of Mail Manager Console

To build an access rule

  1. Click the Local Rules tab.
  2. To enter the regular expression, you need to make use of both the Device ID list and the selected item text box.

    Image of Mail Manager Console

  3. Select the field you want to match against. This example uses Device Type.
  4. Type in the regular expression. This example uses samsung.*
  5. Ensure that the regular expression check box is selected and then click Allow or Deny. In this example, the choice is Allow. The final result is as follows:

    Image of Mail Manager Console

To find devices

By selecting the regular expression check box, you can run searches for specific devices that match the given expression. This feature is only available if a major snapshot has successfully completed. You can use this feature even if there is no plan to use regular expression rules. For example, assume that you want to find all devices that have the text “workmail” in their ActiveSync device ID. To do so, follow this procedure.

  1. Click the Access Rules tab.
  2. Ensure that the device match field selector is set to Device ID (the default).

    Image of Mail Manager Console

  3. Click within the selected item text box (as shown in blue in the preceding figure) and then type workmail.*.
  4. Ensure the regular expression check box is selected and then click the magnifying glass icon to display matches as shown in the following figure.

    Image of Mail Manager Console

To add an individual user, device, or device type to a static rule

You can add static rules based on user, device ID, or device type on the ActiveSync Devices tab.

  1. Click the ActiveSync Devices tab.

  2. In the list, right-click a user, device, or device type and select whether to allow or deny your selection.

    The following image shows the Allow/Deny option when user1 is selected.

    Image of Mail Manager Console

Device monitoring

The Monitor tab in XenMobile Mail Manager lets you browse the Exchange ActiveSync and BlackBerry devices that have been detected and the history of automated PowerShell commands that have been issued. The Monitor tab has the following three tabs:

  • ActiveSync Devices:
    • You can export the displayed ActiveSync device partnerships by clicking the Export button.
    • You can add Local (static) rules by right-clicking the User, Device ID, or Type columns and selecting the appropriate allow or block rule type.
    • To collapse an expanded row, Ctrl-click the expanded row.
  • Blackberry Devices
  • Automation History

The Configure tab shows the history of all snapshots. Snapshot history shows when the snapshot took place, how long it took, how many devices were detected and any errors that occurred:

  • On the Exchange tab, click the Info icon for the desired Exchange Server.
  • Under the MSP tab, click the Info icon for the desired BlackBerry Server.

Troubleshooting and diagnostics

XenMobile Mail Manager logs errors and other operational information to its log file: Install Folder\log\XmmWindowsService.log. XenMobile Mail Manager also logs significant events to the Windows Event Log.

Common errors

The following list includes common errors:

  • XenMobile Mail Manager service doesn’t start

    Check the log file and the Windows Event Log for errors. Typical causes are as follows:

    • The XenMobile Mail Manager service cannot access the SQL Server. This may be caused by these issues:

      • The SQL Server service is not running.
      • Authentication failure.

      If Windows Integrated authentication is configured, the user account of the XenMobile Mail Manager service must be an allowed SQL logon. The account of the XenMobile Mail Manager service defaults to Local System, but may be changed to any account that has local administrator privileges. If SQL authentication is configured, the SQL logon must be properly configured in SQL.

    • The port configured for the Mobile Service Provider (MSP) is not available. A listening port must be selected that is not used by another process on the system.

  • XenMobile cannot connect to the MSP

    Check that the MSP service port and transport is properly configured in the Configure > MSP tab of the XenMobile Mail Manager console. Check that the Authorization Group or User is set properly.

    If HTTPS is configured, a valid SSL server certificate must be installed. If IIS is installed, IIS Manager can be used to install the certificate. If IIS is not installed, see http://msdn.microsoft.com/en-us/library/ms733791.aspx for details on installing certificates.

    XenMobile Mail Manager contains a utility program to test connectivity to the MSP service. Run the InstallFolder\MspTestServiceClient.exe program and set the URL and credentials to a URL and credentials that will be configured in the XenMobile and then click Test Connectivity. This simulates the web service requests that XenMobile Service issues. Note that if HTTPS is configured, you must specify the actual host name of the server (the name specified in the SSL certificate).

    When using Test Connectivity, be sure to have at least one ActiveSyncDevice record or the test may fail.

    Image of Mail Manager Console

Troubleshooting Tools

A set of PowerShell utilities for troubleshooting is available in the Support\PowerShell folder.

A troubleshooting tool performs in-depth analysis of user mailboxes and devices, detecting error conditions and potential areas of failure, and in-depth RBAC analysis of users. It can save raw output of all cmdlets to a text file.