This article provides answers to frequently asked questions on WorxMail APNS for IT Admins.

Question and Answers

This article provides answers to frequently asked questions on WorxMail?? APNS for?? IT Admins.For more information on Push Notifications for WorxMail, refer to Citrix Documentation -?? Push Notifications for WorxMail for iOS.

General Overview

Q1: Why does WorxMail for iOS require APNS notifications?

A: In Avatar and previous releases, when WorxMail application is in the background, it relies on background app refresh functionality of the iOS platform to “wake up” the application to:

  1. Update the badge
  2. Show notifications (if turned on)
  3. Sync emails

The frequency?? algorithm to wake up the application is more or less depending on the app usage (the more frequent the app is in use the more frequent it checks for new mail while in background mode). Therefore, at times the badge or?? the?? mails?? will not sync for hours.
For customers who want near real time of badge update and a higher frequency of mail syncing, it is recommended to use WorxMail with Push Notifications.

Q2: Is APNS notification an optional feature in Beetlejuice for WorxMail for iOS?

A: Yes, it is an optional feature in BeetleJuice.?? It is turned off by default. The Admin will have to enable the feature (as an app specific policy in AppC/ XMS server). If the customer is ok with background app refresh approach when WorxMail is in background, then this feature does not?? need to be enabled.

Q3: How about push notifications for WorxMail for Android?

A: Android OS allows 3rd party applications to maintain server connections both in foreground and background mode. Hence, WorxMail for Android maintains a persistent ActiveSync connection to sync emails and sync is near real time.

Q4: Will APNS feature in WorxMail for iOS work with both XM 9 and XM 10 servers?

A: Yes

Q5: What are the supported upgrade paths?

A: The following table provides supported upgrade paths.

User-added image

Key points (to elaborate on the above table)

  • APNs support requires a unique App ID (Apple iOS requirement). Therefore, this solution will be supported for WorxMail wrapped with a Unique App ID. WorxMail that is using a provisioning profile created with a wildcard App ID is not supported for APNs.
  • It is not possible to upgrade a wildcard App ID wrapped WorxMail to a Unique App ID wrapped WorxMail on the users device. A re-install is required. So, for older customers wanting to leverage this push service, you will need to create a Unique App ID in the Apple Developers portal, a new provisioning profile, a new wrapped version of WorxMail then load this up to the server as a new app.

Q6: Will the APNs feature work with Office365?

A: Yes, O365 is supported in addition to Exchange 2007, 2010 and 2013.

Q7: Is the APNs feature available for Lotus Notes?

A: The Beetlejuice release (10.0.7) only supports Exchange. We will investigate on what web services are available for Lotus Notes. When the due diligence is completed, we will provide a status update.

Q8: Do I need to install any server components on-premise?

A: No. Citrix will host a “listener” service in the cloud. This service will send out push notifications to your user’s WorxMail application. Note that no personally identifiable information (PII) is stored or flows through this cloud service.

Q9: Why did you go with a cloud first approach for listener service?

A: Key reasons are:

  • Zero on-premise server footprint to support APNS notifications
    • No hardware/ software/ monitoring/ server scaling work effort for IT administrators
  • No change to mail data flow
    • Mail data traffic continues to flow between Device and Exchange Server
  • No sensitive data sent to listener service by Exchange server
    • APNS notification sends only the badge count to WorxMail application.

Q10: Why does the feature require a listener service? The Native Mail client does not need a listener service.

A: The native mail client on iOS maintains a persistent ActiveSync connection with the exchange server. Apple allows this only for the native mail client. 3rd party mail clients have to leverage APNs to send remote notifications.
In order to support APNs, a server component is required. The server component receives?? a trigger from the exchange server and then send an APNs notification to WorxMail application.

Q11: Where is the listener service hosted?

A: The listener service is hosted on Amazon Web Services (AWS).?? It is configured as an HA/DR service. The listener service will be available in three regions – Americas, EMEA, APAC. The IT admin will have to select the region that is closest to the Exchange Server.

Q12: What is the Citrix hosted listener service URL?

The listener service URLs and IP addresses are based on region:

- Americas:

Configuration?? and Setup

Q1: What does the customer IT admin need to do to enable APNs push notifications for WM?

A: The document by the Mobility Experts team provides step-by-step instructions and screenshots to set up APNs notifications: http://blogs.citrix.com/2015/06/11/mobility-experts-a-step-by-step-guide-to-configuring-worxmail-apns/.

Q2: Can I use the MDM server APNs certificate for my WorxMail App ID?

A: No. The MDM server APNs certificate is required to enable XDM/ XMS manage iOS devices. The WorxMail APNs certificate is required to support APNs push notifications for the WorxMail application.

Q3: How do I generate the APNs certificate for WorxMail?

A: The APNs certificate for WorxMail application is generated by IT admin using the Apple developer portal. This is the same portal used to register the app with Apple (with a specific app ID). When the APNs certificate is generated, the IT admin can upload that using the Xenmobiletools portal. For more information, refer to the step-by-step instructions from Apple on generating and exporting APNs certificates - Configuring Push Notifications.

Q4: How do I renew the APNs certificate for WorxMail when it expires?

A: A new APNs certificate should first be generated via the Apple developer portal and exported. You then go to xenmobiletools.citrix.com and update the certificate that has been previously uploaded for WorxMail. This is done by selecting the?? ‘Update’ action for the WorxMail app ID in the uploaded certificates list.??

Q5: The Exchange server is behind a firewall. Do I need to allow outbound connection to the Citrix hosted listener service?

A: Yes. Ensure outbound SSL connections are not blocked by the Firewall to the Citrix hosted service for your region:

- Americas:

Q6: The Exchange server has to bypass a web proxy to reach the Citrix Listener Service. What do I need to do to allow this?

  • On Exchange for EWS, make the following update to the XML in the web.config file in the ClientAccess\exchweb\ews folder:
 <configuration>   <system.net>     <defaultProxy>       <proxy usesystemdefault="false"         proxyaddress="http://proxy.ournetwork:8080"         bypassonlocal="true”  />     </defaultProxy>   </system.net> </configuration>

Q7: What are the configurations required when EWS and ActiveSync servers are different?

A: For WorxMail to be able to connect to the EWS server, the following configuration is required:

  1. Update the hidden policy for the EWS server FQDN in the WorxMail policy XML file:
    ?? ?? <key>PushNotificationsEWSHostName</key>
    ?? ?? ?? ?? ?? <string></string>

  2. If using STA for WorxMail, then you need to add the EWS FQDN to the background services policy just like the ActiveSync server FQDN.??
    Note: EWS usage from the WorxMail application is only during subscription of EWS push notifications.?? Mail data traffic will continue to flow via ActiveSync.

Q8: If I do not want to set my main EWS directory to use certificate based authentication, but Active Sync uses certificate based authentication, what are my options?

A: WorxMail requires that both Activesync and EWS use the same authentication method for SSO. If you want to enable EWS certificate based authentication or SSO only for WorxMail clients, the following configurations can be selected from:

?? ?? ?? 1. Using NetScaler KCD

  • Using the NetScaler AAA and KCD, the certificate can be used to authenticate at the NetScaler and then this is delegated to the Exchange CAS for authentication. See this post for more details on configuring WorxMail and KCD with NetScaler AAA - How to: Single Sign on to XenMobile WorxMail.
  • Note?? that with this approach, traffic to Exchange leverages SecureBrowse and not NetScaler STA. The impact of not using STA with WorxMail is shorter session timeouts - this will interrupt mail notifications and background sync with more frequent pin prompts. The timeouts do not impact APNs badging.

?? ?? ?? 2. New IIS Site on?? Exchange server with EWS Virtual Directory

  • Microsoft supports configuring a new EWS directory and ActiveSync directory in a separate IIS site on the Exchange server. This?? way, authentication methods can be set differently for EWS. Microsoft documentation for a new virtual directory in Exchange
  • As part of the site-creation process, you must bind an IP address to the site; each site should have a unique IP address.??
  • After you assign an IP address, create a DNS record that allows users to access the new website using a new domain name.
  • WorxMail can be configured to connect to this separate site while leaving all other clients to connect to the default site by specifying the FQDN of the new site in the WorxMail Exchange server policy. This way the Autodiscovery used by other clients will not be impacted by the new configuration and will still connect to the default site.

Q9: What are the configuration changes required when Split Tunneling is set to Off and STA is enabled?

A: NetScaler Gateway must allow traffic from WorxMail to the Citrix registration service URLs so that the initial registration of the WorxMail client to the NetScaler does not fail. You also need to?? add the registration service URL to the?? Background services MDX Policy?? for WorxMail to sync properly.

  • https://us-east-1.pushreg.xm.citrix.com
  • &
  • ?? https://eu-west-1.pushreg.xm.citrix.com
  • &
  • https://ap-southeast-1.pushreg.xm.citrix.com
  • &

Q10: What do I set the Upload Read Ahead Size to?

A: If the Exchange Server is configured for client certificate authentication, the uploadReadAheadSize parameter needs to be changed in IIS for both the EWS site and the ActiveSync site:

Q11: How can I verify that the Outbound connections are working and APNs is setup?

  • The outbound connection from Exchange to the listener service can be verified either via the Exchange event logs which will log events when a subscription request or notification for a subscription is invalid/fails. You can also run Wireshark traces on the Exchange server to track outbound traffic to the listener service.
  • There are?? two?? easy checks that can be carried out to know whether APNs is working or the app is still using local badging:
    • First, validate that the badge unread count is equal to what you see for your Outlook client on your laptop/desktop.
    • As a second check, send the app to the background for more than 5 minutes and then check if the badge is still updating.

Q12: I do not see the WorxMail updated APNs policies to configurethe settings.

A: This is available in the Beetlejuice wrapper. Ensure that with the Beetlejuice upgrade, you are also using the latest version of the MDX toolkit.

Q13: Can I change the APNs policy from OFF to ON or ON to OFF?

A: This can be changed by the Admin from ‘OFF’ to ‘ON’. The next time WorxMail checks in with the server to get the latest policies, the badge will begin to update. The scenario of going from ‘ON’ to ‘OFF’ is not supported. If turned OFF, the badge will continue to update.

Q14: Where do I upload the APNs certificate?

A: The listener service will require your WorxMail’s APNs certificate to push notifications to your end users.?? The APNs certificate is uploaded via https://xenmobiletools.citrix.com. You will need your citrite id to get access to the portal.?? Ensure to select the 2nd option on the screen: “Upload WorxMail APNs certificates”.

Q15: Can I upload the same certificate and app ID for multiple regions?

A: Yes, the same certificate and app ID can be uploaded for multiple regions. However, you can only have?? one entry per region. To upload for multiple regions, each region will need to be registered under a different citrite ID.

Information/Data Flow

Q1: After the admin enables APNs push, what is the end to end flow?

A: The end -to -end flow is as follows:

  1. User launches APNs enabled WorxMail application on their device.
  2. User is prompted by the iOS platform to allow Notifications. User clicks on “Allow”.
  3. The iOS platform obtains the device token from the Apple Push Notification service (on behalf of the WorxMail application).
  4. WorxMail registers with the Citrix hosted listener service.
  5. WorxMail makes an EWS call to subscribe to EWS push notifications for the inbox folder. Upon success, the Exchange server sends the subscription id to WorxMail.
  6. WorxMail updates the Citrix hosted listener service with the subscription id.
  1. When there is mailbox activity, the Exchange server will send an EWS push notification to the listener service.
  2. Listener service will send out an APNs push notification via Apple APNs to WorxMail. The APNs push notification will have the total unread count of the inbox.
  3. WM will connect to Exchange server via active sync and sync e-mails as well as trigger mail notifications if enabled by the user in WorxMail settings.

Q2: Does anything need to be configured on the Exchange Server to make it aware of the Listener service?

  • EWS Push Notification APIs will be used by WorxMail to communicate with the Exchange Server.
  • For most customers, EWS will be enabled on the Exchange server since Outlook for Mac uses EWS. Ensure with your Exchange Admin that EWS is not blocked or allowed for only specific user agents.
  • At FTU, after upgrade, or when the policy change to turn on APNs is received by the client, the client makes a push subscription request to Exchange. The URL of the listener service will also be communicated as part of this request to Exchange. This is how the Exchange server knows which Listener service to communicate with to trigger push notifications to the device.
  • Refer to the tech note on EWS Push notifications for complete details of the subscription request from the client.

Q3: What server role on Exchange carries out the communication with the listener service?

A: CAS – Client Access Server

Q4: What kind of information does the Listener service know about a Mailbox?

A: No Personally Identifiable Information (PII) is available to the Listener Service. The Listener service will store the following information:

  1. Device Token ID: Assigned to the device during initial registration with the listener service
  2. EWS subscription ID: assigned by Exchange to the client upon EWS Push subscription request
  3. EWS folder ID of inbox.
  4. Active Sync ID hashed with SHA-256
  5. Email address hashed with SHA-256
  6. iOS version
  7. APNs specific information: notification id, etc
  8. No mail data will flow through the listener service.

Q5: How will the actual mail data traffic flow?

A: This will continue to flow between the device and the exchange server via ActiveSync (no change in the behavior).

Q6: What happens if the EWS connection from Exchange to the Listener service fails?

  • The connection will be retried for up to 15 minutes based on the algorithm described in this StatusFrequency.
  • If within 15 minutes, there is still no success, Exchange will terminate the subscription request for the client.
  • When WorxMail is brought into the foreground, it will check its registration status with the listener service every 5 minutes.
  • If it has been 30 minutes since the listener service last received an update from Exchange, the client will send a new subscription request to Exchange since Exchange would have terminated the subscription after retrying for 15 minutes.

Q7: Why are we using ‘Push’ instead of ‘Streaming’ notifications? Microsoft seems to recommend the latter.

A: The only reason Microsoft recommends streaming over push is because of the reduction in overhead of an additional listener service that needs to be written and maintained. Since Citrix is hosting the listener service, a push solution is just as viable and effective.

In addition, to use the streaming approach, the server would have to subscribe itself to Exchange for the updates and would require the credentials of the user. For a cloud based offering, this cannot be done. This would be the approach for an On-prem solution.

Q8: What info will help Citrix support if I need assistance troubleshooting my APNs setup?

  • WorxMail logs – set this to Debug level 10 or 15 (preferred)
  • Your APNs tenant ID
  • Screenshots of the badge count and AppController policy settings

Additional Resources

CTX200971 - How to Prepare WorxMail for APNs Worx App

CTX201025 - FAQ: Badge Behavior and Notifications Behavior for End Users

Mobility Experts: A Step-by-Step Guide to Configuring WorxMail APNS

Applicable Products


Join the conversation

Citrix Discussions

Open a case

Citrix Support