Product Documentation

Push Notifications for WorxMail for iOS

Sep 01, 2016

WorxMail for iOS can receive notifications about email and calendar activity when the app is running in the background or is closed. WorxMail supports notifications provided through the iOS background app refresh functionality or push notifications provided through the Apple Push Notification service (APNs).

By default, WorxMail uses the background app refresh method, which does not require any configuration yet can have significant delays in syncing. To provide users with real-time push notifications when WorxMail is in the background, configure WorxMail as described in this article.

How Push Notifications Work

WorxMail sends push notifications for the following Inbox activities:

  • New mail, meeting requests, meeting cancellations, meeting updates. 

    When APNs pushes notifications to an inbox, WorxMail updates all folders, including Calendar, so that meeting changes are reflected immediately in users’ calendars.
  • Mail status changes from read to unread and vice versa.

    WorxMail icon with unread email count


    The WorxMail icon shows the total count of unread and new messages in the Exchange Inbox folder only. WorxMail updates the icon after users read emails on a desktop or laptop computer.

    The WorxMail drawer still provides the count of unread Inbox emails in Worx for the sync period. If the Control locked screen notifications policy is On, push notifications appear on a locked device screen after iOS wakes up WorxMail to perform a sync.

During an installation or upgrade, WorxMail prompts users to allow push notifications. Users can also allow push notifications later by using iOS Settings.

To provide push notifications, Citrix hosts a listener service on Amazon Web Services (AWS) to perform the following functions:

  • Listen for Exchange Web Services (EWS) push notifications sent by Exchange Servers when there is Inbox activity. Exchange does not send any mail content to the Citrix service.

    No personally identifiable information is stored by the Citrix service. Instead, a device token and subscription ID identifies the specific device and Inbox folder to be updated within WorxMail.

  • Send APNs notifications, containing only badge counts, to WorxMail on iOS devices.

The Citrix listener service does not impact mail data traffic, which continues to flow between user devices and Exchange Servers through ActiveSync. The listener service, which is configured for high availability and disaster recovery, is available in three regions: Americas, Europe, Middle East and Africa (EMEA), and Asia Pacific (APAC).

For details about the EWS push notification service, see the Microsoft article Notification subscriptions, mailbox events, and EWS in Exchange.

System Requirements for Push Notifications

Note: Push notifications are not currently supported for IBM Notes.

Exchange Server configuration:

  • Allow outbound SSL (over port 443) from your firewall to the Citrix listener service URL for the region where your Exchange Server is located. For example:

  • Region URL IP Address
    Americas us-east-1.pushreg.xm.citrix.com:443 52.6.252.176
    52.4.180.132
    EMEA eu-west-1.pushreg.xm.citrix.com:443 54.77.174.172
    52.17.147.220
    APAC ap-southeast-1.pushreg.xm.citrix.com:443 54.169.87.20
    52.74.231.240

  • If you have a proxy server between EWS and the Citrix listener device, you can either send EWS traffic through the proxy and then on to the listener device, or you can bypass the proxy and route EWS traffic to the listener device directly.

    To send EWS traffic through the proxy server: Configure the EWS web.config file in the ClientAccess\exchweb\ews folder, as follows:

    <configuration>
      <system.net>
        <defaultProxy>
          <proxy usesystemdefault="false"
            proxyaddress="http://proxy.example:8080"
            bypassonlocal="true” />
        </defaultProxy>
      </system.net>
    </configuration>

    To bypass the proxy server: Configure the bypass list to allow Exchange to make connections to the Citrix listener service. For details, see "Push Event Notifications" in https://msdn.microsoft.com/en-us/library/office/aa579128(v=exchg.140).aspx.

  • If your Exchange Server is configured for client certificate authentication, set theuploadReadAheadSize property in Internet Information Server (IIS) for both the EWS site and ActiveSync site. For example, for a 10 MB attachment limit, change the value to 10485760 (1024 * 1024); for a 20 MB attachment limit, change the value to 20971520.

    For details, see the blog post http://www.butsch.ch/post/Exchange-20XX-Client-Certificate-und-IIS-ActiveSync-uploadReadAheadSize.aspx. Be aware that the serverRuntime element in IIS 7.0 replaced some IIS 6.0 metabase properties, including UploadReadAheadSize. For details, see Server Runtime in the IIS reference.

NetScaler Gateway configuration:

  • If your EWS and ActiveSync servers are different, configure your NetScaler traffic policy to allow EWS traffic.
  • If your NetScaler Gateway configuration includes Secure Ticket Authority (STA) and split tunneling is off, NetScaler Gateway must allow traffic from WorxMail to the following Citrix listener service URLs:
  • Region URL IP Address
    Americas https://us-east-1.pushreg.xm.citrix.com 52.7.65.6
    52.7.147.0
    EMEA https://eu-west-1.pushreg.xm.citrix.com 54.154.200.233
    54.154.204.192
    APAC https://ap-southeast-1.pushreg.xm.citrix.com 52.74.236.173
    52.74.25.245

Provisioning profiles and app IDs:

  • APNs requires a provisioning profile created with an explicit and unique app ID. APNs does not support apps that use a provisioning profile created with a wildcard (*) app ID.

XenMobile Management Tools for APNs signature signing is compatible with these browsers:

  • Chrome (minimum version 36)
  • Firefox (minimum version 31)
  • Internet Explorer 10 or 9
  • Safari (minimum version 7)

Upgrading WorxMail

Be aware that the type of app ID previously used for WorxMail affects whether users can upgrade WorxMail or must reinstall the app, as shown in the following table.

App ID on deployed version of WorxMail Upgrades from WorxMail 10.0.x to 10.0.7 are supported? Required user action
Explicit app ID, with a provisioning profile created with an explicit app ID Yes Users can upgrade to WorxMail 10.0.7.
Wildcard app ID, with a provisioning profile created with a wildcard app ID No

APNs does not support wildcard IDs, so you must use a new explicit app ID.

Users must perform a fresh install of WorxMail 10.0.7.

Configuring WorxMail for Push Notifications

Follow these steps to configure WorxMail for push notifications:

  1. Verify that your environment meets the system requirements, described earlier in System Requirements for Push Notifications.
  2. If your deployed version of WorxMail was wrapped with an explicit app ID with its own distribution profile, enable the Push Notifications service for the app ID. For details, see Registering App IDs in the Apple App Distribution Guide.
  3. If your deployed version of WorxMail was wrapped with a wildcard app ID or this is a new deployment, you must use a new app ID and provisioning profile when wrapping the new version of WorxMail. From the Apple Enterprise Developer portal, create a new provisioning profile and a unique, explicit app ID.
    • You must register an explicit WorxMail app ID, use the explicit distribution profile for that app ID, and enable the Push Notifications service for the app ID. For details, see Registering App IDs in the Apple App Distribution Guide.
    • If you have staging and production environments, you will need separate app IDs and certificates for each environment.
  4. Wrap WorxMail with the MDX Toolkit, using the explicit app ID prepared in Steps 2 or 3.
  5. Generate a WorxMail APNs certificate for the explicit WorxMail app ID. Be sure to choose the Production SSL certificate and not the Development SSL certificate.

    WorxMail requires an APNs certificate to support push notifications. This cannot be the same APNs certificate uploaded to the XenMobile server.

    To obtain and upload an APNs certificate:

    1. Request a new APNs certificate from Apple.
    2. Export, as a .p12 file, the certificate and private key using the Keychain Access feature on your Mac. For details on generating and exporting the APNs certificate from the Apple Developer portal, see Configuring Push Notifications in the Apple App Distribution Guide.
  6. Register your APNs certificate and obtain a customer ID.
    1. Use your Citrix Login ID to log in to the XenMobile Management Tools portal at https://xenmobiletools.citrix.com.
    2. Click Upload WorxMail APNs certificates.

       

      APNs certificate upload site

       

    3. Choose the region where your Exchange Server is located.

       

      APNs certificate upload region

       

    4. Specify your explicit WorxMail app ID, choose your APNs certificate (.p12 file), and enter your certificate password.

       

      APNs certificate upload details

       

    5. When the upload completes, your customer ID displays. You will need the customer ID to configure the Push notifications customer ID policy, described in Step 7.

       

      APNs certificate customer ID

       

      You can return to the Dashboard view to view details, obtain your customer ID, or delete certificates.

  7. When you add WorxMail to XenMobile, update the following policies to enable and configure push notifications.
    Push notifications
    Enables APNs-based notifications about Inbox activity. If On, WorxMail supports push notifications. Default value is Off.
    Push notifications region
    The region where the APNs host is located for your WorxMail users. Options are Americas, EMEA, and APAC. Default value is Americas. Select the same value you specified for Step 6c.
    Push notifications customer ID
    Your APNs customer ID, used to identify your account to the Citrix notification service. This is the customer ID that displayed in Step 6e.

Background Network Services

If you disable split tunneling on NetScaler Gateway, add a Citrix push registration server FQDN to this policy in order to enable WorxMail to sync properly. These values are appended to the values in the policy. The values are comma-separated with no spaces. Depending on the push notifications region selected, the server to be added is as follows:
 
Americas: https://us-east-1.pushreg.xm.citrix.com

EMEA: https://eu-west-1.pushreg.xm.citrix.com

APAC: https://ap-southeast-1.pushreg.xm.citrix.com

8. If your previously deployed WorxMail had a wildcard app ID, let your users know that they must reinstall WorxMail.

For more details about push notifications, see FAQ: WorxMail APNS for IT Admins. A Citrix customer login is required to view that content. Also see the blog post A Step-by-Step Guide to Configuring WorxMail APNS.

For details on how to update an expired certificate, please see Update Apple Push Services Certificate for WorxMail.

Troubleshooting Outbound Connections

To troubleshoot outbound connections, check the Exchange event logs, which include log entries when a subscription request or the notification for a subscription is invalid or fails. You can also run Wireshark traces on the Exchange Server to track outbound traffic to the Citrix listener service.