Push Service (Client)

The UBIK^® push service is a mechanism to ensure the clients always receive certain information pushed by the push web service.

The client part of the push service runs in the background, independently of the content service. When active, it periodically polls the push web service for new updates. Once such updates are received, the clients react accordingly based on the information contained in them. Some examples are updating content and switching clients into different sync modes.

Push service settings

The following settings are used in order for the push service to function properly.

Name	Purpose
PushServerName	Name of the server to connect to for push updates
PushPortNumber	Port number to use when connecting to the push server (optional)
UBIKPushService	Name of the UBIK push service
ActivatePushService	Whether UBIK^® should run with/without the push service.

Changing the value of ActivatePushService could potentially start/stop the push service.

Background polling service

As mentioned, a background polling service is responsible for communicating with the push web service and getting push updates. This service is started once users successfully log in and will keep running until they are logged out.

On Android and iOS the Polling will continue while UBIK is in the background and/or the device is asleep, but at a deduced frequency. On Android it is around 15 minutes. On iOS it depends on how much the App is used, the frequency can range from 15 minutes to a couple of hours.

There are two types of push communication involved here, namely

Updating push parameters;
Updating push data

Updating push parameters

There are different push criteria that define which data should be pushed to which clients. As a result, the push web service requires a set of push parameters which can be used to check against these criteria.

The client polling service, in order to always get the intended push data, has to keep this set of parameters up-to-date and use them in the push data updating.

During maintaining the push parameters, the following information might be collected by UBIK^® and used as the parameter values:

User name;
Device ID;
UBIK^® application name and context name;
Current location;
etc.

Updating push data

The main job of the service is to get push data once it's ready to be pushed from the server. And the service is not interested in getting push data it has received before.

To achieve this, the service repeats (e.g. every 10 seconds) the following tasks:

Frequently sending the client's actively maintained push parameters (types and values) and the last push status ID to the push web service;
Recording the status ID in the received push update as the last push status ID;
Passing on the data in the received push update so that UBIK^® can process it.

Processing push data

Notification for Received Push Data

After receiving push data, UBIK^® processes it and potentially performs different follow-up tasks.

The currently known types of push data and their intended client actions are described in the following subsections.

Updating content hierarchy

Upon receiving such push data, UBIK^® tries to update the content hierarchy as the parameters in the push data indicate. This can lead to various scenarios such as:

Update of a single object;
Removal of a single object;
Update of a single object and all its children;
Update of root objects;
Update of infrastructures;
etc.

In case there are uncommitted changes involved in the update, UBIK^® performs the update while preserving the changes. This applies for all the sync modes.

Updating Meta Definitions

Error Notification for Conflict during Updating Meta Definitions

Upon receiving such push data, UBIK^® tries to update all the Meta Definitions. If the update is successful, root objects and infrastructures are then updated as well, and UBIK^® is automatically switched to the automatic sync mode.

In case there are uncommitted changes, the followings apply depending on the sync mode at that point of time.

Automatic mode: Changes are committed automatically and the updates are done afterwards;
Other modes: Updates can not proceed (changes will be lost otherwise) and an error notification is shown.

Meta definition pushes are not yet supported by the WinX client.

Updating device status

Error Dialog for Conflict during Preparing for Maintenance

Upon receiving such push data, UBIK^® tries to update the status of the device. Currently, the only known status is maintenance. This means the server will be under maintenance and unreachable soon. Therefore, UBIK^® should be switched to offline mode.

In case there are uncommitted changes, the followings apply depending on the sync mode at that point of time.

Automatic mode: Changes are committed automatically and UBIK^® is switched to offline mode;
Other modes: A dialog is shown to let the users decide whether to commit their changes or not. Changes are, of course, only committed with users' consent. But UBIK^® is switched to offline mode either way.

Device status pushes are not yet supported by the WinX client.

Popup dialogs

There are three sub types of this push:

Emergency popup
Failure popup
Important information popup

Upon receiving such a push, a dialog with the corresponding style is shown to the user. All these popups can also contain a content/document. In either case, the associated object will be downloaded as soon as the push is received and the button text will be updated accordingly. The possible button states are:

OK: If the popup contains only text;
Waiting/Downloading/Detail: If there is an object associated and the download is pending/on-going/successful;
Close: If the associated object somehow cannot be downloaded. The detailed error(s) is/are displayed as notification(s) in this case.

Once the user has confirmed the popup by clicking the OK/Detail button, it is considered successful and won’t be received again. In the case of a Detail button, the associated object is opened in either the UBIK^® content browser or a third party document viewer.

Users can only dismiss the dialog by clicking the OK/Detail/Close button. The Android back button is disabled when such a popup dialog is shown.

Popup dialog pushes are not yet supported by the WinX client.

Reacting to processing errors

In the push scenarios described above, once a conflict is detected and can not be resolved (e.g. updating Meta Definitions when there are uncommitted changes in manual sync mode), that particular push is considered as failed to be processed.

During the next push update, all the failed pushes will be reported to the push web service. The result of this is UBIK^® will get these failed pushes again along with the new pushes (if there are any). However, all successful pushes in the previous push update will not be delivered again.

Push related errors

Just like for the content service, various errors can happen when the push service is running. For example,

The push web service is unreachable due to misconfigurations in the settings;
Users are denied of accessing the push web service due to invalid credentials;
The client push service is incompatible with the push web service due to version differences;
etc.

In case such an error occurs, a notification is shown to inform the users so that they can either fix the issue or contact the administrators.