• Backbone.js Reference /
• Business Logic Reference

Business Logic Reference

Reference

The Business Logic reference is split into two sections:

• Kinvey Requests -- The Kinvey request pipeline and hooks to modify processing
• Support Modules -- The modules available to business logic code

Kinvey Requests

There are two types of business logic requests: collection hooks and custom endpoints. Collection hooks allow server-side processing pre and post data collection requests, while custom endpoints are independent on-demand requests.

A request to the Kinvey service goes through several standardized steps, similar to a pipeline.

Collection Hook Pipeline

For collection hooks, the pipeline is:

1. Requst from client to Kinvey backend
2. Authentication of client (verify that client has access to this backend)
3. Pre-processing hooks
4. Database actions
5. Post-processing hooks
6. Clean-up and response formatting
7. Response is returned to the requesting client

All requests to and from Kinvey execute steps 1, 2, 6 and 7. The other steps are optional. For example, if the response.complete() method is called during pre-processing (step 3), then processing jumps to steps 6 and 7, completing immediately.

You can customize the behavior of this pipeline with the following functions:

These can be modified by clicking on the pre- or post-request buttons on the console, and then selecting the action you want to have Business logic.

Custom Endpont Pipeline

Custom endpoints have a more abbreviated request pipeline:

1. Requst from client to Kinvey backend
2. Authentication of client (verify that client has access to this backend)
3. Custom Endpoint processing
4. Clean-up and response formatting
5. Response is returned to the requesting client

All custom endpoints use the onRequest function for server-side logic:

Parameters

The parameters to all Business Logic hooks are:

Request

The request object has the following fields/values:

Response

The response object has the following fields/values:

The three response functions (complete, continue, and error) should be called following a return statement. For example:

return response.complete(201);

Modules

The following modules are available for use in your JavaScript:

• logger -- Log messages to the Kinvey console.
• collectionAccess -- Access your raw data in MongoDB.
• push -- Send push notifications to user's devices.
• email -- Send email notifications.
• validation -- Validate incoming requests.
• utils -- Various utilities.
• request -- HTTP request module.
• lodash -- Implementation of lodash, a JavaScript toolkit.
• json2csv -- Implementation of json2csv, used for converting JSON to CSV.
• moment -- Implementation of moment.js, used for Date/Time functions.
• moment-timezone -- Implementation of moment-timezone.js, used for timezone processing.
• xml2json -- Implementation of xml2json, used for converting XML to JSON (and vice versa).
• xmldoc -- Implementation of xmldoc, used for parsing XML documents.
• async -- Implementation of async.js, used for asynchronous function processing.
• backendContext -- Provides methods to access information about the current backend context.
• requestContext -- Provides methods to access information about the current request context.
• bluebird -- Promises library
• kinvey -- Kinvey Service API
• twilio -- Integration with Twilio SMS API
• slack -- Integration with Slack meesaging API
• hipchat -- Integration with the HipChat messaging API
• facebookMessenger -- Integration with the Facebook Messenger send API
• watson -- Integration with IBM Watson

Logger

Use the logger module to log a message that you can view in the console. Logging can be filtered and traced to a specific request.

Available Methods:

For example:

var logger = modules.logger;
logger.info('Started BL processing', function(err, result) {
    if (!request.body.name) {
      logger.fatal('Request did not include a name...');
      response.complete(400);
    }
}
 );

...

The logging level (info, warning, error, fatal) is just used in logging and will not affect the request in any way.

Collection Access

Use the collection access module to access your data in MongoDB. collectionAccess provides an asynchronous interface to MongoDB collections.

Available Methods:

All collectionAccess methods are asynchronous, so actions that need data from a collectionAccess method need to be performed in the callback to the method (or in the promise fulfillment function, if using promises).

Below you can see examples of the find(), findAndModify() and update() methods:

find()

// Ignore the incoming request and return all items tagged with an age greater than 10
modules.collectionAccess.collection('myCollection').find({"age": {"$gt": 10}}, function (err, docs) {
  if (err) {
    logger.error('Query failed: '+ err);
  } else {
    response.body = docs;
    response.complete(200);
  }
});

findAndModify()

// Find the user with the highest score on Easy difficulty and update his "firstPlace" to true
var myCollection = modules.collectionAccess.collection('myCollection');
myCollection.findAndModify({"difficulty": "Easy"}, [["score", -1]], { $set: { "firstPlace": "true" }}, function (err, docs) {
  if (err) {
    logger.error('Query failed: '+ err);
  } else {
    response.body = docs;
    response.complete(200);
  }
});

update()

// Find all documents where the "age" has value of 18 or higher and set their "isAdult" to "true"
var myCollection = modules.collectionAccess.collection('myCollection');
myCollection.update({"age": {"$gt": 17}}, { $set: { "isAdult": "true" }}, { "multi": true }, function (err, status) {
  if (err) {
    logger.error('Query failed: '+ err);
  } else {
    response.complete(200);
  }
});

ObjectID warning

When an entity is created without explicitly specifying an _id attribute, that entity's _id will not be a regular JavaScript string; instead, it will be represented as a Kinvey ObjectID, which is a special internal object type. When searching for an entity with an _id attribute that is stored as an ObjectID, you can use the collectionAccess.objectID helper function to convert your string into the special type.

Example using String _id

// To find an entity that has a String _id field, we must use the same to query for it
modules.collectionAccess.collection('myCollection').findOne({ _id: myIncomingStringId }, function(err, result) {
    ...
});

Example using ObjectId _id

// To find an entity that has an ObjectID _id field, we must use the same to query for it
modules.collectionAccess.collection('myCollection').findOne({ _id: modules.collectionAccess.objectID(myIncomingStringId) }, function(err, result) {
    ...
});

Promises API

All asynchronous collectionAccess methods have sibling methods that return Promise objects. (For more info on promises, see the Bluebird section below). The method signatures are the same as the callback-style methods, except "Async" is appended to the method name and there is no callback argument passed. Methods returning promises are:

Here's an example similar to the one above, using findAsync() to return a Promise:

// Ignore the incoming request and return all items tagged with an age
// greater than 10.
var findData = modules.collectionAccess.collection('myCollection').findAsync({"age": {"$gt": 10}});

findData.then(function (docs) {
    response.body = docs;
    response.complete(200);
},
function(err){
    logger.error('Query failed: '+ err);
});

Push

Use the push module to send a push notification to a device registered with your app.

Available Methods:

For example, to send a broadcast message:

    var push = modules.push;
    if (request.body.sendMessageToAll){
        push.broadcastMessage(request.body.message, function(err, result) {
           response.continue();
         });
    }

The users argument to send is either an array of Kinvey User documents or a single user document. The message will be sent to all iOS or Android devices that are contained in the documents in users. You can query the user collection with the collectionAccess module to get a list of users.

For example:

    var push = modules.push, collectionAccess = modules.collectionAccess;
    collectionAccess.collection('user').find({"firstName": request.body.firstName}, function (err, userColl) {
      if (err) {
        logger.error('Query failed: '+ err);
      } else {
        userColl.forEach(function (user) {
          logger.info('Pushing message to ' + user);
          push.sendMessage(user, "People who are named " + user.firstName + " are awesome!", function(err, result) {
          });
        });
      }
    });

Payloads

The methods sendPayload and broadcastPayload allow for more robust push messages. For iOS, the payload consists of two arguments, iOSAps and iOSExtras. iOSAps is a JSON object that can have the following properties:

iOSExtras is a JSON object with custom name-value pairs to be included in the push notification.

For Android, the payload is contained in the androidPayload attribute, which is any JSON object to be sent to Google Cloud Messaging (GCM).

Each of the arguments above are null-safe.

For example, to send a broadcast with payloads:

var iOSAps = { alert: "You have a new message", badge: 2, sound: "notification.wav" }
var iOSExtras = {from: "Kinvey", subject: "Welcome to Business Logic"}
var androidPayload = {message: "You have a new Message", from: "Kinvey", subject: "Welcome to BL" }
var push = modules.push;
push.broadcastPayload(iOSAps, iOSExtras, androidPayload, callback);

Email

Use the email module to send email to any valid email address.

Available Methods:

For example, to send a text email:

    var email = modules.email;
    email.send('my-app@my-app.com',
               request.body.friendEmail,
               'Join my octagon in my-app!',
               "You've been invited to join " + request.body.name + "'s octagon in my-app!", function(err, result) {
               response.continue();
               });

To send an HTML email, it is important to note that the reply-to must be included; if you want the reply-to to be the same as the from address, you can either also pass the from address in the reply_to argument, or simply pass a null value (which will default the reply to to the from address). For example:""

    var email = modules.email;
    email.send('my-app@my-app.com',
           request.body.friendEmail,
           'Join my octacgon in my-app!',
           "You've been invited to join " + request.body.name + "'s octagon in my-app!",
           null,
           '<html>You've been invited to join  <b>'+request.body.first_name+'</b>'s octagon in my-app!</html>', callback);

Validation

Use the validation module to validate input on a request.

Available Methods:

For example:

var validation = modules.validation
  , result, spec, doc;


spec = {
    someRequiredField: {required: true},
    age: {min: '0', max: '200'},
    someTextField: {pattern: ['a regular expression']}
};

doc = request.body;

result = validation.doValidation(spec, doc);

if(result.length > 0) {
  response.body.debug = result;
  response.complete(400);
} else {
  response.continue();
}

The spec syntax is an object where the properties are fields that are expected to be present in the doc argument to doValidation, and the values are validation operators. If an property is missing, doValidation returns a string describing the failure. Extra properties are allowed to be present in doc. A property is allowed to have multiple operators

Allowed validation operators are:

Utils

Use the utils module for various utility helper functions.

Available Objects:

renderTemplate

Used to render templates using the mustache template engine.

For example:

var render = modules.utils.renderTemplate
  , spec
  , output;

spec = 'Hello there {{data.name}} happy {{data.age}}th birthday!';
output = render(spec, {data: request.body});
response.body = {"message": output};
response.complete(200);

The render method can take either a plain text or HTML-formatted string as a value for spec.

A complete guide on how to use mustache can be found in the Mustache Manual.

tempObjectStore

A key-value store for persisting temporary data between a pre- and post-hook. tempObjectStore is an ephemeral store that only lives for the duration of a single request, but will allow for data that is written in a pre-hook to be read in a post-hook. The object implements three methods:

For example, to store an item in an onPreSave hook:

function onPreSave(request, response, modules) {
  var tempObjectStore = modules.utils.tempObjectStore;
  tempObjectStore.set('token', request.body.token);
  response.continue();
}

Then, to retrieve it:

function onPostSave(request, response, modules) {
  var tempObjectStore = modules.utils.tempObjectStore;
  var token = tempObjectStore.get('token');
  response.body = { "message": "Object for token " + token + " was saved successfully."};
  response.complete();
}

base64

A utility for encoding utf8 strings to base64, and decoding base64 strings to utf8.

For example, to encode a string to base64:

function onPreSave(request, response, modules) {
  var encoded = modules.utils.base64.encode(request.body.username);
  request.body.username = encoded;
  response.continue();
}

To decode a string from base64:

function onPreSave(request, response, modules) {
  var decoded = modules.utils.base64.decode(request.body.username);
  request.body.username = decoded;
  response.continue();
}

Convert

A utility for converting data.

For example, to convert a date to to a Kinvey Date string:

myDate = new Date();
kinveyDate = modules.utils.convert.toKinveyDateString(myDate);

To convert a Kinvey Date string to a JavaScript date object:

myDate = modules.utils.convert.fromKinveyDateString(kinveyDate, 'date');
// note:  this could also be accomplished via modules.utils.convert.fromKinveyDateString(kinveyDate);

To convert a Kinvey Date string to a moment:

myMoment = modules.utils.convert.fromKinveyDateString(kinveyDate, 'moment');

To convert a Kinvey Date into a standard ISO-8601 date string

myDateString = modules.utils.convert.fromKinveyDateString(kinveyDate, 'string');

Request

Available Methods:

callback is a function taking 3 arguments, error, response and body:

• error -- Set to null if no error, otherwise set to an error object with the failure
• response -- The full response from the server (containing headers, body and status)
• body -- The returned HTTP body from the server.

options is an object that may contain the following properties:

For example:

var req = modules.request;
req.get({uri: 'http://api.example-api.com/v1/abcdefg',
             method: 'GET'},
            function(error, res, body){

            if (error){
                response.body = {error: error.message};
                response.complete(434);
            } else {
                response.body = JSON.parse(body);
                response.complete(res.status);
            }
});

The body value passed to your callback will be encoded differently based on the data returned by the API you are requesting data from. All Kinvey libraries expect the data returned via response.body to be application/json, so you should convert the response from request to a JavaScript object prior to assigning it to response.body. If you've used the json property in the options object, then this step has already been completed. Otherwise, for JSON data you need to call JSON.parse(body).

Security (SSL)

The request module supports SSL encryption. To enable SSL encryption, simply specify a uri starting with https://. The module will use SSL if required. By default the request module does not validate SSL certificates, which decreases the security of https requests. To force SSL verification set strictSSL to true in your options. This is recommended for the best security, but may limit your ability to access some servers.

Promises API

All request methods have sibling methods that return Promise objects. (For more documentation, see the Bluebird section below). The method signatures are the same as the callback-style methods, except "Async" is appended to the method name and there is no callback argument passed. Methods returning promises are:

An example using the request module to return a Promise:

var req = modules.request;
var fetchData = req.getAsync({uri: 'http://api.example-api.com/v1/abcdefg'});

fetchData.then(
   function(res, body){
       response.body = JSON.parse(body);
       response.complete(res.status);
   },
   function(error){
       response.body = {error: error.message};
       response.complete(434);
   }
);

For more information on the request module, see Request -- Simplified HTTP request method.

Lodash

A fork of underscore.js, lodash is a JavaScript toolkit which provides cross-platform methods for manipulating objects, collections, and more in a performant fashion.

The following methods from v4.0.0 of lodash are supported in Kinvey Business Logic:

The lodash module also includes the following properties:

For example:

function onPreFetch(request, response, modules){
  var _ = modules.lodash; // Get lodash reference
  var myArray = [1, 2, 3];

  var reversedArray = _.reverse(myArray); // [3, 2, 1]
}

For reference on the lodash API and each of the methods listed above, see the lodash documentation.

json2csv

json2csv is a module that converts JSON to CSV.

Signature: json2csv(options, callback)

Example usage:

function onPostFetch(request, response, modules) {
  var json2csv = modules.json2csv;
  var fields = ['name', 'price']; // CSV columns
  var bookResults = [
    {
      name: "Publication 1",
      price: 19.50
    },
    {
      name: "Publication 2",
      price: 4.00
    }
  ]; // These objects represent results from a Kinvey collection fetch

  bookJson = JSON.stringify(bookResults); // json2csv input be serialized JSON

  // Convert
  json2csv({
    data: bookResults,
    fields: fields
  }, function(err, csv) {
    if (err)
      response.complete(500);

    var returnResult = { csvStringData: csv };

    response.body=returnResult;
    response.complete(200);
  });
}

The contents of csvStringData would be:

name, price
"Publication 1", 19.50
"Publication 2", 4.00

You can also use dot notation to create CSV columns with nested JSON fields:

function onPostFetch(request, response, modules) {
  var json2csv = modules.json2csv;
  var fields = ['book.name', 'book.publisher', 'price', 'type']; // CSV columns
  var bookResults = [
    {
      book: {
        name: "Publication 1",
        publisher: "Acme Publishing, Inc"
      },
      price: 19.50,
      type: "paperback"
    },
    {
      book: {
        name: "Publication 2",
        publisher: "Acme Publishing, Inc"
      },
      price: 4.00,
      type: "paperback"
    }
  ]; // These objects represent results from a Kinvey collection fetch

  bookJson = JSON.stringify(bookResults); // json2csv input must be serialized JSON

  // Convert
  json2csv({
    data: bookResults,
    fields: fields
  }, function(err, csv) {
    if (err)
      response.complete(500);

    var returnResult = { csvStringData: csv };

    response.body=returnResult;
    response.complete(200);
  });
}

The contents of csvStringData would be:

book.name, book.publisher, price, type
"Publication 1", "Acme Publishing, Inc", 19.50, "paperback"
"Publication 2", "Acme Publishing, Inc", 4.00, "paperback"

For more examples and a complete options reference, see the json2csv Github page.

Moment

A date library for parsing, validating, manipulating, and formatting dates, using moment.js. A new moment can be initialized with no arguments (to get the current date and time) or with the following arguments:

• date -- A string date or JavaScript Date()
• format -- A moment.js format string
• locale -- The locale of the moment

The following methods from v2.10.3 of moment.js are supported in Kinvey Business Logic:

In addition, the moment module supports moment duration objects with the following methods:

To declare a new moment object, create a modules.moment, and call any of the supported methods on that object.

function onPreFetch(request, response, modules){
  var theMoment = modules.moment();

  theMoment.add('days', 7);

  response.body={"thisTimeNextWeek" : theMoment};
  response.complete(200);
}

To declare and use a duration object, create a modules.moment object and invoke the duration method, and then call any of the supported methods on the duration object.

function onPreFetch(request, response, modules){
  var duration = modules.moment().duration(24, 'hours');

  response.body={"duration" : duration.humanize()};
  response.complete(200);
}

For reference on the moment.js API and each of the methods listed above, see the moment.js documentation.

Moment Timezone

An extension of moment.js which adds extra methods for parsing and displaying dates in any time zone. The moment-timezone constructor takes the same parameters as moment but uses the final paremter as a time zone identifier.

var theMoment = moment.tz(1453234509, 'America/New_York').format() // 1970-01-17T14:40:34-05:00

In addition to all of the moment.js methods above, the following methods from v0.5.0 of moment-timezone.js are supported in Kinvey Business Logic:

The moment-timezone.js module also supports Zone object, which offers the following methods:

To declare a new moment-timezone object:

function onPreFetch(request, response, modules){
  var theMoment = modules.momentTimezone.tz('America/New_York'); // Creates a new moment using current date/time and 'America/New_York' time zone

  theMoment.add('days', 7);

  response.body={"thisTimeNextWeekWithTimeZone" : theMoment.format()};
  response.complete(200);
}

To modify the time zone of an existing moment:

function onPreFetch(request, response, modules){
  var theMoment = modules.momentTimezone('2000-01-01').tz('America/New_York');

  response.body={"dateWithTimeZone" : theMoment.format()};
  response.complete(200);
}

To use the zone namespace:

function onPreFetch(request, response, modules){
  var offset = modules.momentTimezone.tz.zone('America/New_York').offset(1453236443); // 480
  var name = modules.momentTimezone.tz.zone('America/New_York').name; // America/New_York

  response.body={
    "tzOffset" : offset,
    "tzName" : name
  };
  response.complete(200);
}

For reference on the moment-timezone.js API and each of the methods listed above, see the moment-timezone.js documentation.

xml2json

xml2json is a utility module which converts XML to JSON and JSON to XML. The following methods from v0.9.0 of xml2json are supported in Kinvey Business Logic:

Example usage:

function onPreFetch(request, response, modules){
  var parser = modules.xml2json;

  // xml to json conversion
  var xml = "<foo>bar</foo>";
  var jsonResult = parser.toJson(xml); // Returns stringified JSON

  response.body=JSON.parse(jsonResult); // { foo: bar }
  response.complete(200);
}

toJson options param defaults:

var options = {
    object: false,
    reversible: false,
    coerce: false,
    sanitize: true,
    trim: true,
    arrayNotation: false
};

For reference on the xml2json API and each of the methods listed above, see the xml2json Github page.

xmldoc

xmldoc is a module that allows parsing of XML documents.

function onPreFetch(request, response, modules){
  var xmldoc = modules.xmldoc;
  var document = new xmldoc.XmlDocument('<hello>world</hello>');
  ...
}

Example usage:

function onPreFetch(request, response, modules){
  var xmldoc = modules.xmldoc;
  var document = new xmldoc.XmlDocument('<foo>bar</foo>');

  var returnResult = {};
  returnResult.name = document.name; // foo
  returnResult.val = document.val; // bar

  response.body=returnResult; // { name: 'foo', val: 'bar' }
  response.complete(200);
}

For reference on the xmldoc API and each of the methods and properties above, see the xmldoc Github page.

Async

Async is a utility module which provides straight-forward, powerful functions for working with asynchronous JavaScript, using async.js. The following methods from v1.4.2 of async.js are supported in Kinvey Business Logic:

For example:

function onPreFetch(request, response, modules){
  var async = modules.async;
  var body = response.body;
  var moment = modules.moment().format();
  var logger = modules.logger.error;
  var debug = modules.logger.info;
  var req = modules.request;

  var req = modules.request;
  var getDate = function(callback) {
    modules.request.get('http://date.jsontest.com', function(error, resp, body){
      if (error){
        callback(error);
      } else {
        callback(null, (JSON.parse(body)).date);
            }
    });
  };

  var getTime = function(callback) {
    req.get('http://time.jsontest.com', function(error, resp, body){
      if (error){
        callback(error);
      } else {
        callback(null, (JSON.parse(body)).time);
            }
    });
  };


  var callback = function(error, results) {
    if (error) {
      response.body = {error: error.message};
      response.complete(400);
      return;
    }
    response.body.date = results[0];
    response.body.time = results[1];
    response.complete(200);
    return;
  };

  async.parallel([getDate, getTime], callback);
}

For reference on the async.js API and each of the methods listed above, see the async.js Github page.

backendContext

Used to return data and perform functions against the current backend context.

One common use case for these functions is for calling requests against the current backend to provide a method to obtain the correct authentication credentials. This allows for BL scripts to be migrated from backend to backend without code changes, such as in the case of seperate development and production backends.

function onRequest(request, response, modules){

  var context = modules.backendContext;
  var utils = modules.utils;

  var appKey = context.getAppKey();
  var masterSecret = context.getMasterSecret();

  var uri = 'https://' + request.headers.host + '/appdata/'+ appKey +'/myCollection/';
  var authString = "Basic " + utils.base64.encode(appKey + ":" + masterSecret);
  var requestOptions = {
    uri:uri,
    headers: {
      "Authorization":authString
    }
  };

  var auth = modules.request.get(requestOptions,function(error, res, body){
    if (error){
      response.error(error);
    } else {
      response.body = JSON.parse(body);
      response.complete(res.status);
    }
  });

}

requestContext

Used to return data and perform functions against the current request context.

Custom Request Properties

Kinvey Client libraries provide API to pass Custom Request Properties when communicating with Kinvey services. The requestContext module provides methods to read and manipulate those properties.

The Custom Request Properties object will be available throughout the entire Kinvey Request pipeline. For example, you can add/modify a Custom Request Property in a preFetch hook, and those changes will be available in a postFetch hook on the same transaction.

Example Code

//Assume {officeLocation: 'Paris'} was provided as the Custom Request Properties object

function onPreFetch(request, response, modules){

  var requestContext = modules.requestContext;
  var officeLocation = requestContext.getCustomRequestProperty('officeLocation');

  if (officeLocation === 'Paris'){
        try {
           //Perform some 'preprocessing' logic for requests from Paris
           //...
           //Set didPreprocess to true in the Custom Request Properties
           requestContext.setCustomRequestProperty('didPreprocess', true);
        } catch (error) {
         //If preprocessing fails due to an error, set didPreprocess to false
         requestContext.setCustomRequestProperty('didPreprocess', false);
        }  
  }

  //Continue the execution
  response.continue();

}

The above code checks the Custom Request Properties for a property, officeLocation. If the officeLocation is Paris, then some custom pre-processing is done as part of the pre-fetch hook. If the pre-processing succeeds, we set didPreprocess to true in the Custom Request Properties. If an error is encountered during preprocessing, we set didPreprocess to false.

We could implement a post-fetch hook that looks for the didPreprocess flag on the Custom Request Properties object:

//Assume {officeLocation: 'Paris', didPreprocess: true} was provided as the Custom Request Properties object

function onPostFetch(request, response, modules){

  var requestContext = modules.requestContext;
  var officeLocation = requestContext.getCustomRequestProperty('officeLocation');
  var didPreprocess = requestContext.getCustomRequestProperty('didPreprocess');

  if (officeLocation === 'Paris'){
        if (didPreprocess === true) {
            //perform some post-processing specific to pre-process success
        } else {
            //optionally perform some other post-processing
        }
  }

  //Finish the execution
  response.complete(200);

}

For details on passing Custom Request Properties to Kinvey backend services, please see the API reference for the Kinvey Client Library of your choice.

Client App Version

All of the Kinvey client libraries provide API to pass a client-app-specific version string (for implementation details, see the Kinvey Dev Center reference documentation for the library of your choice). The requestContext module provides a clientAppVersion namespace, which includes API to retrieve details about the version of the client app making the request.

The requestContext.clientAppVersion namespace provides the following methods:

Example Code

Assuming a client app version string of "1.1.5":

function onRequest(request, response, modules){
  var context = modules.requestContext;

  var majorVersion = context.clientAppVersion.majorVersion(); //majorVersion will be 1
  var minorVersion = context.clientAppVersion.minorVersion(); //minorVersion will be 1
  var patchVersion = context.clientAppVersion.patchVersion(); //patchVersion will be 5

  if (majorVersion < 2) {                                //will be true
      //Perform some version 1 compatible logic
      if ((minorVersion >= 1) && (patchVersion === 5)) {    //Will be true
          //perform some logic for a specific patch release
      }
  } else if (majorVersion >= 2) {                        //Will be false
      //Perform some version 2+ compatible logic
  }


  //Finish the execution
  response.complete(200);

}

Assuming a client app version string of "1.0.1-beta":

function onRequest(request, response, modules){
  var context = modules.backendContext;

  var versionString = context.clientAppVersion.stringValue(); //versionString will be "1.0.1-beta"
  var majorVersion = context.clientAppVersion.majorVersion();   //majorVersion will be 1
  var patchVersion = context.clientAppVersion.patchVersion();   //patchVersion will be NaN

  if (majorVersion < 2) {                         //Will be true
      //Perform some version 1 compatible logic
      if (patchVersion > 1) {                        //Will be FALSE as patchVersion is NaN
          //Perform some patch-specific logic
      }
  }

  if (versionString.match("beta") !== null){    //Will be true
      //Perform some beta-specific logic
  }

  //Finish the execution
  response.complete(200);

}

Bluebird (Promises)

Promises functionality is provided through the Bluebird library. Promises present an alternative to callbacks for managing asynchronous program flow. They allow asynchronous activities to be 'chained' together rather than 'nested' as callback arguments to asynchronous functions. This can allow code that executes asynchronously to read like synchronous code.

For examples and further reading, see:

• Promises Overview (from promisejs.org)
• Promises Patterns (from promisejs.org)
• Promises Nuggets
• Callbacks, Promises and Coroutines (Oh, my!)

For specific information about the Bluebird library, refer to the following:

• Bluebird github page
• Bluebird API reference

Promises in Kinvey-provided modules

The Kinvey-provided modules that expose async APIs also have "promisified" methods that will return promises instead of requiring callbacks as parameters. See the examples in the Collection Access and Request modules.

Kinvey

The Kinvey module provides APIs to access Kinvey-specfic data and features.

Kinvey Entity

A Kinvey Entity is a JSON object containing Kinvey-specific metadata for use with AppData collections. Kinvey Entities also contain methods to manipulate Kinvey metadata.

The Kinvey module provides the following Kinvey Entity methods:

For example, to create a Kinvey Entity with only Kinvey metadata:

function onPreFetch(request, response, modules){
  response.body=modules.kinvey.entity();
  response.complete(200);
}

The response would contain an entity containing no additional attributes, except for Kinvey metatada attributes:

{
  "_acl": {
    "creator": "kid_VT5YYv2KWJ"
  },
  "_kmd": {
    "lmt": "2013-05-08T13:48:36+00:00",
    "ect": "2013-05-08T13:48:36+00:00"
  },
  "_id": "518a57b4d79b4d4308000002"
}

To use your own _id, you can simply pass that ID as a String into the method:

function onPreFetch(request, response, modules){
  var myID = "000-22-2343";
  response.body=modules.kinvey.entity(myID);
  response.complete(200);
}

{
  "_acl": {
    "creator": "kid_VT5YYv2KWJ"
  },
  "_kmd": {
    "lmt": "2013-05-08T13:51:02+00:00",
    "ect": "2013-05-08T13:51:02+00:00"
  },
  "_id": "000-22-2343"
}

You can add Kinvey metatada to your own JavaScript object by passing that object into the function.

function onPreFetch(request, response, modules){
  function employee() {
    this.firstName = "John";
    this.lastName = "Doe";
    this.status = "Active";
    this.dob = "5/5/1985";
    this.doh = "1/12/2012";
  }

  response.body=modules.kinvey.entity(new employee());
  response.complete(200);
}

This example results in the Kinvey metadata being added to your employee object.

{
  "firstName": "John",
  "lastName": "Doe",
  "status": "Active",
  "dob": "5/5/1985",
  "doh": "1/12/2012",
  "_acl": {
    "creator": "kid_VT5YYv2KWJ"
  },
  "_kmd": {
    "ect": "2013-05-08T13:57:11+00:00",
    "lmt": "2013-05-08T13:57:11+00:00"
  },
  "_id": "518a59b7d79b4d4308000003"
}

Note that you can add properties directly to a Kinvey Entity and pass it directly into a collectionAccess method that takes an entity as an argument:

function onPreFetch(request, response, modules) {
    var entity = modules.kinvey.entity();
    entity.name = "Sachin";
    modules.collectionAccess.collection("People").save(entity, function(err){
        if (err !== null){
            //handle error
        }else{
            response.continue();
        }
    });
}

_acl Namespace

Kinvey Entities returned from entity() are also imbued with an _acl namespace containing methods for accessing that entity's user and group access privileges:

ACL method chaining

All _acl methods can be chained to the modules.kinvey.entity() by chaining the _acl namespace followed by the desired method. Furthermore the _acl modifier methods (those that return the _acl namespace) can be chained to each other. Since the _acl modifier methods return the _acl namespace, there's no need to restate the _acl namespace for the next method in the chain.

For example, the following line will create a Kinvey Entity, add a reader, add a writer, then return all readers. NOTE: Since getReaders() returns an array, no futher _acl methods can be chained to it.

modules.kinvey.entity(someObject)._acl.addReader(readUserId).addWriter(writeUserId).getReaders();

Example

The example below uses kinvey.entity()._acl along with the Request Context module to grant write access on the requested entity to the user making the request:

function onPreFetch(request, response, modules) {
    var currentUser = modules.requestContext.getAuthenticatedUserId();
    var collectionName = request.collectionName;
    var entityId = request.entityId;
    modules.collectionAccess.collection(collectionName).findOne({"_id":entityId}, {}, function(err, doc){
          if (err !== null){
            //handle error
          } else if (doc) {

            var entity = modules.kinvey.entity(doc)._acl.addWriter(currentUser);
            //Note we directly pass the Kinvey Entity to the save method.
            modules.collectionAccess.collection(collectionName).save(entity, function(err){
              response.continue();
            });
          } else {
                  // entity not found
                  response.error("Entity not found");
                }
    });
}

Twilio

The Twilio module provides support for integrating with Twilio for outbound SMS support along with communications functions. This library exposes official Node Twilio Library The following methods from v2.5.1 of node-twilio are supported in Kinvey Business Logic:

For example:

function onPreFetch(request, response, modules){
  //require the Twilio module and create a REST client
  var twilio = modules.twilio('ACCOUNT_SID', 'AUTH_TOKEN');

  //Send an SMS text message
  twilio.sendMessage({

    to:'+16175551242', // Any number Twilio can deliver to
    from: '+15085551234', // A number you bought from Twilio and can use for outbound communication
    body: 'Sending an SMS note.' // body of the SMS message

  }, function(err, responseData) {
    if (err) {
      return response.error(err);
    } else {
      modules.logger.info(responseData);
      response.body = {sentSMS: true}
      return response.complete(200);
    }
});
}

For reference on the twilio-node API and each of the methods listed above, see the twilio-node documentation.

Slack

The Slack module provides support for integrating with Slack via the Slack Web API. This library exposes the Slack.js library. The following methods from v7.5.6 of slack are supported in Kinvey Business Logic:

For example, to send a message to a channel or user:

function onPreFetch(request, response, modules){
  //require the Slack module
  var slack = modules.slack;

  //Send a chat message
    slack.chat.postMessage({
      token: 'someaccesstoken',
      channel: '@someuser',
      message: 'Can you attend a meeting at 9:00 AM?'
      }, function(err, data) {
        if (err) {
          return response.error(err);
        }
       response.body = data;
       response.complete();
   });

}

For reference on the slack API and each of the methods listed above, see the slack.js documentation.

HipChat

The HipChat module provides support for integrating with HipChat. This library exposes the hipchat-client library. The hipchat client exposes access to rooms and users APIs.

The following methods from the rooms object of v1.0.5 of hipchat-client are supported in Kinvey Business Logic:

The following methods from the users object of v1.0.5 of hipchat-client are supported in Kinvey Business Logic:

For example, to send a message to a channel:

function onPreFetch(request, response, modules){
  //require the HipChat module
  var HipChatClient = modules.hipchat;

  var hipchat = new HipChatClient('auth_token');

  hipchat.api.rooms.message({
    room_id: 'Frontend',
    from: 'HipChat Client',
    message: 'Hello world!'
  }, function (err, res) {
     if (err) {
       return response.error(err); }
     }
     response.body = res;
     response.complete();
});
}

For reference on the slack API and each of the methods listed above, see the hipchat-client documentation.

Facebook Messenger

The Facebook Messenger module provides support for integrating with the Facebook Messenger Send API. This library exposes the facebook-send-api library. The following methods from v1.0.3 of facebook-send-api are supported in Kinvey Business Logic:

For example, to send a message to a channel or user:

function onPreFetch(request, response, modules){
  //require the Facebook Messenger module
  var token = 'xyz';
  var fb = modules.facebookMessenger;
  var FBPlatform = new fb(token);

  FBPlatform.sendTextMessage('someSenderId', 'hello');
  response.complete();
}

For reference on the slack API and each of the methods listed above, see the Facebook Send API documentation.

IBM Watson

The Watson module provides support for integrating with the IBM Watson APIs. This library exposes the watson-developer-cloud library. The following methods from v1.12.2 of watson-developer-cloud are supported in Kinvey Business Logic:

For example, to use the conversation service to determine the intent of a message:

function onPreFetch(request, response, modules){
  //require the watson module
  var watson = modules.watson;

  var conversation = watson.conversation({
    username: '<username>',
     password: '<password>',
     version: 'v1',
     version_date: '2016-07-01'
  });

  conversation.message({
  input: 'What\'s the weather?',
  workspace_id: '<workspace id>'
  }, function(err, res) {
     if (err) {
       response.error(err);
     } else {
       response.body = res;
       response.complete();
     }
});
}

For reference on the slack API and each of the methods listed above, see the watson-developer-cloud documentation.