WorxMail APNs Troubleshooting
To have a real time email sync experience with WorxMail, you need to enable WorxMail with APNs. You can find the steps to enable the same here.
Post configurations, if you run into any issues with WorxMail APNs notification, this blog will help you debug the issue.
To start with make sure you have taken care of the pre-requisites that are required for WorxMail APNs.
For newer version of APNs troubleshooting article, please refer to https://support.citrix.com/article/CTX222834
There are multiple moving parts that are involved in the WorxMail APNs badge notification update process.
- WorxMail with correct push notification configurations.
- iOS Device.
- APNs server
- Citrix push registration cloud server
- Exchange Web Services
- Citrix listener service cloud server.
To have the APNs working on WorxMail, we need all the above parts setup correctly and communicating with each other. As part of First time utilization(FTU) setup of WorxMail, WorxMail will communicate with exchange server to sync the email using Active sync protocol.
As part of FTU setup if the WorxMail is configured with APNs setting as prescribed in the above articles then firstly WorxMail will register itself with APNs server for remote notifications and in turn device(WorxMail) gets a device token from APNs server. Now WorxMail will register with Citrix Push registration server with the received device token, again WorxMail will register itself with EWS for subscription ID (for a push based event). In the process of registration with EWS site, EWS will challenge the request with 401 authentication, now WorxMail will respond the authentication request with credentials that it has from the FTU. Upon successful authentication EWS will return a subscription ID to WorxMail(mapped to the device ID).
Stage 2: Whenever a new email lands in the Inbox folder of the end user, an EWS push notification is send to the subscribed devices notifying the Citrix listener service, Citrix listener service will send an APNs notification to the Apple server. Apple server in-turn will notify the device and will silently update the WorxMail badge.
Once you have done all the configuration on the WorxMail, post download you have configured Worxmail, however you don’t see any push notification badge update coming to WorxMail then below check points will be helpful in debugging the issue.
Point 1: To start, gather the WorxMail logs from the device for analysis. Once you have the logs, extract them into a folder, navigate to the WorxMail folder and look for “CtxLog_MailConfiguration” log file.
Once you open “CtxLog_MailConfiguration” log file, you should be able to see Push notification listener service token(64 character length – token containing alphanumerics) assigned. This token value should not be “Nil”. If you have this token value set to Nil, then you can straight away confirm that WorxMail APNs is not working
Point 2: WorxMail requests for APNs token
Navigate to Diagnostics folder inside the WorxMail folder and open the latest log file available. As per flow, first WorxMail will request for an APNs token. To confirm that the WorxMail did receive the token you should look for the below set of logs which confirms that the WorxMail is able to get the device token from the APNs.
2015-09-19T18:50:02.859-0400 WorxMail INFO (4) Requesting device token from iOS
2015-09-19T18:50:02.884-0400 WorxMail INFO (4) didRegisterForRemoteNotificationsWithDeviceToken – received device APNS token
2015-09-19T18:50:02.884-0400 WorxMail INFO (4) Obtained device token successfully
Received tokens(For Reference only)
deviceActiveSyncId = 56eeb72232490dbb63b124273a25fb3c6a0bf7932827965de08585cdaf78fb54;
deviceNotificationId = 1fe3ff5c6684581af6922f0cff92376dc468216bca7ea87531877b0980daf5b3;
emailId = 796b83a75c32179d4b025afbf187872d31fb5ec9be3ac2f3feae9336d77b0378;
- If you do not see the device token received by the WorxMail, make sure WorxMail is able to reach the Apple push notification servers.
- If you have WorxMail’s Network policy set to “tunnel to internal network,” make sure your NetScaler is able to reach the Citrix push registration listener service.
- If your NetScaler servers cannot talk to the push registration listener servers, try enabling the split tunnel on the NetScaler policies, so the WorxMail can leverage the device DNS to talk to the APNs.
point 3: WorxMail registers with push registration service
In the WorxMail logs, you can see if the WorxMail is registering with push listener service (In this case the push registration server URL is “https://us-east-1.pushreg.xm.citrix.com”) with device ID’s that it has received in the previous step. If the WorxMail can reach https://us-east-1.pushreg.xm.citrix.com then you can view the device registration.
Note: Your Push registration service URL might be different based on the configuration that you have in WorxMail MDX policies.
2015-09-19T18:50:02.904-0400 WorxMail INFO (4) ProvisionStatus = ProvisionStatusRegisteringForPushNotifications
2015-09-19T18:50:03.312-0400 WorxMail INFO (4) Device registration successful with token from server fce470ad6f11f0d3d9494e65c19868bda92091dff1dae38c4a4234e58f7e5dce
- If you do not see the device registration happening with the push registration server, then make sure WorxMail is able to talk to Citrix push registration URL’s(*.pushreg.xm.citrix.com).
- If you have WorxMail’s Network policy set to “Tunnel to internal network” then make sure your NetScaler is able to reach Citrix push registration listener service.
- If your NetScaler servers cannot talk to the push registration servers, try enabling the split tunnel on the NetScaler policies, so the WorxMail can leverage the device DNS to talk to push registration servers.
Note(Imp): If your NetScaler Gateway configuration includes Secure Ticket Authority (STA) and split tunneling is off, NetScaler Gateway must allow outbound SSL (over 443) connection from NetScaler (when tunneled from Secure Mail)
1. For Americas:https://us-east-1.pushreg.xm.citrix.com (IP: 22.214.171.124; 126.96.36.199)
2. For EMEA:https://eu-west-1. pushreg.xm.citrix.com (IP: 188.8.131.52; 184.108.40.206)
For APAC:https://ap-southeast-1. pushreg.xm.citrix.com (IP: 220.127.116.11; 18.104.22.168)
Point 4: WorxMail subscription to EWS
WorxMail will register itself with the EWS server, as part of which EWS will provide a 401 authentication challenge which WorxMail will try to respond to with the credentials. Upon successful authentication EWS will provide a Subscription ID to WorxMail. You can see the below logs confirming the subscription id.
2015-09-19T18:50:03.313-0400 WorxMail INFO (4) EWS operation name=SubscribeToPushbaseEventNotification
2015-09-19T18:50:03.314-0400 WorxMail INFO (4) ProvisionStatus = ProvisionStatusSubscribingForPushNotifications
2015-09-19T18:50:03.846-0400 WorxMail INFO (4) Inside completion block for operationName=SubscribeToPushbaseEventNotification
2015-09-19T18:50:03.846-0400 WorxMail INFO (4) Received HTTP status code 200 for operationName=SubscribeToPushbaseEventNotification
2015-09-19T18:50:03.846-0400 WorxMail INFO (4) Received response string content for operationName=SubscribeToPushbaseEventNotification
2015-09-19T18:50:03.848-0400 WorxMail INFO (4) EWS Subscribe to push event notification successful
2015-09-19T18:50:03.848-0400 WorxMail DETAIL (5) SubscriptionId:- GQBmdGxwZXgwMWNhczAzLmNpdHJpdGUubmV0EAAAABEsUvAkwt1IsKpqHhaQgA5F4ZVHnWDSCA==
- Make sure WorxMail is reachable to the exchange servers EWS site.
- Make sure EWS site is enabled with the same Authentication method same as Active Sync server. Basic authentication, NTLM authentication etc.
- Make sure certificate that is bound to the EWS site is trusted.
Point 5: WorxMail gets the Inbox folderID and the unread count from EWS
Post authentication to EWS site, WorxMail will get the folder ID which is enabled for push notifications. You can confirm the same with the below set of logs.
2015-09-19T18:50:03.848-0400 WorxMail INFO (4) EWS operation name=GetFolder
2015-09-19T18:50:03.849-0400 WorxMail INFO (4) ProvisionStatus = ProvisionStatusGettingFolderIdForPushNotification
2015-09-19T18:50:04.436-0400 WorxMail INFO (4) Inside completion block for operationName=GetFolder
2015-09-19T18:50:04.437-0400 WorxMail INFO (4) Received HTTP status code 200 for operationName=GetFolder
2015-09-19T18:50:04.437-0400 WorxMail INFO (4) Received response string content for operationName=GetFolder
2015-09-19T18:50:04.438-0400 WorxMail INFO (4) Got folderId for inbox
2015-09-19T18:50:04.439-0400 WorxMail DETAIL (5) Folder ID:- AQAWAGNocmlzLmJ1cmtlQGNpdHJpeC5jb20ALgAAA4tYHB9LXmFGujrRkElxHqIBAH2WBaHLe7JPv8/7wkthmdIAAAEPU8YAAAA=
Point 6: WorxMail updates the listener service
WorxMail in turn will update the listener service.
2015-09-19T18:50:04.442-0400 WorxMail INFO (4) ProvisionStatus = ProvisionStatusUpdatingListenerServiceForPushNotifications
2015-09-19T18:50:04.752-0400 WorxMail INFO (4) Calling success block for Listener service update.
- Make sure exchange server is able to reach the Citrix listener service(*.mailboxlistener.xm.citrix.com).
Other important points:
- WorxMail will be enabled with APNs only at the time of FTU. For any reason if APNs does not work you will have to re-download the application and then re-configure it from the FTU.
- For any reason, if WorxMail does not contact EWS site for large amount of time then exchange server will terminate the subscription ID, then WorxMail will re-initiate a new connection requesting for a new subscription Id.
If you need more help on the same, you can always reach out Citrix Support @ https://www.citrix.com/support.html