Product Documentation

WorxChat Tech Preview

Aug 11, 2016

Welcome to the WorxChat Preview. WorxChat is a mobile messaging app integrated with Lync and Skype for Business that allows users to seamlessly maintain conversations and contacts across devices, while remaining in the secure XenMobile environment.

To connect Lync or Skype with the mobile client, you need to install the WorxChat Server and other components. This diagram shows an overview of WorxChat architecture:

localized image

This article describes the steps for installing the necessary components and then configuring, wrapping and deploying WorxChat. For a look at WorxChat's user features, see WorxChat Mobile App.

During this preview, let us know what you think. You can provide your feedback here.

System Requirements

  • A dedicated Lync 2013 or Skype for Business 2015 pool. Lync and Skype can also be in the same pool as a hybrid environment.
  • WorxChat server in the same domain as the Lync pool.
  • Windows Server 2012
  • SQL Server 2012
  • .NET Framework 4.5 
  • PowerShell 3.0
  • Two CPUs with 4 GB RAM. If you have a separate test environment, you can share the SQL Server with the XenMobile server database.
  • Client: iOS 9.x and Android 4.4 to 6.x

What's New in WorxChat

Support for Android.  WorxChat is now supported for Android, versions 6.x. Please see Google Cloud Messaging below for setting up WorxChat notifications.

Support for Lync 2013 and Skype for Business 2015. You can now integrate WorxChat with Lync 2013 and Skype for Business 2015, either separately or in the same pool. 

Server Installation Prerequisites

Before installing the WorxChat Server, you must have the following prerequisites.

  • Unified Communications Managed API (UCMA) 4.0 Runtime, available here. Prior to installing UCMA 4.0 Runtime, enable the Media Foundation feature and restart the system. If you don't restart the system, UCMA installation will fail. For instructions on enabling a Windows feature, see this article. No restart is required after installing UCMA 4.0 Runtime.
  • A wild card certificate or a certificate with the UCMA trusted application pool FQDN as the Common Name and with the Common Name plus the computer FQDN (for example, WorxChat Server) in the Subject Alternative Name field. You can create the certificate using MMC Snap-ins.

    Put the certificate in the computer account's certificate store's Computer\Personal location. The WorxChat Server web app will use this certificate as the web server certificate and also to establish mutual trust between the WorxChat Server and the Lync server.
     

Installing the WorxChat Server

To deploy WorxChat, you need to install the WorxChat Server, which creates a database that stores necessary data about user endpoints and manages message exchanges between WorxChat clients and the Lync server.

1. You can download the WorxChat Server installer from the XenMobile downloads page.  

Important

Before starting the installer, you have to disable User Access Control.

  1. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system
  2. Change the DWORD EnableLUA from 1 to 0.
  3. You will get a notification that a restart is required. After the restart, User Access Control is disabled.

The user running the installer should have Lync administrator privileges. First, the installer checks that all prerequisites are available. If they aren't, an error message appears.

If all prerequisites are available, the Citrix license agreement screen appears.

localized image

2. Click I agree to the license terms and conditions and then click Install.

The installation process begins.

localized image

First, the installer enables Windows Identity Foundation 3.5. The installer then enables the following components:

  • Web Server
  • Web-Common-Http
  • Web-Default-Doc
  • Web-Dir-Browsing
  • Web-Http-Errors
  • Web-Static-Content
  • Web-Http-Redirect
  • Web-DAV-Publishing
  • Web-Health
  • Web-Http-Logging
  • Web-Custom-Logging
  • Web-Log-Libraries
  • Web-ODBC-Logging
  • Web-Request-Monitor
  • Web-Http-Tracing
  • Web-Performance
  • Web-Stat-Compression
  • Web-Dyn-Compression
  • Web-Security
  • Web-Filtering
  • Web-Basic-Auth
  • Web-CertProvider
  • Web-Client-Auth
  • Web-Digest-Auth
  • Web-Cert-Auth
  • Web-IP-Security
  • Web-Url-Auth
  • Web-Windows-Auth
  • Web-App-Dev
  • Web-Net-Ext
  • Web-Net-Ext45
  • Web-AppInit
  • Web-ASP
  • Web-Asp-Net
  • Web-Asp-Net45
  • Web-CGI
  • Web-ISAPI-Ext
  • Web-ISAPI-Filter
  • Web-Includes
  • Web-WebSockets
  • Web-Ftp-Server
  • Web-Ftp-Service
  • Web-Ftp-Ext
  • Web-Mgmt-Tools
  • Web-Mgmt-Console
  • Web-Mgmt-Compat
  • Web-Metabase
  • Web-Lgcy-Mgmt-Console
  • Web-Lgcy-Scripting
  • Web-WMI
  • Web-Scripting-Tools
  • Web-Mgmt-Service

After the components are enabled, the OCSCore component of the Lync SDK, which allows the local computer to run Lync-server-specified PowerShell cmdlets, is installed.

localized image

The installer then runs the Bootstrapper.exe to set up the management store.

Next, the installer collects a list of certificates from the Certificate Store and from the list of Trusted Application Pool FQDNs from the Lync server. After those are collected, the welcome screen appears.

localized image

3. Click Next. Enter the SQL server FQDN in the Database server FQDN field.

4. You must authenticate to the SQL server. Do one of the following:

  • If you select Integrated Windows Authentication, no user name or password is required. Click Next to continue.
  • If you select Explicit Authentication, you must enter a user name and password before clicking Next.
localized image

At any point during installation, you can click the question mark for more information about a particular field.

Next, the installer checks if the database server (at the given FQDN/IP address) is accessible with the user-selected authentication type. If not, a connection error message appears.

If the connection is successful, the pool settings screen appears.

localized image

5. Enter a server pool name, such as WorxChat Server Pool 1, which will allow easy identification when there are multiple WorxChat server pools, and then click Next.

The Web server certificate screen appears.

localized image

6. In the Select your web server certificate list, choose the same certificate that satisfies the certificate requirements outlined in the System Requirements section.

7. Click Next.

The Lync trusted application pool settings screen appears. On this screen, you'll configure UCMA pool-related settings. You can choose to create a new pool or add the settings to an existing pool.

New pool:

localized image

8. When you use an existing pool, choose from a list of all UCMA-trusted app pools in the domain.

localized image

9. Click Next.

The installation confirmation screen appears.

localized image

10. Click Install.

The status of the process appears as the installer configures the database, adds the server to the UCMA trusted applications pool, writes system registry values, and deploys the WorxChat server code to the local Internet Information Services (IIS) server.

When the setup is complete, the following screen appears.

localized image

11. Click Exit.

The success screen appears.

localized image

12. Click Close to finish the installation.

WorxChat Server Firewall Settings

If firewall protection is on for WorxChat Server, you need to configure the following settings so that WorxChat Server and the Lync server can communicate. To turn on firewall protection, see this Microsoft article, Turn Windows Firewall on or off.

Firewall settings on WorxChat Server:

  • Allow outgoing connections to port <lync_server_FQDN>:5061, or whichever port number is configured in the DNS record at _sipinternaltls._tcp.<domain>.
  • Allow incoming connections to TrustedApplicationPort on WorxChat Server. Use the port number you specified on the Lync trusted application pool settings screen when installing WorxChat Server. This is the port number on which WorxChat Server will listen for incoming connections from the Lync server.
  • Allow incoming connections to TCPPort on the WorxChat Server. Default value is 8080. You can change this value in the web.config file (usually found in the c:\inetput\wwwroot\CTXUCMAService folder) of the WorxChat Server web app.

Firewall settings on the Lync server:

  • Allow incoming connections to port <lync_server_FQDN>:5061, or whichever port number is configured in the DNS record at _sipinternaltls._tcp.<domain>.
  • Allow outgoing connections to TrustedApplicationPort on WorxChat Server. Use the port number you specified on the Lync trusted application pool settings screen when installing the WorxChat Server.

For more information on firewall rules, see this Microsoft TechNet article, Add or Edit Firewall Rule.

Apple Push Notifications and Google Cloud Messaging

After you install the WorxChat Server, you need to configure Apple Push Notifications (APNs) for iOS platforms or Google Cloud Messaging for Android platforms.

In WorxChat, push notifications keep mobile endpoints connected at all times. Even if users exit the app, their messages are still delivered.

Apple Push Notifications

The steps for requesting an APNs certificate and for configuring push notifications in NetScaler are the same for WorxChat as for WorxMail. For details, see Push Notifications for WorxMail for iOS and this Citrix blog post.

1. Go to XenMobile Management Tools and sign in.

localized image

2. On the next screen, select Manage push notification.

Note that although Android is mentioned, this preview is available for iOS only.

localized image

3. When prompted to choose your region, for this tech preview, Americas is the only region available.

localized image

4. When prompted to confirm Americas as your region, click Yes, I'm sure.

The Choose Your Platform screen appears.

localized image

5. Select iOS and then click Next.

The Upload APNs Certificate screen appears.

localized image

6. In the App Name field, enter the app name, such as WorxChat.

7. In the App ID field, enter WorxChat bundle ID, which takes the form com.companyname.chat.

8. Upload the APNs certificate and then enter the certificate password.

For more information about each field, click the question mark icon next to it.

9. Click Upload.

If the upload is successful, the following screen appears with the Customer ID (shaded out in this figure), which you'll need to enter when you upload WorxChat to the XenMobile console.

localized image

Google Cloud Messaging

1. Go to https://console.cloud.google.com and click Create an Empty Project.

localized image

2. Name your project and click Create.

localized image

 

3. On the Dashboard, click Enable and Manage APIs.

 

localized image

4. Under the Google APIs tab, search for and select Google Cloud Messaging.

localized image

5. On the following screen, click Enable.  

localized image

 

6. Click Go to Credentials to set up your Google Cloud Messaging credentials.

 

localized image

7. On the following screen, select Web server from the Where will you be calling the API from? list.

localized image

8. On the next screen, enter a name and optional IP addresses, then click Create API key.

 

localized image

9. On the next screen, you'll see you API key (shaded out here). You will need the API key to get your Customer ID from the Citrix push notification service. You will also need your project number, which you can find under Settings.

10. Go to XenMobile Management Tools and sign in.

11. Follow the steps, as shown in the Apple Push Notifications above. Enter the API key and the project number when prompted.

12. When you upload WorxChat to the XenMobile Server, enter the project number and Customer ID when prompted.

Where to Find Components

Here's where to find the components you've just installed.

WorxChat Server components appear under Control Panel > Programs > Programs and Features

localized image

The databases folder that the installer created is nested inside the SQL Server folder.

localized image

The website that IIS created is under Default Web Site.

localized image

The folder path to where the website points is shown in the following figure.

localized image

 

 

Server Settings: Web.config

In the web.config file shown in the preceding screenshot, you can manage the following parameters in the appSettings section of the file.

  • ThresholdCount: Maximum numbers of users per server. For this preview, the maximum is 500.
  • NotificationLevel: Push notifications policy. The values are CountOnly (number of unread messages), SenderNameOnly (sender name) or NameWithMessage (sender name with message preview). Default is CountOnly.
  • MaxEndpointInactivityPeriodInHrs: The number of hours before an endpoint is terminated due to inactivity. Default is 72 hours.
  • TCPPort: The port for communication with the mobile app. Default is 8080.

Once the web.config file is edited, restart the IIS services for the changes to take effect.

localized image

Remote Database Server

The WorxChat web app runs under the Local System identity, using the machine's identity to access the remote database server.

Give the machine identity read/write access to the WorxChat-owned databases, DataInformation and ControlInformation, on the remote database server.

Follow these steps to create a machine account and give appropriate permissions on a database server:

  1. Run the following SQL command on the database server to create the machine login account:

    Create Login [<domain_name>\<machine_name>] From Windows;

    For more information on creating database logins, see this TechNet document.  

  2. Run the following commands to give appropriate permission to the newly created machine account:

    ALTER AUTHORIZATION ON DATABASE::DataInformation TO [<domain_name\machine_name>];

    ALTER AUTHORIZATION ON DATABASE::ControlInformation TO [<domain_name\machine_name>]

Downloading and Wrapping WorxChat

Download WorxChat and other XenMobile components from the XenMobile downloads page.

To wrap the app with the MDX Toolkit, see Wrapping iOS Mobile Apps.

WorxChat Policies on XenMobile

The following table shows the XenMobile policies that you can configure for WorxChat.

Policy

Description

 

Lync Chat Server Mapping

Maps the WorxChat server FQDN to the corresponding Lync pool/server FQDN. This is how the client knows which WorxChat server to connect to.

Format:  “Chat Server FQDN:Lync Pool FQDN”

User domain

 

The same as the domain portion of the user principal name (UPN). For example, for user@company.net, the user domain is company.net.

 

 

Background network services

Specifies Lync auto-discover FQDN and WorxChat server FQDNs when using Secure Ticket Authority (STA). 

You should also specify the push registration server FQDN: 443 here:

us-east-1.pushreg.xs.citrix.com:443.

Values are comma-separated with no space.

 

Accept all SSL certificates

If ON, WorxChat accepts all SSL certificates, whether valid or not. If OFF, WorxChat blocks access when a certificate error occurs.

 

Push notifications customer ID

Push server region should be selected as Americas.

The customer ID is returned when uploading the push certificate.

 

Max Conversation history

Sets the maximum time period to save messages on the device. Messages older than this period are erased.

 

Allow ShareFile

Allows users to attach ShareFile files to their messages.

The policies are at Configure > Apps > App Information > Platform > iOS.

localized image
localized image

WorxChat Secure Ticket Authority Configuration

To allow users to stay connected for long periods of time without having to authenticate frequently, configure the Secure Ticket Authority (STA) for WorxChat. Configure this the same way that you configure STA for WorxMail, as explained in Configuring App Controller to Provide STA Tickets for WorxMail, with these differences:

  • No WorxMail Exchange Server or domain is required.
  • In Background network services, enter the WorxChat servers and ports mentioned in WorxChat Policies in XenMobile.

If you have already configured STA for WorxMail on NetScaler Gateway, no further configuration is needed for WorxChat.

 

Troubleshooting / FAQs

Where can I find WorxChat Server logs?

You can find the log files at:

C:\inetpub\wwwroot\CTXUCMAService\Logs

The Window Event Viewer also will have error logs on an unhandled-error scenario.

 

Why am I seeing a database login error in the logs?

If you're using a remote database server, check if you've given permission to the machine account to access the WorxChat database. Refer to Remote Database Server for details.

 

Why can't I sign on to the WorxChat mobile app?

Check the following:

  • The WorxChat Server is up and running using IIS Manager.
  • You've added all necessary DNS records for auto-discovery to work. You can find the DNS requirements here. You can also use the Lync connectivity analyzer to check the status of connectivity. Use Lync Mobile 2013 app as the testing client.
  • Is Windows Firewall blocking access to the TCP port (default is 8080) on which WorxChat server is listening for connections? If so, add the necessary policy to open up access to that particular port. The value of the attribute configuration\appSettings\TCPPort in Web.config file is the port number on which WorxChat server is listening for incoming connections.

 

WorxChat Server is installed, but the mobile app isn’t connecting.

The WorxChat service application pool is running as a LocalSystem account. Make sure the LocalSystem account has permission to access the Active Directory.