Product Documentation

Testing and Troubleshooting WorxMail

May 28, 2016

When WorxMail isn't working properly, connection issues are typically the cause. This article describes how to avoid connection issues and, if issues do occur, how to troubleshoot them.

Testing ActiveSync Connections, User Authentication, and APNs Configuration

The Worx Exchange Active Sync (EAS) Test tool helps you verify that ActiveSync is ready for deployment in a XenMobile environment and that your environment meets the system requirements for WorxMail push notifications. The Worx EAS Test tool verifies the following:

  • iOS and Android device connections with Microsoft Exchange or IBM Traveler servers.
  • User authentication.
  • Push notification configuration for iOS, including Exchange Server, Exchange Web Services (EWS), NetScaler Gateway, APNs certificates, and WorxMail.
    For information about configuring push notifications, see Push Notifications for WorxMail for iOS.

The tool provides a comprehensive list of recommendations for correcting issues.

Installing Worx EAS Test

The Worx EAS Test tool, Worx EASTest.ipa, is available for download from http://support.citrix.com/article/CTX141685.

The EAS Test tool supports environments configured with explicit user name and client certificate authentication. The method for installing Worx EAS Test on devices depends on the type of authentication that you want to test:

Authentication Type Installation Method

Explicit user name

Install Worx EASTest.ipa on iOS devices using iTunes.

Client certificate

Wrap Worx EASTest.ipa with the MDX Toolkit and then add the app to XenMobile.

To uninstall Worx EAS Test:

  1. Press and hold the Worx EAS Test Tool icon on your home screen until the icon begins to move back and forth.
  2. Tap the X in the upper left corner of the icon.
  3. When prompted, tap Delete.

Worx EAS Test Logs

Worx EAS Test writes all logs to /documents/citrixlogs/ on a device. If you wrap Worx EAS Test, the app generates two files: CtxLog_AppInfo.txt and CtxLog_AppPolicies.xml. Use the Send Log command in Worx EAS Test to email all log files.

Testing with Worx EAS Test

Prerequisites for testing:

  • Set the Network access policy to Unrestricted.
  • Set the Block email compose policy to Off.

To set up a test:

  • On the device where you installed Worx EAS Test, open the tool.
localized image
  • To add the server you will test, tap Add new server. Specify any of the following to connect to a server:
    • FQDN (subdomain.example.com)
    • IP address (10.20.30.40)
    • Email address (name@example.com)

For a cluster configuration, add all the servers including the load balancing server. Tap Next to add more servers or tap Dismiss to continue with the next step. To delete an added server, swipe left on its name and tap Delete.

  • Enter the following items for the account to be used to test the connection. To enter an item, tap the field, type the value, and then tap Next.
    • Username: Specify either the userPrincipalName (UPN) or sAMAccountName attribute.
    • Domain: Provide the user domain. If you are using an internal domain for the Traveler server, you can leave Domain blank.
    • Password: Specify the user password.
  • To enable Accept All Certificates, set it to On.
  • By default, the Client OS is set to Auto Detect. In this case, the settings appear as shown in the following example.
localized image
  • To change the OS, Version, or Device Type, select them from the provided lists.
  • To add a Version or Device Type, tap its label, tap + and then enter the information as shown in the following example. When you are finished, tap <. To return to the main screen, tap < again.
localized image
  • To change the number of times the test runs, tap Repeat Count and then tap a value.
  • To run the test, tap Diagnose in top right corner.

Test results appear as shown in the following example:

localized image

The following example shows how issues are reported.

localized image

The following example shows how the tool notifies you that WorxMail successfully received a test push notification.

localized image

If there are issues during the test, the results appear as shown in the following example:

localized image
  • For a detailed list of ActiveSync policies, tap Send Logs and then tap Send.
  • To reset the test, tap Reset on the main screen. A reset performs the following actions:
    • Deletes all Server names.
    • Clears all Credentials.
    • Sets Accept All Certificates to Off.
    • Sets Client Settings to Auto Detect.
    • Sets Repeat Count to 1.

Using WorxMail Logs to Troubleshoot Connection Issues

All Worx apps generate several logs to assist with troubleshooting. To obtain WorxMail logs:

  • Go to Worx Home > Help > Report Issue.
  • Select WorxMail from the list of apps.
  • An email addressed to your organization's help desk opens.
  • Fill in the subject line and body with a few words describing your issue.
  • Select the time when it happened.
  • Change log settings only if your support team has instructed you to do so.
  • Click Send. The completed message opens with zipped log files attached.
  • Click Send again.

메모

On iOS devices, Worx Home automatically uses native email clients to send WorxMail logs. Worx Home does not allow users to send logs as email attachments with WorxMail.  This is a third-party issue. As a workaround, you can configure XenMobile 10.3 to send logs to the server automatically. Go to Settings > Client Support > Send logs to IT help desk and select directly.

 

The zip files sent includes the following logs:

  • CtxLog_AppInfo.txt (iOS), Device_And_AppInfo.txt (Android), logx.txt and WH_logx.txt (Windows Phone)

App info logs include information about the device and app. Verify that the hardware model and platform version in use are supported. Verify that the versions of WorxMail and MDX Toolkit in use are the latest and are compatible. For details, see System Requirements for WorxMail and XenMobile Compatibility.

  • CtxLog_VPNConfig.xml (iOS) and VpnConfig.xml (Android)

    The VPN configuration logs are provided for Worx Home only. Check the NetScaler version (<ServerBuildVersion>) to ensure the latest NetScaler release is in use. Check the <SplitDNS> and <SplitTunnel> settings as follows:

    • If Split DNS is set to Remote, Local, or Both, verify that you are correctly resolving the mail server FQDN through DNS. (Split DNS is available for Worx Home on Android.)
    • If Split Tunnel is set to On, make sure that mail server is listed as one of the Internet apps accessible on the backend.
  • CtxLog_AppPolicies.xml (iOS), Policy.xml (Android and Windows Phone)

The policies logs provide the values of all MDX policies applied to WorxMail as of the time you obtained the log. For connection issues, verify that the values for the <BackgroundServices> and <BackgroundServicesGateway> policies.

  • Diagnostic logs (in the diagnostics folder)


For initial configurations of WorxMail, the most common issue is “Your Company Network Is Not Currently Available.” To use the diagnostic logs to troubleshoot connection issues, as follows.

The key columns in the diagnostic logs are Timestamp, Message Class, and Message. When an error message appears in WorxMail, make note of the time so you can quickly locate related log entries in the Timestamp column.

To determine whether the connection from the device to NetScaler Gateway succeeded, review the AG Tunneler entries. The following messages indicate successful connection:

AG policy Intercepting FQDN:443 for STA tunneling

New TCP proxy connection to (null):443 established

To determine whether the connection from NetScaler Gateway to XenMobile succeeded (and thus can validate the STA ticket), go to the Worx Home diagnostic log and review the INFO (4) entries under Message Class, for the time the device was enrolled. The following messages indicate that Worx Home obtained a STA ticket from XenMobile:

Getting STA Ticket

Got STA Ticket response

STA Ticket – Success obtaining STA ticket for App -- WorxMail

메모

During enrollment, Worx Home sends a request to the XenMobile server for a STA ticket. The XenMobile server sends the STA ticket to the device, where it is stored and added to the XenMobile server STA ticket list.

To determine if the XenMobile server issued a STA ticket to a user, check the UserAuditLogFile.log, included in the XenMobile support bundle. It lists for each ticket, the issue time, user name, user devices, and result. For example:

Time: 2015-06-30T 12:26:34.771-0700

User: user2

Device: Mozilla/5.0 (iPad; CPU OS 8_1_2 like Mac OS X)

Result: Successfully generated STA ticket for user ‘user2’ for app ‘WorxMail’

To check the communication from NetScaler Gateway to the mail server, a quick way to tell if DNS and networking are configured correctly is to use WorxWeb to access Outlook Web Access (OWA). Like WorxMail, WorxWeb can use a micro VPN tunnel to establish a connection to NetScaler Gateway, which acts as a proxy to the internal or external resource it is accessing. In most cases, particularly in an Exchange environment, OWA is hosted on the mail server.

To test the configuration, open WorxWeb and enter the FQDN of the OWA page to see if you can access it. That request takes the same route and DNS resolution as communication between NetScaler Gateway and the mail server. If the OWA page opens, you know that NetScaler Gateway is communicating with the mail server.

If all of the preceding checks indicate successful communications, you know that the issue isn’t with your Citrix setup, but instead with the Exchange or Traveler servers.

You can collect information for your Exchange or Traveler server administrators. First check for HTTP issues on the Exchange or Traveler servers by searching the WorxMail diagnostic log for the word “Error”. If the errors include HTTP codes and you have multiple Exchange or Traveler servers, investigate each server. Exchange and Traveler have HTTP logs that show HTTP requests and responses from client devices. The log for Exchange is C:\inetpub\LogFiles\W3SVC1\U_EX*.log. The log for Traveler is IBM_TECHNICAL_SUPPORT > HTTHR*.log.

Troubleshooting Issues with Email, Contacts, or Calendar

Suppose that WorxMail is having an issue such as it can’t send an email, emails are getting stuck in drafts, contacts are missing, or calendar items are out-of-sync. To troubleshoot those types of issues, use Exchange ActiveSync mailbox logs. The logs show incoming requests sent by the devices and the outgoing responses from the mail server.

For more details, see these TechNet blog posts:

Exchange ActiveSync Mailbox Logging

Under The Hood: Exchange ActiveSync Mailbox Log Analysis