Push adapter

The Push adapter allows to send push notifications to mobile devices. Currently only android and IOS are supported, but others should be feasible.

Prerequisites

In order for the push adapter to function one should have an application running on either android or ios capable of receiving push notifications. This usually requires having either a developer account with ios and configured push notifications here. Google requires a API key, you can find out here how to get one.

Configuration

AdapterUniqueID

Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements:

START with a letter or _ (underscore)
FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)
IosPrivateKeyAlias Alias is in the keystore containing the private key used to connect to Apple push service
IosPrivateKeyPassword Password of the private key
TrustRemote Ignore validation of remote server certificate
IosProduction Connect to Apple's production push gateway
Google Api Key The key to use to send pushes to Google's GCM gateway
HttpAdapter If Google is used, a reference to a Http Adapter used to delegate the request to

Workflow Settings

A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:

Input Property: the variable containing the instructions the adapter have to execute
Output Property: the variable the adapter will store the response in after execution
Before Adapter Script: script that will be executed before calling the adapter
After Adapter Script: script that will be executed after the adapter fulfilled its task

Request - API

CODE

var msg = {
        aps: {
            alert: "Confirm your authentication request from TrustBuilder",
            sound: 'default',
            mydata: 'some data to be transferred'
        }
    };

// send a push notification to an ios device, the devicetoken is stored in the workitem and if the message couldn't be delived in 5 minutes, Apple can drop it
workItem.pushrequest = tb.mobilePushRequest('ios',workItem.devicetoken,JSON.stringify(msg),300000);

// Same but always deliver
workItem.pushrequest = tb.mobilePushRequest('ios',workItem.devicetoken,JSON.stringify(msg));

var androidMsg = "{\"message\":\"Hello\",\"title\":\"TrustFactor Authentication - click to authenticate.\"}";

// Android message
workItem.pushrequest = tb.mobilePushRequest('android',workItem.deviceId, androidMsg ,300000);

Response - API

Common Properties

The response API can be applied to the variable specified in the "output property" (see "Workflow Settings"): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.

All responses have four properties in common:

status Status flag indicating whether the response is ok (0) or not (1).
substatus Response specific number indicating what the problem was, eg. http status code
message Response specific message in case there was a problem (can be null)
rc Return Code, a human readable code based on the substatus

Response Codes

If all is ok, the status is zero, for non-zero statusses.

Example

Request

CODE

/**
 * We've got everything now prepare the push request
 * @param workItem
 */
function preparePushRequest(workItem) {
    var msg = {
        "aps": {
            "alert": "Confirm your authentication request from TrustBuilder",
            "sound": "default",
            "u": 'my application data"
        }
    };
    // same as the timeout on the session
    workItem.pushrequest = tb.mobilePushRequest(
        workItem.platform, // android or ios
        workItem.device,
        JSON.stringify(msg),
        timeout);
    tb.log('Sending : '+workItem.pushrequest);
}

Response

CODE

/**
 * if push was send ok, goto the next step
 */
function handlePushResponse(workItem) {
    var response = workItem.pushresponse;
    if (response.status == 0){
        return "ok";
    }
    return "error";
}