xmpResource Reference

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

The following is a complete reference to the xmpResoruce service provided with XMPL. You can use this service for implementing activities around the project data within AngularJS or Javascript, such as retrieving the ADOR information for a recipient, adding new recipients, sending emails, etc.

Setup

This section discusses setup in an Angular JS environment. For a plain JavaScript, non angular setup, refer to JavaScript Access.

To set up xmpResoruce, you must first include the XMPL javascript code (xmp.min.js, or any other version of it).

Then, in your application module, include a reference to the xmp.services module, which contains the service. For example:

var myApp = angular.module('myApp', ['xmp.services']);

Finally, from any definition that requires the usage of xmpResource, such as directive or service, add it as an injected source. For example:

myApp.controller('aController', 
   ['$scope','xmpResource',function ($scope,xmpResource) {
   // do something with xmpResource
}]);

The Access Object

To carry out the xmpResource tasks, it must have a connection to a certain XMPL server and in it to a certain project (campaign). There are two ways to pass connection data to xmpResource:

1. You can pass an access data object in any method call via an optional options variable.
2. xmpResource has a member named access which holds a default access data object. When methods are called without an access containing options variable, this default is used. The default may be defined at configuration time, or later via setting the access member directly.

An access object looks as follows:

{ 
    url: 'YYYYY',
    accessToken: 'XXXXX', 
    serviceToken: 'ZZZZZ'
}

The url member holds the address of the XMPL server, more precisely its REST services layer base URL.
accessToken is an identifier of the project, and provided so that xmpService knows exactly which project to draw data from. serviceToken is a login key that is retrieved in an initial login process with xmpService.

You can get a definition of the access object to use for your project from Circle. Download an xmpcfg.js file from Circle as explained here and open it in a text editor to review the url and accessToken.

Looking into xmpcfg.js you will see that serviceToken is missing. serviceToken is not initially provided. It is something that you get by making a first login call to xmpResource.

Configuration and Properties

xmpResource allows for an optional configuration. You can configure it in your module definition, using the config method of an AngularJS module. For example, the following configures default access data per the xmpcfg.access object defined in xmpcfg.js:

var myApp = angular.module('myApp', ['xmp.services'])
.config(['xmpResourceProvider', function(inProvider) {
	// xmpcfg.access is defined externally at the xmpcfg.js
    inProvider.configure({
      access:xmpcfg.access
    });
}]);

This sets up a default access object that xmpResource can use to access the remote server. Other members that can be set at configuration time in the same manner are:

• timeout - Timeout for HTTP requests. In milliseconds.
• debugEnabled - Enable debug messages for library. Will be written to console.
• dontCacheGets - Instruction to avoid caching get requests. Use this in case that you are updating the Project data outside of XMPL methods (for example, if the data source is a SQL server that you update from another source).

Any of the initial configuration options becomes a member of the same name of xmpResource that you can access and modify at any later time.

Methods

The xmpResource methods carry out some data retrieve or manipulation over the data at the remote server. Using an underlying AngularJS resource object, They are all performing asynchronous HTTP calls (at least by default) and return promise objects. If you are familiar with Angular JS promise objects, you can use the result like you do with other promise objects. In addition any such method accepts callback for both success and failure scenarios, and allow you to implement using the call result in this manner instead of promises.

All methods require the existence of access data, either as a default defined in xmpResource.access member (which you setup through config or directly on the member) OR that you passed to the method as an option. Note that initially (As the page loads) the access data contains only the url member and the accessToken. You must add a serviceToken member with the result of a call to the login method of xmpResource. There is a shortcut for getRecipientADORs call that allows combining it with login to save the need for two calls

Get Recipient Data

getRecipientADORs

Prototype:

getRecipientADORs(
    inRecipientID,
    inOptions,
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

• inRecipientID: The recipient ID of the recipient for whom to get the ADORs
• inOptions: options object. See below for details
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

var inOptions = { 
	access : {  
		url: 'YYYYY', 
		accessToken: 'XXXXX',  
		serviceToken: 'ZZZZZ' 
	}, 
	adors: ['firstName', 'lastName', 'Age'], 
	resolved : ['Gender'], 
	async: true/false 
} 

Return value:
a Promise object containing a key value mapping where the key is the ADOR name, and the value is the result. For example:

{
    "first name":"gal",
    "last name":"kahana",
    "courses":[
       {"name":"calculus","hours":"8"},
       {"name":"logic","hours":"4"},
       {"name":"C++","hours":"10"}
    ]
}

The result returns first name and last name ADORs, which are regular values, and courses which is a table ADOR - represented as an array with key value objects for each item.

Description:

getRecipientADORs requests ADOR values for inRecipientID per the inOptions options structure provided. options may have:

• access [optional] - access data for the call. If null will use the service default.
• adors - array of requested ADORs.
• async [optional] - if not passed, a result is returned that when complete will have the recipient data key/value object. if true, an async request will start a query job on the server, and return with a job ID. later that ID may be requeried mutliple times with getRecipientQueryStatus. getRecipientQueryStatus will return a status. when the status is ready it will also return the key value pair that are the recipient values for the ADORs list.
• login [optional] - login data, for login + query
• resolved [optional] - array of ador names. Adors in this list should go through asset resolving. Note that it may be that 'resolved' will appear but 'adors' will not
• noCache [optional] - boolean. don't use cache for this retrieve

returned result, if non-async, is a dictionary of key-value, where a key is ADOR name, and value is the ADOR value. If async, will return job id, status, and if done, also the dictionary with key-value providing the ADOR names/values.

uImage

Note that in case of ADORs that are implemented as uImage, the return value will not be a string, but rather an object defining an async job, like this:

{
    "uImage":true,
    "jobID":THE_ASYNC_JOB_ID,
    ["status":CURRENT_STATUS]
}

• 'uImage' is a flag to mark this object as uImage (this will enable future devs).
• 'jobID' is an async job id started for this uImage calculation.
• 'status' is an optional data providing

If this is the case, use an async job loop to wait for the actual value. See getRecipientQueryStatus for getting status and final value.

####Login

getRecipientADORs may be optionally used for login, and spare the need for an initial login call. This is useful when the page calls getRecipientADORs as an initial,mostly, phase, to save the need for extra REST call.
in this case pass the login requirements via the inOptions structure:

inOptions = 
{
    ....
    login:{
        cached:	{
	    serviceToken:inChachedServiceToken,
	    recipientID:inCachedRID
        }
    }
}

Note that in this cases inRecipientID will be NULL as you don't have it yet. [it is determined by login]

When using this form of login the return result will be an object with two members:

• login - login result, like this:

{
    serviceToken:the_service_token,
    recipientID:the_recipient_id
}

• result - ADORs collection.

getRecipientQueryStatus

Prototype:

getRecipientQueryStatus(
    inOptions,
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

• inOptions: Options object is mandatory this time with a single mandatory member - jobID which indicates the Job ID to check status for. Another optional member is access which may be used for instead of the default pre-configured access object.
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
a Promise object containing a the status, and possibly values for the query:

{
    jobID: /* the job id*/,
    status: /*either 0 (done success),1 (in progress) or 2 (done error)*/
    [recipientID]: /* if status is 0, will have the recipient ID matching the ADOR values */
    [values]: /* if status is 0, a key value object with ADOR values */
}

Description:
getRecipientQueryStatus should be used after a call to getRecipientADORs where async was passed in the options object, starting an asynchronous job retrieving ADOR values.

Initially the call to getRecipientADORs will return a result that is the same as the one for getRecipientQueryStatus including the job ID to start tracking, unless the status is already no longer no progress. Then make occasional calls to getRecipientQueryStatus to get the status of the job. When finally the status equals 0 (done success) there will be another field named values with the ADOR values as a key value object. final status of 1 means failure.

getAssetFetchingURL

Prototype:

getAssetFetchingURL(
    inAssetName,
    [inOptions])

Parameters:

• inAssetName: string. The name of an asset, as retrieved from a recipient ADORs get.
• inOptions: [optional,null] Options object can contains a single access member which may be used instead of the default pre-configured access object.

Return value:
A URL for the asset named.

Description:
After receiving an ADOR value that is an asset name from getRecipientADORs you will want to be able to fetch the asset. Use this method to get a URL that you can use as source for this asset, for using in your page, for example as an src attribute for an img element or for Ajax getting.

Getting Project Data

The following methods provide information about the project which is not related to a particular recipient - such as the plan schema, documents available for PDF generation, email documents and touch-points etc.

Changing Recipient Data

saveRecipientADORs

Prototype:

saveRecipientADORs(
    inRecipientID,
    inADORs,
    [inOptions],
    [inRunWhenSuccess],
    [inRunWhenFailed])`

res.saveRecipientADORs(res.recipientID, adors, 
{ 
	retrieveADORs: ['firstName', 'lastName', 'Gender', 'Age'], 
	resolvedADORs: [] 
}, 
function (data) { 
	$('#result').text(data.firstName + ' ' + data.lastName + ' successfully updated'); 
}, 
function (data) { 
	$('#result').text('Something went wrong'); 
}); 

Parameters:

• inRecipientID: [string], a recipient ID to save to ADOR values to.
• inADORs: [object], key value map, where the key is the name of an ADOR, and the value is its new value
• inOptions: [optional,null] Options object can contains an access member which may be used instead of the default pre-configured access object. In addition it can add two other members:
  • retrieveADORs: a list of ADORs to retrieve post update
  • resolvedADORs: a sublist of retrieveADORs of ADORs that should go through asset resolving
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
a Promise object containing a key value map of ADOR values, like the case of getRecipientADORs for what ADORs providing in inOptions.retrieveADORs.

Description:
A method for setting ADOR values for a recipient. Provide recipient ID, ADOR names and values to set the new values.
You can optionally pass ADOR names to retrieve post the setting via inOptions.retrieveADORS and inOptions.resolvedADORs.

addRecipient

Prototype:

addRecipient(
    inOptions,
    [inRunWhenSuccess],
    [inRunWhenFailed])`

res.addRecipient({ 
	adors: { 
		firstName: firstname, 
		lastName: lastname, 
		Gender: gender, 
		Age: age 
	}, 
	retrieveADORs: ['firstName', 'lastName', 'Gender', 'Age'], 
	resolvedADORs: [] 
}, 
function(data) { 
	$('#result').text(result.values.firstName + ' ' + result.values.lastName + ' successfully added'); 
}, 
function(data) { 
	$('#result').text('Something went wrong'); 
}); 

Parameters:

• inOptions: Options object is mandatory this time containing the data of the recipient and other fields. inOptions has the following keys:
  • adors - key value object defining the ADOR names and values that serve as the new recipient initial values.
  • retrieveADORs: [optional] a list of ADORs to retrieve post insertion
  • resolvedADORs: [optional] a sublist of retrieveADORs of ADORs that should go through asset resolving
  • access: [optional] access object data which may be used instead of the default pre-configured access object
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
a Promise object containing the new recipient ID (as recipientID) and ADOR values (as values) for the ADORs requested via inOptions.retrieveADORs. For example:

{
	"values":{
		"first":"james",
		"last":"green",
		"profilePic":"img1.jpg"
	},
	"recipientID":"james.green"
}

Description:
Create a new recipient. Provide the new recipient values in inOptions.adors as an object of properties where keys are ADOR names and values are the ADOR values. Optionally also provide ADORs to retrieve after the recipient insertion. Returns the new recipient ID and calculated ADOR values post insertion.

Tracking

trackEvent

Prototype:

trackEvent(
    inEventType,
    [inOptions],
    [inRunWhenSuccess],
    [inRunWhenFailed])`

var pageName = 'Tracking page'; 
var actionName = 'load page'; 
res.trackEvent(actionName, { 
	sync: true, 
	recipientID: res.recipientID, 
	properties: res.addDefaultTrackingParameters({ 
		PageName: pageName, 
		ActionName: actionName, 
		ActionParams: new Date().getTime(), 
	}) 
}); 

Parameters:

• inEventType: event type.
• inOptions: [optional,null] Options object contain extra data about the event and access data. Its members can be:
  • recipientID - recipient to track this event for. At this point in time tracking is only enabled for cases where the page is personalized, and so recipientID is actually mandatory.
  • access - optional access object to override the default xmpResource assigned connection.
  • sync - defaults to false. If true the method call becomes synchronous and will return only when the HTTP request is complete. This is generally a bad idea, unless you are tracking a page leave event, in which case if you don't use it the event recording may not happen.
  • date - date for the tracked event. default is now.
  • properties - extra properties for this event. See below for details.
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
a Promise object which value is undefined.

Description:
Use trackEvent to track events occurring on the page. The most important parameters to retrieve are the event type and the recipient ID (in inOptions.recipientID).

In addition the inOptions object also includes a properties object that should include extra data about the event. You should normally have the following members set up in the properties object:

{
  PageName: XXXX, // the page logical name
  ActionName: YYYY, // action name, may be different from the event type to define a variant of it
  ActionParams: ZZZZ // parameters for the action depending on the action type
}

In addition there are other parameters per the tracking protocol, and they may be conveniently handled by calling addDefaultTrackingParameters with your properties object, for example like this:

xmpResource.trackEvent(
    'Page Leave',
    {
        sync:true, // so that window unload won't kill the post request
	recipientID:scope.xmp.recipientID,
	properties: xmpResource.addDefaultTrackingParameters(
                      {
                          PageName:scope.trackingPageName,
                          ActionName:'Page Leave',
                          ActionParams:(((new Date()).getTime() - loadedTime) / 1000).toString(),
                      })
   });

Note how the properties member is the result of calling addDefaultTrackingParameters for the user set parameters.

addDefaultTrackingParameters

Prototype:

addDefaultTrackingParameters(inProperties)

Parameters:

• inProperties: properties object for the event to track

Return value:
an enhanced properties object for the event to track, with some simple-to-compute fields

Description:
Use addDefaultTrackingParameters as part of calling trackEvent to fill up some fields automatically. The method takes care of the following parameters:

• Screen Resolution, (client window resolution)
• Browser, (browser name and version)
• Platform, (os name and version)
• Human Language, (browser language)
• ClientIP, (client IP, provided by server according to relevant HTTP headers)
• PageURI, (page URL, with no parameters)
• ReferringPageURI, (page URL for the page that lead to this page, if relevant. normally for links clicked on)
• UserSession, (server session ID, to track different work sessions)
• PageParams, (page query string parameters)
• IsLandingPage, (indication for landing page)
• Java Enabled, (javascript enabled on page. true)

Email

sendEmail

Prototype:

sendEmail(
    inEmailTouchpointID,
    inOptions,
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

• inEmailTouchpointID: email touchpoint ID, to use as template for sending an email.
• inOptions: options object containing data for sending the email. The following members are available:
  • recipientID: recipient ID to send the email to.
  • access: optional. access object to override the default xmpResource access.
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
a Promise object containing an undefined value.

Description:
Use this method to send emails according to a touchpoint and recipient ID.

changeUnsubscribeStatus

Prototype:

changeUnsubscribeStatus(
    inRecipientID,
    inUnsubscribe,
    [inOptions],
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

• inRecipientID: recipient ID to change the subscription status for.
• inUnsubscribe: boolean. Set the subscription status to true or false.
• inOptions: [optional,null] Options object can contains a single access member which may be used instead of the default pre-configured access object.
• inRunWhenSuccess: [optional, null], callback to call on success. inRunWhenSuccess(result,httpResponseHeaders)
• inRunWhenFailed: [optional,null], callback to call on failure. inRunWhenFailed(httpResponse)

Return value:
A promise object with undefined value.

Description:
Change the subscription status for the recipient. Provide the recipient ID and whether the person should be unsubscribed (true) or re-subscribed (false).

Debugging

xmpResource provides debug and error methods which work similar to the ones that browser provide. The main difference is that debug will log messages when debugEnabled was set to true on xmpResource.