Configuring push notification

NexJ applications rely on the application server to send or push data to the client in real time as it becomes available. This is required for notifications and reminders.

To meet the needs of scalability, compatibility with different J2EE containers, and reliability of data, the push notification functionality is separated into two components: the push server and the push redirector.

The push server receives initial client requests, authenticates them, and redirects them to the push redirector.

The push redirector establishes a regular HTTP connection with the push server and listens for notifications coming in on the connection. After clients are authenticated and redirected by the push server, the push redirector establishes a Comet connection with clients and pushes notifications onto that connection. The push redirector is deployed on NexJ Model Server.

Comet is a communication technique that allows a server to send data to a web browser without the data being explicitly requested by the client. Data streaming and long polling use Comet. The push redirector also uses Comet in combination with Java NIO (non-blocking I/O) to disassociate threads from open sockets, creating a scalable push solution.

For architectural information about the components in the push notification process, and notification protocols and modes, see Push notification architecture overview.

You can determine the push URL, push state, and push retry timeout value for your deployment from the About NexJ CRM dialog. You may need to provide this information to NexJ Customer Support.

In NexJ CRM, on the application toolbar, click the User settings button and select About NexJ CRM.

Push notification types

Three push notification types are available to use in NexJ applications. Long polling and data streaming both use Comet and require the server to notify the client of new information. Client polling relies on the client to check for updates.

Data Streaming
When the client requests information from the server, the server holds the request indefinitely. As information becomes available to the server, it is written to the output stream and sent to the client. The output stream remains open after sending to allow more data to be sent as it becomes available.

Data streaming is recommended and used by default if a push type is not specified by the client. Data streaming cannot be used if there is a proxy server between the client and push redirector that does not handle uncommitted server responses for each request and response. If data streaming is not appropriate, the client must request long polling when the client establishes the initial Comet connection. To use data streaming, set the Push Type value to "streaming".

Long Polling
When the client requests information from the server, the server holds the request until a notification is ready to be pushed to the client. After information becomes available to the server, a completed response is pushed to the client and the connection closes. The client immediately registers for push notifications again in order to continue receiving updates. This notification type uses the Comet technique. To use long polling, set the Push Type value to "long".

Client Polling
The client periodically polls for new data from the server. Because the client is constantly checking for new updates, this solution does not rely on the server for push notifications. However, this push type is neither real time nor scalable and constant client requests can overload the server. To use client polling, set the Push Type value to "none".

Push notification configurations

Configuration	pushRedirectorURL	pushServerURLs
Embedded push	Not set	Set
Embedded push redirector	Set	Set
Embedded push redirector with auto-discovery	Set	Not set
Standalone push redirector	Set	Set
Standalone push server	Not set	Not set

Embedded push

This configuration combines the functionality of the push redirector and the push server into a single component running in NexJ Model Server.

Embedded push redirector

In this configuration, the push redirector and the push server run in the same NexJ Model Server process.

Use this configuration only for development, which usually involves running a single instance of the Model Server from within NexJ Studio and without using a web server.

Embedded push redirector with auto-discovery

This configuration is similar to "embedded push redirector" configuration, but with the additional ability for the push redirector to auto-discover and connect to all the push servers in the NexJ cluster. This way the PushServerURLs property does not need to be specified and the push redirectors on each node in the cluster are able to dynamically and automatically connect to all the push servers in the cluster as they are started.

Use this configuration only for testing. When running a cluster, it is usually done behind a web server, which would limit the number of push connections that clients can establish, to the number of threads available on the web server. Also, this configuration starts as many push redirectors as there are nodes in the cluster, which is usually more than what is needed.

Standalone push redirector

This configuration enables a standalone push redirector, which is expected to connect to a standalone push server.

Standalone push server

This configuration enables a standalone push server, which is expected to run in conjunction with standalone push redirectors which connect to it.

Push server and push redirector properties

The following push redirector and push server configuration properties can be configured as system properties, as attributes of the Server element in the .server file or the Environment element in the .environment file. If you are using the environment file as a template, the values can also be specified in the .properties file.

You can also use the NexJ Studio environment editor to specify the properties in the Push Notification tab. The name of the property as displayed in the environment editor is included in parentheses in the property descriptions below.

To configure security, you need to do one of the following:

Specify the Push User and Push Password properties.
Specify the Push Certificate and Push Password properties.
Configure SPNEGO authentication for the push redirector.

pushType (Push Type)

The push type that the NexJ application will use for notifications.

Use one of the following values:

"none" for non-Comet client polling
"long" for long polling using Comet
"streaming" for data streaming using Comet

pushRedirectorURL (Push Redirector URL)

This property is required for using the push redirector. If it is not configured, the push redirector is disabled.

The pushRedirectorURL property specifies the host, the port, and the context path of the push redirector. The host value is required but the port and context path values are optional.

The property is specified in the following format:

http[s]://<host>[:<port>][/<path>]

For example:

http://localhost:5080/nexj/pushRedirect

If the port or context path are not specified, the default values are used. The default port is 5443 if SSL is enabled and 5080 if SSL is not enabled. The default context path is /nexj/pushRedirect.

pushServerURLs (Push Server URLs)

When running as a "standalone push redirector" configuration, this property is required. If it is not configured, the standalone push redirector is disabled.

When running as an "embedded push redirector" configuration, this property is optional and will be determined automatically if it is not configured.

This property is specified as a space-separated list of full paths to each instance of the push server running on each node of the application cluster in the following format:

http[s]://<host>:<port>/<path>[ http[s]://<host>:<port>/<path>]*

For example:

http://app1.local:8080/nexj/push http://app2.local:8080/nexj/push

If using client certificate authentication, the context path should be /<app_context_root>/cert/push.

In all other cases, the context path should be /<app_context_root>/push.

The host and port must point directly to the push server nodes. The application context root must match the value specified in the httpURL attribute of the root Environment element.

pushCertificate (Push Certificate)

This is property is optional. If it is not configured, one of the following options must be true:

The pushUser property is configured.
The push server to which the push redirector is connecting must use SPNEGO as its authentication model. In this case, the service account user running the push redirector is used to authenticate.

Otherwise, an error will occur when connecting to the push server.

The property contains a Base64 encoded keystore, containing the private key and certificate to be used during client certificate authentication to the push server when using two-way SSL (mutual authentication).

The CN field of the Subject in the certificate must specify a username known to the push server as well as the push server's authentication store if using an external security store. In other words, the user specified in the CN field of the certificate must be able to authenticate with the NexJ application when connecting to the push server.

pushUser (Push User)

This property is optional. If it is not configured, one of the following options must be true:

The pushCertificate property is configured.
The push server to which the push redirector is connecting uses SPNEGO as its authentication model. In this case, the service account user running the push redirector is used to authenticate.

Otherwise, an error will occur when connecting to the push server.

The property specifies the name of the user that is used by the push redirector to authenticate with the NexJ application when connecting to the push server.

To be authorized by the push server, the push user must be assigned the PushRedirect privilege in the NexJ Admin Console. For more information about assigning privileges, see the NexJ CRM Administrator Guide. In addition, the push user must exist in the application server's authentication domain and have membership in the "nexjusers" group.

pushPassword (Push Password)

This property is required if either of the following is true:

The pushUser property is configured. In this case, the value is the push user password.
The pushCertificate property is configured. In this case, the value is the keystore password.

Otherwise, this property is optional.

pushServerTrust (Push Server Trust)

This property is required if SSL is enabled on the push server. If it is not specified, then an error will occur when the push redirector attempts to establish the initial connection to the push server.

This property specifies a Base64 encoded public certificate of the Model Server on which the push server is running. The certificate is trusted by the push redirector when making the initial connection to the push server with SSL enabled. This configuration is recommended for production.

If the certificate is self-signed, then the trust certificate must also be added to the Model Server's trust store.

If SSL is not used on the push server or if the trust certificate is added manually to the Model Server on which the push redirector is deployed, this property is optional.

pushTrust (Push Trust)

The fallback property that contains the push server SSL certificate that the push redirector should trust, when pushServerTrust is not specified.

pushTimeout (Push Timeout)

This property is optional.

The property specifies, in milliseconds, the interval that indicates when an idle Comet connection between the client and the push redirector times out. When a timeout occurs, an empty notification is sent to the client. The client can detect whether something is wrong with its connection to the push redirector and try reconnecting.

The default value of pushTimeout is 300,000 milliseconds (5 minutes).

pollPeriod

The pollPeriod property must be configured in either the environment file or the properties file and not in the Push Notification tab of the environment editor.

As of NexJ CRM 9.4 and when the push type is set to "none" (client polling), this property specifies the time interval in milliseconds between poll requests.

The default value for pollPeriod is 300,000 milliseconds (5 minutes).

pushDisconnectDelay

The pushDisconnectDelay property must be configured in either the environment file or the properties file and not in the Push Notification tab of the environment editor.

This property is optional.

The property specifies, in milliseconds, when client connections are dropped if the push redirector loses connectivity with the push server.

The default value for pushDisconnectDelay is 50 milliseconds.

Push notification authentication

Push notification clients are authenticated by the application server on which the push server is deployed.

Client connections to the push redirector are authenticated through a three-way handshake brokered by the push server. When the push server authenticates a client, the push server generates a unique client ID which acts as a security token that is shared with the push redirector. The push server then redirects the client to the push redirector, passing the client ID as a parameter.

The push redirector must authenticate itself when it communicates with the application server. This behavior is similar to that of any client interacting with the server.

To configure the authentication protocol for the application server, edit the .environment file for your project to include the authProtocol attribute on the Environment root element. You can also configure it in NexJ Studio in the environment editor, in the Security subtab in the Overview tab. This is a global setting that affects all authentication performed with the application server.

Running the push redirector

To run the push redirector, ensure that the Java JDK is installed and the JAVA_HOME environment variable is set to the JDK directory.

Running the embedded push redirector

When using either of the "embedded push redirector" configurations, the Model Server is started with all the features or modules enabled, including the push server and the push redirector running on the same server.

The embedded push redirector has an independent HTTP connector listening on a separate port.

Embedded push redirector configurations are recommended primarily for development and testing.

Running the standalone push redirector

This configuration is recommended for a production environment.

The nexj-push-redirector_version.zip file, which is bundled with the NexJ Studio plugin, contains everything needed to run a standalone instance of Model Server with support for the push redirector only, where no other NexJ components or applications are enabled.

To set up a standalone instance of the push redirector, first extract the nexj-push-redirector_version.zip to a location of your choice. Inside the archive file are three directories: bin, conf, and deploy. Then navigate to the bin directory and edit one of the following files using your preferred text editor:

If you want to start the push redirector manually on Windows, edit pushrd.bat. This file starts the server and the console outputs any status messages.
If you want to start the push redirector manually on Linux, edit pushrd.sh. This file starts the server and the console outputs any status messages.
If you want to add the push redirector as a Windows service, edit pushrd-svc.bat. This file allows you run the server automatically by configuring the service.

Configure the selected file using one of three available methods.

Place a fully configured .environment or .server file in the conf directory that contains the settings for the push redirector. If multiple files are found, the first .environment file takes precedence over any .server files.

Use this method in a production environment, to ensure that the environment file is not overwritten when extracting a new version of the push redirector.
Define the CONFIG_FILE variable with the location of a configured environment or server file. If files are also present in the conf directory, the file defined in CONFIG_FILE takes precedence.
Define the PUSH_PROPS variable with the settings of each property. Each property must be prefixed with -Dnexj. If files are present in the conf directory or if CONFIG_FILE variable is defined, any properties defined in the PUSH_PROPS variable will overwrite the properties within the environment or server files. Here is a sample definition for PUSH_PROPS:
JAVA
```
set PUSH_PROPS=-Dnexj.pushRedirectorURL="http://localhost:5080/nexj/pushRedirect" -Dnexj.pushServerURLs="http://localhost:8080/nexj/push" - Dnexj.pushUser="nexjsa" -Dnexj.pushPassword="text:nexj"
```
Info

If you are deploying without HTTPS and using the PUSH_PROPS method, add the following property:
-Dnexj.secureTransport="false"

Example NexJ Standalone Push Redirector environment file

The examples provided in this topic are included for reference purposes only. You should not copy them and edit them for direct use.
Click here to expand...
TEXT
```
<Server description="Local NexJ Application Server for rapid application development." 
	secureTransport="false" 
	pushRedirectorURL="http://localhost:5080/nexj/pushRedirect" 
	httpURL="http://localhost:6080/nexj" 
	pushServerURLs="http://localhost:6080/nexj/push" 
	pushType="streaming" 
	pushPassword="nexj" 
	pushUser="nexjsa"/>
```

You can manually run the push redirector from the command line, or install and run it as a Windows service.

Manually starting the standalone push redirector

After editing the pushrd.bat file for Windows or the pushrd.sh file for Linux, you can now run the redirector.

To start the redirector, execute the pushrd.bat batch script file on Windows or the pushrd.sh shell script file on Linux. No further steps are required.

To confirm that the push redirector is connected to the push server, enter the URL of the push server in a web browser, for example: http://localhost:8080/nexj/push. The URL should bring up a web page that displays the push redirector URL in plain text. If your connection times out and produces error code 500, then the push redirector is not connected.

A log of the server is created with Apache log4j in the log directory. To configure log settings, edit the conf\log4j.properties file.

To stop the redirector, select the server console and press Ctrl + C. Enter Y when asked to terminate the process.

Starting the standalone push redirector as a Windows service

After editing the pushrd-svc.bat file, you can now run the redirector.

To register the push redirector as a Windows service and then run it:

Open a command line console and navigate to the bin directory. Enter pushrd- svc.bat -i to install the push redirector service.

Info

The pushrd- svc.bat script works with both 32-and 64-bit versions of Windows. The script automatically selects the correct version, but you can also force the script to use settings for the 32-bit version with the x86 parameter, for example: pushrd-svc.bat -i x86
In the command line, enter services.msc to open the Windows services console. Locate the service named PushRedirector and start the service to run the push redirector. Configure the service as desired.

Info

For increased security, set the Windows service to log on using a local service account with limited privileges. Update the permissions on the directory containing the push redirector files to give the service account Modify permissions.

The push redirector is now registered as a Windows service and is running.

To confirm that the push redirector is connected to the push server, enter the URL of the push server in a web browser, for example: http://localhost:8080/nexj/push. The URL should bring up a web page that displays the push redirector URL in plain text. If your connection times out and produces error code 500, then the push redirector is not connected.

A log of the server is created with Apache log4j in the log directory. To configure log settings, edit the conf\log4j.properties file.

To uninstall the redirector, enter pushrd-svc.bat -u on the command line.

Configuring SSL for the push redirector

You can configure SSL between the push redirector and the push server as well as between the push redirector and clients.

Info

Enabling SSL is recommended in a production environment.

Configuring SSL between the push redirector and the push server

Configure SSL between the push redirector and the push server by specifying the push server SSL certificate, which the push redirector should trust when making an initial connection to the push server.

You must also enable secure transport, by updating the environment file:

Set the secureTransport attribute in the server or environment file to "true".

Ensure that the value of the httpURL attribute in the server or environment file starts with "https".

To configure SSL between the push redirector and push server:

In NexJ Studio, open the push redirector environment file.
In the Overview tab, open the Push Notification subtab.
In the Push Trust field, enter the public key that matches the server certificate installed on the push server.
Save and close the environment file.

SSL is configured between the push redirector and push server.

To complete the SSL configuration for the push redirector, ensure that you also configure SSL between the push redirector and clients.

Configuring SSL between the push redirector and clients

Configure SSL between the push redirector and end users by first replacing the default conf\ssl.keystore file with your own private key certificate. This certificate must be trusted by end users connecting to the push redirector. Then, specify a password for the keystore file in the environment file.

You must also enable secure transport in the server's environment file by setting the secureTransport attribute to "true" and ensure that the httpURL attribute value starts with "https".

To enable SSL between the push redirector and clients:

On the push redirector machine, replace the default ssl.keystore:
1. Obtain a PKCS #12 keystore file from a trusted certificate authority (CA).
  
  Info
  
  The PKCS #12 keystore file should have a CN matching the hostname of the push redirector server.
2. Copy the PKCS #12 keystore file and paste it into the push redirector conf directory.
3. Delete the default ssl.keystore file.
4. Rename the PKCS #12 keystore file to ssl.keystore.
In NexJ Studio, provide the password for the keystore file:
1. In NexJ Studio, open the push redirector environment file.
2. In the Type field, ensure the server type is set to Generic.
3. In the Overview tab, open the Security subtab.
4. Enter the keystore password value that you obtained when you exported the PKCS #12 file.
5. Save the environment file. Copy the new environment file into the push redirector conf directory.

SSL is configured between the push redirector and clients.

To complete the SSL configuration for the push redirector, ensure that you also configure SSL between the push redirector and the push server.

Configuring SPNEGO authentication with the push redirector

Before SPNEGO authentication can be used with the push redirector, Kerberos service principal names must be set for each application server node. The push user and push password properties are still required in the server or environment file, but correct credentials do not need to be entered.

See Enabling SPNEGO authentication for information on enabling SPNEGO authentication in your server or environment file.

To set up SPNEGO authentication with the push redirector:

Configure Kerberos service principal names for each application server node. Kerberos may already be configured for the frontend address, but each node must be added as well.
Set the service to run as a service account on the domain. The service account must be a member of the "nexjusers" security group. If you are using a Windows-based service, the pushUser property in the environment file should be left blank. If you are using a Linux-based service, the pushUser and pushPassword properties should be set to the service account’s credentials.
Grant the service account Modify permissions on the directory of the push redirector.
If the push redirector is currently running, restart it.

You have set up SPNEGO authentication with the push redirector.

Push redirector troubleshooting

If you are not sure that the push redirector is running correctly, use the following suggestions to diagnose or resolve the problems.

Can the push redirector connect to all the nodes in the cluster?

If the NexJ application is running on a clustered application server, then the push redirector needs to be set up to connect to all the nodes in the cluster.

Does the log file show that the push redirector has started?

The log file is named nexj.log and is located in the nexj-push-redirector_version/log directory. Look for a string similar to the following:

TEXT

; 15:43:28,420 INFO [..] Connecting push redirector http://<servername>/nexj/ pushRedirect to push server http://<servername>/nexj/push

Is the push redirector is running properly?

Using a web browser, access the push server URL at https://<servername>/nexj/push. The returned web page should display the push redirector URL. The push server URL is the URL specified on the httpURL attribute in the environment or server file for your deployment, followed by the extension “push”. If you receive an HTTP error 500 (internal server error) after a timeout, then the push redirector is not connected.

Are messages being sent between users?

Using two different browser sessions, open the NexJ application as two different test users.
In one browser session, open the Conversations sidebar and send a message from one user to the other test user.
In the other session, open the Conversations sidebar and verify that the message had been received.

Have the web server and application server names been added to your web browser's trusted sites list?

The following procedure is for Microsoft Internet Explorer only.

In Internet Explorer, open the Tools menu and select Internet Options.
The Internet Options dialog opens.
Click the Security tab.
The security options are displayed.
Select the Trusted sites icon, then click Sites.
The Trusted sites dialog opens.
In the Add this website to the zone field, enter the web server URL for your deployment, then click Add.
The URL is added to the list of trusted sites in the Websites field.
In the Add this website to the zone field, enter the application server URL for your deployment, then click Add.
The application server URL is the URL returned after you log into the push redirector login web page.
The URL is added to the list of trusted sites in the Websites field.
Click Close.
The Trusted sites dialog closes.
Click OK.
The changes to the trusted sites list are saved.

Push redirector server sizing

The following table provides recommended sizing for the servers that host the push redirector.

Push servers are lightweight and typically sized similarly to your servers, effectively doubling the number of servers in your web tier.