Targeting API

The Targeting API provides programmatic access to the targets in your site and their interaction with content items. It can be accessed via JavaScript or Apex.

TargetingAPIRequest

A Targeting API request is made up of the following properties. Requirements may differ depending on the API method used:

contentId: String, The content ID to use in a given API method.
bundles: List<TargetBundle>, The list of TargetBundles to set, add or remove targets from a piece of content or update.
mapParameters: Map<String, Map<String, String>>, Used with saving or creating content, this must contain a map with a key of values and a value of a map, with a key of the target field and a value of the value to target on.

createTarget

This method creates a new target with the given parameters.

Parameters

name: String, A required field and is the name of the target being created.
type: String (optional, default: Predefined), The type of the target. The value can be either Ad Hoc or Predefined.
description: String (optional), A description of the target
expiryDate: String (optional), The specified string should use the standard date format yyyy-MM-dd HH:mm:ss in the GMT timezone. If omitted, OrchestraCMS will assume this target never expires.

Map Parameters

mapParameters: Map<String, Map<String, String>>, Used with saving or creating content, this must contain a map with a key of values and a value of a map, with a key of the target field and a value of the value to place on a target. For multiple values, use a comma-separated list of strings.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

targetingRequest.parameters = new Map<String, String>{'name' => 'Test Created Target', 'type' => '', 'description' => 'Test description', 'offset' => '0'};
targetingRequest.mapParameters = new Map<String, Map<String, String>>{'values' => new Map<String, String>{'Country' => 'Canada,US'}};

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'createTarget');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to create target.');
}
if (apiResponse.type != 'TargetBundle') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and TargetBundle
System.Debug(apiResponse.message); // Outputs 'CREATE_TARGET' on success

JavaScript Request

var apiRequest = {
    parameters: {
        name: 'Test Created Target',
        type: '',
        description: 'Test description.'
    },
    mapParameters: {
        values: {
            Country: 'Canada,US'
        }
    },
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'createTarget',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // createTarget Request

The user must have set up target permissions and the content targeting feature license must be enabled. See the getTargetedUserFields API method for a list of possible targeted fields to use.

deleteTarget

This method deletes the target for the given target ID.

Parameters

id: String, The ID of the target to delete.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

targetingRequest.parameters = new Map<String, String>{'id' => 'a00000000000000000'}; // Replace with TargetBundle originId

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'deleteTarget');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to delete the requested target.');
}
if (apiResponse.type != 'Message') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and Message
System.Debug(apiResponse.message); // Outputs 'Target deleted' on success

JavaScript Request

var apiRequest = {
    parameters: {
        id: 'a00000000000000000', // Replace with TargetBundle originId
    },
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'deleteTarget',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // addTagToContent Request

The user must have set up target permissions and the content targeting feature license must be enabled.

expireTarget

This method will expire the target for the given ID, setting the expiry date to the given date. The date must be in the user's local time. If no expiry date is given, OrchestraCMS will use the current date as the expiry date.

Parameters

id: String, The ID of the target to expire.
expiryDate: String, The specified string should use the standard date format yyyy-MM-dd HH:mm:ss in the GMT timezone. If omitted, OrchestraCMS will use the current date as the expiry date.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

targetingRequest.parameters = new Map<String, String>{'id' => 'a00000000000000000'}; // Replace with TargetBundle originId

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'expireTarget');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to expire the requested target.');
}
if (apiResponse.type != 'TargetBundle') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and TargetBundle
System.Debug(apiResponse.message); // Outputs 'EXPIRE_TARGET' on success

JavaScript Request

var apiRequest = {
    parameters: {
        id: 'a00000000000000000', // Replace with TargetBundle originId
    },
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'expireTarget',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // expireTarget Request

The user must have set up target permissions and the content targeting feature license must be enabled.

getTargetedUserFields

This method retrieves the map of targeted user fields. This list is used when creating/updating targets via the createTarget/saveTarget requests. This Map has only one value that can be passed as a possible targeted field and once used, a field should not be used again. Multiple values for a field should be expressed as a comma separated list of values.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'getTargetedUserFields');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to get the targeted user fields.');
}
if (apiResponse.type != 'Map<String, Integer>') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and Map<String, Integer>
System.Debug(apiResponse.message); // Outputs 'The matching targets for the user' on success

JavaScript Request

var apiRequest = {
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'getTargetedUserFields',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // getTargetedUserFields Request

In the returned Map<String, Integer>, the String key is the field name and the Integer value is the fields position.
The user must have set up target permissions and the content targeting feature license must be enabled.

getTargets

This method retrieves all the targets for the current site.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'getTargets');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to get the targets for the site.');
}
if (apiResponse.type != 'List<TargetBundle>') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and List<TargetBundle>
System.Debug(apiResponse.message); // Outputs 'All the targets for the current site' on success

JavaScript Request

var apiRequest = {
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'getTargets',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // getTargets Request

Returns all predefined and ad hoc targets for the site.

getTargetsForUser

This method retrieves all the targets for the specified user.

Parameters

userId: String, The user ID of the user for whom the target list will be obtained. When provided, userId takes precedence over username.
username: String, The username of the user for whom the target list will be obtained.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();
targetingRequest.parameters = new Map<String, String>{'userId' => '005000000000000000'};

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'getTargetsForUser');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to get the targets for the user.');
}
if (apiResponse.type != 'List<TargetBundle>') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and Message
System.Debug(apiResponse.message); // Outputs 'The matching targets for the user' on success

JavaScript Request

var apiRequest = {
    parameters: {
        userId: '005000000000000000' // Replace with the user Id to retrieve the targets from
    },
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'getTargetsForUser',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // getTargetsForUser Request

Only predefined targets will be returned, because the Targeting API can't evaluate AdHoc ones.

getTargetsOnContent

This method retrieves targets on the specified content.

Parameters

contentId: String, The content ID to get the targets from.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();
targetingRequest.contentId = 'a01000000000000000';

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'getTargetsOnContent');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);
System.Debug(response);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to get the targets on the content.');
}
if (apiResponse.type != 'List<TargetBundle>') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and List<TargetBundle>
System.Debug(apiResponse.message); // Outputs 'The target for the specified content' on success

JavaScript Request

var apiRequest = {
    contentId: 'a01000000000000000',
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'getTargetsOnContent',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // getTargetsOnContent Request

saveTarget

This method takes an existing TargetBundle retrieved by one of the TargetingAPI calls and allows you to set new values and then save that target bundle.

Parameters

bundles: List<TargetBundle>, The target to save. Currently only a single entry in the list is supported for saving. Setting more than one item will result in an error.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

TargetBundle targetBundle = new TargetBundle();
targetBundle.targetType = 'Predefined';
targetBundle.targetName = 'Test Target';
targetBundle.description = 'Updated description';

targetingRequest.bundles = new List<TargetBundle>{targetBundle};

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'saveTarget');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to save the target.');
}
if (apiResponse.type != 'TargetBundle') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and TargetBundle
System.Debug(apiResponse.message); // Outputs 'UPDATE TARGET' on success

JavaScript Request

var apiRequest = {
    bundles: [{
        targetType: 'Predefined',
        targetName: 'Test Target',
        description: 'Updated description',
    }],
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'saveTarget',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // saveTarget Request

The user must have set up target permissions and the content targeting feature license must be enabled.

Currently only a single entry in the list is supported for saving, setting more than one item will result in an error.

searchTargets

This method search for targets with the given filters.

Parameters

name: String, A required field and is the name of the target being created.
status: String, The status of the target, either Active or Expired.
type: String (optional, default: all), The type of the target. The value can be either Ad Hoc or Predefined.
modifiedBy: String (optional), The name of the user who last modified the target.
lastUsed: String (optional), The specified string should use the standard date format yyyy-MM-dd HH:mm:ss in the local timezone of the user.
offset: String (optional), The offset index used to start the search, used when moreResults = true.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();

targetingRequest.parameters = new Map<String, String>{'name' => 'Test', 'type' => '', 'status' => 'Active', 'offset' => '0'};

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'searchTargets');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to search for targets.');
}
if (apiResponse.type != 'List<TargetBundle>') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and List<TargetBundle>
System.Debug(apiResponse.message); // Outputs no message on success

JavaScript Request

var apiRequest = {
    parameters: {
        name: 'Test',
        type: '',
        status: 'Active',
        offset: '0'
    },
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'searchTargets',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // searchTargets Request

The user must have set up target permissions and the content targeting feature license must be enabled.

setTargetsForContent

This method set targets on the specified content.

Parameters

contentId: String, The content ID on which to set the targets.
bundles: List<TargetBundles>, The list of new TargetBundles to set on the content. Passing an empty TargetBundle list will remove the targets from the content.

Apex Request

TargetingAPIRequest targetingRequest = new TargetingAPIRequest();
targetingRequest.contentId = 'a01000000000000000';

TargetBundle targetBundle = new TargetBundle();
targetBundle.targetType = 'Predefined';
targetBundle.targetName = 'Test Target';

targetingRequest.bundles = new List<TargetBundle>{targetBundle};

Map<String, String> parameters = new Map<String, String>();
parameters.put('service', 'TargetingAPI');
parameters.put('action', 'setTargetsForContent');
parameters.put('targetingRequest', json.serialize(targetingRequest));
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('apiVersion', '5.0');

String response = cms.ServiceEndPoint.doActionApex(parameters);

JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) json.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Unable to set the targets for the content.');
}
if (apiResponse.type != 'Message') {
    throw new APIException('Unexpected result from Targeting API.');
}

System.Debug(response); // Outputs response and Message
System.Debug(apiResponse.message); // Outputs 'Successfully added the targets to the content.' on success

JavaScript Request

var apiRequest = {
    bundles: [{
        targetType: 'Predefined',
        targetName: 'Test Target'
    }],
    contentId: 'a01000000000000000',
    requestFlags: {}
};
var response = '';
var data = {
    service: 'TargetingAPI',
    action: 'setTargetsForContent',
    targetingRequest: JSON.stringify(apiRequest),
    apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
    var jsonResponse = JSON.parse(json);
    console.log(jsonResponse);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){}, // Handle response on complete
    readonly: false // Whether it is a read only call
};
doServiceRequest(data, options); // setTargetsForContent Request

This can be used to add and remove targets. If you are adding a target, you must send all the old targets plus the new one in your list.

JSON-Serialized Response Examples

List<TargetBundle> Example

{
    "type": "List<TargetBundle>",
    "transactionId": null,
    "timeNow": "2017-06-26T00:00:00.000Z",
    "responseObject": [{
        "targetType": "Predefined",
        "targetName": "Test Target",
        "targetKey": "a12345678901234567890123456=",
        "targetExpireDate": null,
        "originId": "a00000000000000000",
        "lastModifiedDate": "2017-06-26T00:00:00.000Z",
        "lastModifiedByName": "Example User",
        "filters": {
            "Country": ["Canada"]
        },
        "description": null
    }],
    "moreResults": false,
    "message": "All the targets for the current site",
    "isSuccess": true,
    "error": null
}

Map<String, Integer> Example

{
    "type": "Map<String, Integer>",
    "transactionId": null,
    "timeNow": "2017-06-26T00:00:00.000Z",
    "responseObject": {
        "Country": 1
    },
    "moreResults": false,
    "message": "The matching targets for the user",
    "isSuccess": true,
    "error": null
}

Message Example

{
    "type": "Message",
    "transactionId": null,
    "timeNow": "2017-06-26T00:00:00.000Z",
    "responseObject": null,
    "moreResults": false,
    "message": "Successfully added the targets to the content.",
    "isSuccess": true,
    "error": null
}