xmpResource Reference

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, such as retrieving the ADOR information for a recipient, adding new recipients, sending emails etc.

#Setup

This section discusses setup in Angular JS environment. For plain JavaScript - non angular setup go to JavaScript Access.

To setup xmpResoruce you must first include the XMPL javascript code (xmp.min.js, or other versions 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 (directive, service, whatnot) that requires the usage of xmpResource, 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:

You can pass access data object in any method call via an optional options variable.
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 like this:

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

The url member holds the address of the XMPL server, more precisely it's 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.

Note that serviceToken is missing. serviceToken is not initially provided. It is something that you get by making a first login call to xmpResource. Prior to using any other method of xmpResource in a page you must call its login method, to retrieve a serviceToken. Then set this token as the serviceToken member of the access data object, and you are ready to make other calls.

Another note. For some methods (where specified) your accessToken member is not just the identifier provided in the xmpcfg.js file. Rather, to make the call you are required to also prefix the access token with a temporary circle token that is dependent on a user login. This is not the case for most methods, and is explained below in Extra Circle token.

#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 access:xmpcfg 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 login with to save the need for two calls - but other cases require an initial call to login. Important - call login only once. When you already have the serviceToken then for the page session it is no longer required to make another call.

login

Prototype:

login(
    [inChachedServiceToken],
    [inCachedRID],
    [inWithRIDDeciphering],
    [inOptions],
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

inChachedServiceToken: [optional, null] A cached service token from a previous call to login, server may return it if not expired
inCachedRID: [optional, null] A cached recipient ID from a previous call to login, if passed then RID deciphering will use it as the returned RID in case one cannot be deciphered from the URL
inWithRIDDeciphering: [optional, false], Boolean, determining whether login should try to decipher a recipient ID from the page URL in addition to returning the service Token. This is good for pages using URLs in the form of XMPie page URLs, in which case the call can retrieve the intended recipient ID.
inOptions: [optional,null] Options object can contains a single access member which may be used for the login 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:

{
    serviceToken:the_service_token,
    recipientID:the_recipient_id
}

serviceToken has the fresh service token, that should be added to the access object. recipientID has the recipient ID in case inWithRIDDeciphering is true.

Description:
Login is the first call to the service, aiming to get a service token. In addition, if passing a site URL it can retrieve a recipient ID from it, if formed like XMPie purls. The method accepts previous cached RID and service token - pass null if there's no such cache. inWithRIDDeciphering will tell the method to ask for RID deciphering from the current site url. Pass false if you don't want such deciphering - do that, as the server will fail if the URL misfits.

For the sake of convenience, xmpResoruce.access.serviceToken is set with the retrieved token. This will allow calling later methods without having to pass it in the options structure (as is the case for service URL and access token which are normally configured in the initial configure method).

#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: [optional, null] 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)

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 [optional] - array of requested ADORs. if not provided, all ADORs will be retrieved
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
idIsIndex [optional] - boolean. Notes that the recipient ID passed is actually not its ID, but rather its index in the arbitrary collection of recipients. This should be used for simple iterations, from 0 to the recipients count which can be retrieved through getRecipientsCount.

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.

##getRecipientsCount Prototype:

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

Parameters:

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 containing a single result member with the recipients count, for example:

{
    result:30
}

Description:

Retrieve the number of recipients for the project. Good for later iteration with getRecipientADORs using index instead of recipient IDs (from 0 to this count-1). Can also be used with getRecipientsIDFromIndex to fetch recipient IDs.

##getRecipientsIDFromIndex Prototype:

getRecipientsIDFromIndex(
    inIndex,
    [inOptions],
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

inIndex: [number], a recipient index, per an arbitrary order of the recipient list, that you want to return the recipient ID for.
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 containing a single result member with the recipient ID, for example:

{
    result:"Jack.Bruce"
}

Description:

Retrieve the recipient ID for a given recipient index. The index is according to an arbitrary order of the recipient list and runs from 0 to the result of getRecipientsCount.

##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 recipients - such as the plan schema, documents available for PDF generation, email documents and touch-points etc.

##getSchema Prototype:

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

Parameters:

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 containing the project schema, example:

{
    "adors":[
       {"name":"first name","type":"text",”io”:2},
       {"name":"last name","type":"text",”io”:2},
       {"name":"email","type":"text",”io”:2},
       {"name":"siteProfileImg","type":"image",”io”:0},
       {"name":"siteIntroductionText","type":"text file"},
       {"name":"isStudent", "type":"visibility",”io”:2},
       {"name":"facebook", "type":"link"},
       {"name":"courses", "type":"table",
              "columns":[
                     {"name":"name","type":"text"},
                     {"name":"hours","type":"text"}
              ]},
]}

The return object contains a single entry named "adors" that has the adors for the plan. It is an array ordered per the plan ADORs order. Each item defines a single ADOR in a descriptor object that has the following fields:

name: name of the ADOR
type: type of ADOR. can be one of - text, image, text file, style, visibility, table, link
io: read/write aspects for ADOR. 0 means ready only, 1 means write only, 2 means both read and write. if omitted, the default is 0.
columns: for table ADORs only. an array of ADORs that form the table columns.

Description:

Retrieve the plan schema, list of ADORs. These ADORs can be used for retrieving recipient data.

##getDocuments Prototype:

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

Parameters:

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 containing a list of documents available for PDF generation, where the key is the document ID and value contains informative data, currently just the label for the document. For example:

{
    "1":{
        "label":"welcome.indd"
    },
    "2":{
        "label":"thankyou.indd",
    }
}

Description:
Retrieve a list of documents that are available for generation of PDF documents. You can start such generation by calling startGenerationJob with the desired document ID and a recipient ID to personalize this document for.

##getEmailTouchpoints Prototype:

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

Parameters:

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 containing a list of email touch-points for the project. You can use these touch-points for sending emails via sendEmail. For example,

{
	"E4":{
		"label":"recipient details update"
	},
	"E5":{
		"label":"new recipient administrator notification"
	}
}

The keys for the return values are email touchpoint IDs. the values are descriptor objects that provide the label for the touchpoint.

Description:
Retrieve a list of available email toucpoints for this project for. You can use the IDs as input parameters for sendEmail to send emails (!).

##getEmailDocuments Prototype:

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

Parameters:

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 containing a list of email documents for the project (text and html files). This has meaning mainly if you wish to download and upload them later, as emails themselves are sent through email touch points, and not documents. An example for such return value:

{
    "1":{
        "label":"newcustomer.htm",
        "type":"htm"
    },
    "2":{
        "label":"existingcustomer.htm",
        "type":"htm"
    },
    "3":{
        "label":"customer.txt",
        "type":"txt"
    }
}

The keys for the return values are email document IDs. the values are descriptor objects that provide the label for the document and its type - either txt or htm.

Description:
Retrieve a list of email documents. Later usage of those documents is a bit outside of the scope of the xmpResource service, and revolves mainly around editing these documents. The rest of the editing workflow should be done, currently, using the REST protocol of XMPL directly rather than relying on xmpResource services.

##getEmailFooters Prototype:

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

Parameters:

inIndex: [number], a recipient index, per an arbitrary order of the recipient list, that you want to return the recipient ID for.
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 containing data about the configured email footers for email documents as defined in the project. For example:

{
    "htm" : "<div>…..</div”,
    "txt" : "UNSUBSCRIBE\nIf you do not wish….."
}

The result object contains at most two keys - htm and txt - where each value is the footer to place in emails of that type (meaning - either html or text).

Description: Retrieve email footers defined for this project. This has to do mainly with applications looking to edit email documents and allow placing the pre-defined email footers as the project user intended them to be.

#changing recipient data

##saveRecipientADORs Prototype:

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

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])`

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.

#generation jobs The next couple of methods allow for the generation and fetching of Personalized PDFs. Document IDs for generating the jobs may be known in advanced or dynamically fetched with getDocuments. Then start a generation job with startGenerationJob, track its status occasionally with getGenerationJobStatus and finally fetch the end result with getGeneratedFileFetchingURL.

Note that the underlying REST protocol allows also the generation of document packages using these methods. This usage goes beyond the scope of xmpResource and is therefore not described here.

##startGenerationJob Prototype:

startGenerationJob(
    inDocumentID,
    inOptions,
    [inRunWhenSuccess],
    [inRunWhenFailed])`

Parameters:

inDocumentID: Document ID to start generation for.
inOptions: Options object is required, and contains recipientID that provides the recipient ID to create the PDF for. In addition it may contain an 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 containing a status of the starting job:

{
    jobID: /* the job id*/,
    status: /*either 0 (done success),1 (in progress) or 2 (done error)*/
    [generatedFileID]: /* if status is 0, will have the ID for the result file */
    [errorCode]: /* if status is 2, will have an error code */
    [errorMessage]: /* if status is 2, will have an error message */
}

jobID: The starting job ID. Can be used later with getGenerationJobStatus for tracking the job status.
status: status of job. 0 for done successfully, 1 for still in progress and 2 for completed with an error.
generatedFileID: if done successfully, will contain the file ID for downloading. This can be used with getGeneratedFileFetchingURL to reference the finished file.
errorCode: in case of error will have the error code
errorMessage: in case of error will have the error message

Description: Start a Personalized PDF generation. Provide the document ID to use as template and recipient ID to personalize for, to start job. You can later track its status with getGenerationJobStatus and finally get the file with getGeneratedFileFetchingURL.

##getGenerationJobStatus Prototype:

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

Parameters:

inOptions: Options object is required, and contains jobID that provides the job ID to get status for. The job ID was set as a return value from an earlier call to startGenerationJob. In addition it may contain an 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 containing the current status of the job:

{
    jobID: /* the job id*/,
    status: /*either 0 (done success),1 (in progress) or 2 (done error)*/
    [generatedFileID]: /* if status is 0, will have the ID for the result file */
    [errorCode]: /* if status is 2, will have an error code */
    [errorMessage]: /* if status is 2, will have an error message */
}

jobID: The job ID.
status: status of job. 0 for done successfully, 1 for still in progress and 2 for completed with an error.
generatedFileID: if done successfully, will contain the file ID for downloading. This can be used with getGeneratedFileFetchingURL to reference the finished file.
errorCode: in case of error will have the error code
errorMessage: in case of error will have the error message

Description: Get a running job status. Job ID is originally returned by startGenerationJob. When done, generatedFileID returned in the result object may be used with getGeneratedFileFetchingURL to fetch the file.

##getGeneratedFileFetchingURL Prototype:

getGeneratedFileFetchingURL(inOptions)

Parameters:

inOptions: Options object is required, and contains fileID for which the download URL should be fetched. In addition to the fileID you may optionally pass an access member which may be used instead of the default pre-configured access object.

Return value:
a URL for downloading the file for inOptions.fileID

Description:
For a concluded PDF generation job use this method to get a URL to retrieve the end result file. Provide the file ID fetched via getGenerationJobStatus result generatedFileID member.

#tracking ##trackEvent Prototype:

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

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.
- customizations: optional object containing customization values for aspects of the email. 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 containing an undefined value.

Description: Use this method to send emails according to a touchpoint and recipient ID.
You can customize several aspects of the email, this way overriding the default definitions for the touchpoint. The following members are available in inOptions.customizations:

xmpSubject – the subject to provide with this email
xmpFrom - the email “from” email address
xmpFromName – the email “from” field display name
xmpReplyTo – the reply-to address for this email
xmpTo - the email “to” email address
xmpToName – the email “to” field display name
xmpCc - the email “cc” email address
xmpCcName - the email “cc” field display name
xmpBcc - the email “bcc” email address
xmpBccName - the email “bcc” field display name

##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.