Skip to content

Latest commit

 

History

History
89 lines (71 loc) · 3.91 KB

usage.md

File metadata and controls

89 lines (71 loc) · 3.91 KB
Raw

Library Usage

Constructing the Engage Object

At a bare minimum to use this library, you need an Watson Campaign Automation pod number, OAuth Client Id, OAuth Client Secret, and OAuth Refresh Token. (Please see the file preparation.md for instructions on establishing these credentials.) You can create an Engage object like this:

var Engage = require('engage-api');
var engage = Engage({
    pod: 1,
    oAuthClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthClientSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthRefreshToken: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
});

When logging into Watson Campaign Automation, this library requests an OAuth authentication token. By default, this token is cached in memory until it expires so that we do not continue to request new tokens for every API call. However, if you are in a position where you need to run many short-lived API calls, it can be helpful to cache the authentication tokens to disk so that they can be reused. You can do this by adding two additional parameters to your Engage object:

var Engage = require('engage-api');
var engage = Engage({
    pod: 1,
    oAuthClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthClientSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthRefreshToken: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    cacheAccessTokens: true,
    cacheFile: __dirname + '/cache'
});

If you will be working with any Watson Campaign Automation data jobs, you probably also want to specify an Watson Campaign Automation SFTP private key file path. (Again, see preparation.md for more details.) With the SFTP key, the constructor looks something like this:

var engage = Engage({
    pod: 1,
    oAuthClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthClientSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    oAuthRefreshToken: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    sftpPrivateKeyPath: __dirname + '/sftp.key'
});

Calling Watson Campaign Automation API Methods

Once you have an Engage object, you can call a Watson Campaign Automation API method, passing an options object and a callback function:

engage.getListMetaData({listId: 12345}, function(err, list) {
    if (err) {
        console.log('Failed to get list metadata: ' + err);
    } else {
        console.log(JSON.stringify(list));
    }
});

The options object contains all of the parameters for use with the Watson Campaign Automation API method call. The callback function signature may vary based on which API method is being called, but the first argument is always an error value which will be null if the method call is successful or an error string if not.

For an API method which accepts a single, required parameter, the value may be passed directly without an options object wrapping it. For example, the GetListMetaData XML API method demonstrated above only accepts a List Id as its parameter, making the following example equivalent:

engage.getListMetaData(12345, function(err, list) {
    if (err) {
        console.log('Failed to get list metadata: ' + err);
    } else {
        console.log(JSON.stringify(list));
    }
});

For methods with no required parameters, the options object can be omitted entirely:

engage.loadUserProfile(function(err, profile) {
    if (err) {
        console.log('Failed to load profile: ' + err);
    } else {
        console.log(JSON.stringify(profile));
    }
});

The callback can also be omitted, but that is not generally advisable. You should always be checking for failure responses, even if you don't need any data to be returned by your API method call.

Please see the file methods.md for a list of all methods currently supported and their potential parameters.