OL Learn   »   Blog   »     »   Capture OnTheGo notifications

Capture OnTheGo notifications

Avatar

Philippe Fontan

April 27th, 2022

OL Learn Blog Automation

Capture OnTheGo is a powerful eForm solution that allows users to work remotely, even when they are offline. A user may sometimes need to be reminded to fill out one particularly urgent document or be advised that new documents are waiting in the repository. This article explains how to send a notification to a COTG user.

What are notifications?

Notifications are messages that are displayed on a mobile device’s notification area (usually at the top of the screen). You already receive several notifications each day for new emails, tweets, messages, traffic information, etc. Tapping any of these notifications usually opens the associated application to allow you to view the entire message from inside the app.

Capture OnTheGo’s API allows such notifications to be sent to individual users as well as groups. Each notification contains a message: the message can simply be informational (e.g. “Make sure to fill out all documents by 16h00 today.“) or can also include an action link that, when tapping the notification, opens the COTG application with a specific document already loaded.

EDIT: at the time of this writing, notifications are only available when using the Nu-book cloud server. They may eventually make their way into OL’s WordPress-based server as well.

Configuring and using notifications

One of the more obvious uses for notifications is to inform a user that a new document is now available. For instance, in the logistics industry, a driver may need to be informed ASAP that a new stop has been added to the daily route. Sending a notification is the best way to ensure the driver takes a look at the device and reacts accordingly.

On most devices, notifications can be personalized (sound, vibration, etc.) on a per application basis. This is usually done through the device’s preferences, by selecting Notifications and then selecting the application for which the notifications should be customized.

Capture OnTheGo allows several types of notifications to be personalized but for the purpose of this article, we will focus on “Server messages”, which is what we will be sending to the device. To test out the procedure laid out below, you should enable sound for Server messages and select a sound bite that isn’t used for any other type of notification. I selected “Wind Chimes” on my Android device, but if you work in a noisy environment, you may want to select “Cannon”, “Explosion” or, why not, a Metallica sound clip. 

The last thing you need to do for the notifications to reach your device is to make sure you are logged into the COTG application. Note: the application does not have to be open. In fact, to test this procedure, you should open the application, log on and then close the application completely (swipe it out of your running tasks).

Sending a notification from Workflow

Notifications are sent via the COTG REST API. You can therefore use any application that supports REST to send notifications to a user: PostMan, NodeRed, Workflow, etc. 

In this article, we’ll focus on Workflow but the procedure is pretty much identical for any other system.

Let’s say we want to send a notification to user “John.Doe@example.com” that a new document named “Delivery 1234” is now available. Here’s the script we would insert in a Workflow process:

var cotgURL  = "https://svc-us.tureonth.com/WS/Notification.ws";
var storeID  = "examplestore";
var storePW  = "1$4d&8_!JCS)r";

var userName = "John.Doe@example.com";
var docTitle = "Delivery 1234";

// Set REST call's XML Payload
var payload = '';

payload += '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
payload += '<ApolloSendNotificationRequest> <StoreID>'+storeID+'</StoreID> <Password>'+storePW+'</Password>';
payload += '<Recipients><User>' + userName + '</User></Recipients>';
payload += '<Message><Title>COTG Notification</Title><Body>New document ' + docTitle + ' is available. Tap here to open it.</Body>';
payload += '<Action>open.document/?title=' + docTitle + '</Action>';
payload += '</Message></ApolloSendNotificationRequest>';

// Post request
var xhr = new ActiveXObject("Microsoft.XMLHTTP");
xhr.open("POST", cotgURL, false);
xhr.setRequestHeader("Content-Type", "multipart/form-data");
xhr.send(payload);

Watch.Log(xhr.responseText,3);

Note the 3 values declared at the top of the script: they specify the REST API server address, along with your store ID and password. If you don’t know your store ID and password, contact the person in charge of your COTG subscription.

The XML payload

Here is a more legible version of the XML structure sent via the REST API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApolloSendNotificationRequest>
  <StoreID>examplestore</StoreID>
  <Password>1$4d&8_!JCS)r</Password>
  <Recipients>
    <User>John.Doe@example.com</User>
    <User>Jane.Smith@example.com</User>
    <Group>Sales</Group>
  </Recipients>
  <Message>
    <Title>COTG Notification</Title>
    <Body>New document Delivery 1234 is available.</Body>
    <Action>open.document/?title=Delivery 1234</Action>
  </Message>
</ApolloSendNotificationRequest>

The XML payload’s structure is straightforward. Besides the authentication information, it includes a recipients structure, inside which you can have as many <user> and or <group> elements as you want.

Next is a message structure that includes 3 elements: title, body and action. The first 2 are self-explanatory but the optional action element is the more interesting one and requires a bit of an explanation.

action specifies which document should be automatically opened when tapping the notification. Two methods are provided:

Open by ID: open.document/Y7KF5GeUvkiyKAGE1VgSIw
Match by title:  open.document/?title=some title

In the script above, we are using the Match by title method, but we could also have used the Open by ID method by specifying the ID of the document that was sent back by the COTG server when the document was initially sent to it.

How COTG matches documents

When using the Open by ID method, the app looks for that document and that document alone. There can be only one match for an ID since each document has a unique ID. This method is therefore fail-safe and is the preferred method of notifying users of new documents in the repository.

With the Match by title method, the app may find several matches for all specified keywords. When that happens, the user is presented with a list of matching titles from which the proper document can be selected. Note that the matching is case-insensitive and (for non-English languages) accent-insensitive. All documents available for that user that match the specified keywords are presented, even if the documents have not been downloaded yet.

There may be multiple keywords, which can be separated with either a blank space or a plus sign (+). The order of keywords does not matter, but for a title to match, all keywords must be found. Therefore, open.document/?title=my title and open.document/?title=title+my are functionally equivalent and would match both “My Document Title” and “This is the title of my document“.

Tapping the notification

When the device receives the notification, it emits whatever sound you assigned to the Server messages event and displays the message in a pop-up in the notification area. Tapping the message automatically activates COTG, whether it was already running or not.

If no action was specified, COTG simply opens up but does not load any specific document.

If an action was specified in the message, then the proper document is automatically loaded in COTG (or a list of documents to chose from when multiple titles match the action keywords). In all cases, if the selected document has not yet been downloaded, the COTG proceeds to download it automatically before displaying it in the application.

If an action was specified but no matching document could be found, then COTG still opens up but displays an error message.

Conclusion

Adding custom notifications to a COTG workflow makes the entire process more user friendly and helps prevent errors or mistakes. The notifications can be sent to individual users when you want to alert them of new documents, or to a group of users for more generic messages. For instance, an hour before your users end their work day, you could send them a reminder: “The day is almost over: don’t forget to charge you tablet overnight.“. You could even send one-off messages like “Avoid highway 437: major accident“.

Use your imagination and don’t be afraid to test the feature. I believe you’ll find it very helpful.

Tagged in: Capture OnTheGo, COTG, Notifications

Leave a Reply

Your email address will not be published. Required fields are marked *

Cancel