Troubleshooting Push

Push Messaging allows a server to “push” a message to a mobile client, as opposed to the client “pulling” messages from the server. This is achieved through techniques that are dependent on the mobile client platform.

• Android uses Firebase Cloud Messaging (FCM)
• Apple uses Apple Push Notification Service (APNs)
• Windows Runtime uses Windows Notification Service (WNS)
• Windows Phone 8 uses Microsoft Push Notification Service (MPNS)

In the rest of this document we call these services the “Platform Notification Service” or PNS.

This document describes the various steps that are performed to enable Push; what can go wrong and how to fix the problem.

Contents

• Introduction
• Troubleshooting

Introduction

A push message will not always get delivered to a mobile client. Each Platform Notification Service only offers “best effort” to deliver a push message.

One Azure Notification Hub is used by each Touch App as a front-end for the various Platform Notification Services.

This is how the servers connect when using the Touch Apps Server (TAS).

The up arrow from the Apps Server to TAS is only required for Push. The calls from TAS to the Notification Hubs are only required for Push.

Firewalls

TAS and Apps Servers should be protected by firewalls. Push requires a change in the firewall rules.

An Apps Server must be able to call the TAS. The TAS must be able to receive calls from Apps Server and call the Notification Hub for each Touch App.

Each Touch App (e.g. mWorkOrder) must register for Push Notification with the Platform Notification Service (PNS) for each supported client platform.

One Azure Notification Hub must be created for each Touch App. The Notification Hub must be configured with the server connection details obtained from each PNS. These steps should be performed by the maintainers of each Touch App. The URL of the Notification Hub must be made available so that customers firewalls protecting the TAS can be adjusted accordingly.

Each Touch App client must register for push notification with the client’s PNS to obtain a PNS Handle. Any change to the PNS Handle must be communicated back to the TAS using the “Ifs.Cloud.BaseResources.PushRegistry” resource.

Push Registry Resource

The Ifs.Cloud.BaseResources.PushRegistry resource is used to add PNS handles to the Notification Hub and to inform IFS Apps that a client wishes to receive Push Notifications.

The Registry is created, modified and deleted using PUT. The PUT operation first tells the Notification Hub about the PNS handle. If that succeeds, it informs IFS Apps through a ManagePushNotifications call.

Whenever mobile device activates it enables the push and valid date.

IFS Apps Server registration

As mentioned in TAS diagram, the IFS Apps Server must be able to call TAS when it wants to make a Push. IFS Apps Server must be told how to do that.

TAS App Server Session table

TAS may be clustered so the authorization token is stored in the Admin database in app_server_session_tab. This table has the following columns.

• cloud_installation_id (Primary Key)
  The System ID
•  base_url
  The TAS URL sent to IFS Apps Server.
• auth_token
  The authorisation token sent to IFS Apps Server
• started_utc
  The UTC timestamp when the authorisation token was successfully registered with IFS Apps Server.
• starting_utc
  The UTC timestamp when the registration process was last attempted.
  

TAS configuration

The following TAS configuration parameters are important. They are set in the web.config file.

• BaseUrl
  This is the URL sent to IFS Apps Server to call the TAS. In a clustered TAS, this identifies the Load Balancer node.
• LifetimeAppServerSession
  The minimum number of minutes an authorisation token should last.
• MinAppServerRetryInterval
  The minimum number of minutes between registration attempts.
  

TAS System

The IFS User and Password information used to register each system is stored in the service_instance_tab. The important columns for Push are as follows.

• cloud_installation_id (unique)
  The System ID
• ifs_user
  The IFS login ID
• ifs_password
  The encrypted password for the user.

The IFS user and password are used as credentials when calling UplinkServices.RegisterUplinkURL.

This information is set during installation.

It can also be displayed and modified in the TAS Portal.

For an Apps10 system (IFS Applications Version dropdown), there are 2 extra fields for an IFS User and Password.

TAS Recycling

The TAS is hosted within IIS. IIS is configured (by default) to recycle (i.e. restart) the Application Pool “IFS Touch Apps Server” every 1740 minutes.

TAS Registration

TAS will attempt to register its URL with IFS Apps Server the first time each system is used (since the last recycle). It will start the registration in the following cases.

•  There is no row for the system in the App Server Session table.
• The configured BaseUrl is not the same as the base_url in the table.
• At least MinAppServerRetryInterval has elapsed since starting_utc and either there is no started_utc or at least LifetimeAppServerSession has elapsed since started_utc.

One TAS node will successfully modify starting_utc to indicate that a registration has been started. It will then generate a new authorisation token and call RegisterUplinkURL. If that is successful, it will update the App Server Session row with the new auth_token, base_url and started_utc values.

Errors are written to the Log\TASTrace.log file. Look for “Failed to register Downlink Url” or “Failed to save AppServer authorisation token”.

RegisterUplinkURL

Only the user who has been granted the Permission Set FND_TOUCHAPPS_CONFIG can execute this API. By default, the IFSMOBILITY user has rights to perform this API call. The user ‘IFSMOBILITY’ is recommended as the IFS User.

Push notification details are stored in the Oracle table mobile_push_msg_setting_tab. This table has an updated (local time zone) timestamp.

Push Notification

When IFS Apps wants to Push, it reads the Uplink URL information and prepares an appropriate call to the TAS using the Ifs.Cloud.BaseResources.PushNotification resource. The call contains the authentication token.

The Ifs.Cloud.BaseResources.PushNotification resource must first successfully authenticate using the provided token. It then calls the Notification Hub and the Notification Hub calls the Platform Notification Service that eventually calls the mobile device. Errors are communicated back to the caller in the usual way. They are not recorded in TAS.

Troubleshooting

This section will use many terms that are defined in previous sections. Do not just read this section. Go back and read the previous sections.

Let’s start with some simple questions.

• Is this happening all the time or just occasionally?
• Is this a single TAS installation?
• Is this a clustered TAS installation?
• How many TAS installations do you have?
  

Detailed Questions

• Is this happening on all TAS installations?
• What is the firewall configuration on the Apps Server and TAS machines?
  • Is a firewall on any TAS node preventing access from the IFS Apps Server or to the Azure Notification Hubs?
  • Is a firewall on the Apps Server preventing access to the TAS nodes?
• How often is TAS “recycled”?
  • Check IIS on all TAS nodes to find how TAS is recycled. Try restarting the IFS Touch Apps Server Application Pool on all nodes.
• What are the current settings for the TAS parameters?
  • The BaseUrl parameter is used by the IFS Apps Server to call the TAS. Is the URL valid on the Apps Server? Can you “ping” the Uplink machine from the Apps Server machine using this machine name?
• How is each TAS System configured?
  • Use the TAS Portal to check each System. Is the IFS Applications Version Apps10 (or above)? It must be, to support Push. Is the IFS User and Password information set and correct? The User (IFSMOBILITY) must have appropriate access rights in IFS Apps.
•  What are the contents of the App Server Session table?
  • Read app_server_session_tab in the TAS Admin database. Also, note the current UTC timestamp.
    • Does the table exist?
      • If the table is missing, the TAS installation must be upgraded to the latest release (at least 1.17).
    • Does a row for the failing System exist?
      • If not, there are probably TAS recycling problems.
    • How recent is the started_utc timestamp?
      • If it is very old or missing, there is an Apps Server registration problem.
    • Is the starting_utc timestamp after the started_utc timestamp?
      • If so, some registrations have failed. Check the trace log.
    • Compare timestamps and tokens with those stored in IFS Apps.
  • What relevant messages are in the Trace log?
    • The Log\TASTrace.log file contains a record of errors. Does it have any messages starting “Failed to register Downlink Url” or “Failed to save AppServer authorisation token”? Read and record the whole of these messages. Do they help you solve the problem?