Filtering API
The Filtering API allows content to be retrieved by various filters.
There are several supporting classes needed for the Rendering API in order to return a RenderResultBundle for use. These helper classes are available in the API 5.0 Resources and the required classes are JSONMessage, APIRequest, FilteringAPIRequest, ContentTypeBundle, AttributeBundle, ContentLayoutBundle, TargetBundle, TaxonomyBundle, ContentBundle, UserBundle and FilteringBundle.
The included examples System.Debug(apiResponse.responseObject) statements return a FilteringBundle.
getContentByName
This method retrieves all content items that match one of the names contained in the request. The search includes the name of the content in all added languages, and is case-insensitive.
Apex Request Example
FilteringAPIRequest filteringRequest = new FilteringAPIRequest();
List<String> contentNames = new List<String> {'Content 1'};
filteringRequest.listParameters.put('contentNames', contentNames);
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('service', 'FilteringAPI');
parameters.put('action', 'getContentByName');
parameters.put('filteringRequest', json.serialize(filteringRequest));
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('Could not retrieve renderings for this node');
if (apiResponse.type != 'FilteringBundle')
throw new APIException('Unexpected result from Filtering API');
System.Debug(apiResponse.responseObject);
JavaScript Request Example
var listparams = {
contentNames: ['Content 1']
};
var filteringRequest = {
listParameters: listparams,
requestFlags: {}
};
var response; // Used to get the JSON Object Response from action
var data = {
service: 'FilteringAPI',
action: 'getContentByName',
filteringRequest: JSON.stringify(filteringRequest),
apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
console.log(json);
response = JSON.parse(json);
}
var options = {
cb: callBackHandler,
cbHandlerOnComplete: function(textStatus) {}, // Handle response on complete
readonly: true // Whether it is a read only call
};
doServiceRequest(data, options);
JSON-Serialized Response Example
{
error: null
isSuccess: true
message: ""
responseObject: {
"contentBundles": {
"a00000000000000000": {
"publishedStartDate": "2017-06-26T00:00:00.000Z",
"originId": "a00000000000000000",
"originalPublishedStartDate": "2017-06-26T00:00:00.000Z",
"contentMetaAttributes": {
"en_US": {
"languageCode": "en_US",
"metaContentName": "Content 1",
"metaContentDescription": "Content 1 Article"
}
},
"contentId": "a00000000000000000",
"contentAttributes": {
"en_US": [{
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Content 1",
"name": "Headline"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Related Articles",
"name": "RelatedArticleLabelText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "<div><span>I am rendered content</span></div>",
"name": "HTMLContent"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "/servlet/servlet.FileDownload?file=00P000000000000000",
"name": "ImageId"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "/servlet/servlet.FileDownload?file=00P000000000000001",
"name": "LargeImageId"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "I am rendered content",
"name": "SummaryContent"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Rendered Content",
"name": "AltImageText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Rendered Content",
"name": "TitleImageText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "<div><span>I am rendered content</span></div>",
"name": "body"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "More Info.",
"name": "mainLinkTitle"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Link 1",
"name": "link1Title"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Link 1",
"name": "link2Title"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Content 1",
"name": "title"
}]
}
}
}
}
timeNow: "2017-06-26T00:00:00.000Z"
transactionId: null
type: "FilteringBundle"
}
The returned API Response is a generic object that contains a responseObject for the specific data from the request.
If no request flags are passed, the most recent version of content is returned regardless of whether it is published.
getRecentlyPublishedContent
This method retrieves all content items from the specified content type. Items are returned in descending order by published date.
Apex Request Example
FilteringAPIRequest filteringRequest = new FilteringAPIRequest();
List<String> contentTypes = new List<String>{'Article'};
filteringRequest.listParameters.put('contentTypes', contentTypes);
filteringRequest.parameters.put('limit', '1');
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('service', 'FilteringAPI');
parameters.put('action', 'getRecentlyPublishedContent');
parameters.put('filteringRequest', json.serialize(filteringRequest));
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('Could not retrieve renderings for this node');
if (apiResponse.type != 'FilteringBundle')
throw new APIException('Unexpected result from Filtering API');
System.Debug(apiResponse.responseObject);
JavaScript Request Example
var listparams = {
contentTypes: ['Article']
};
var params = {
limit: '1'
};
var filteringRequest = {
listParameters: listparams,
parameters: params,
requestFlags: {}
};
var response; // Used to get the JSON Object Response from action
var data = {
service: 'FilteringAPI',
action: 'getRecentlyPublishedContent',
filteringRequest: JSON.stringify(filteringRequest),
apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
console.log(json);
response = JSON.parse(json);
}
var options = {
cb: callBackHandler,
cbHandlerOnComplete: function(textStatus) {}, // Handle response on complete
readonly: true // Whether it is a read only call
};
doServiceRequest(data, options);
JSON-Serialized Response Example
{
error: null
isSuccess: true
message: ""
responseObject: {
"contentBundles": {
"a00000000000000000": {
"publishedStartDate": "2017-06-26T00:00:00.000Z",
"originId": "a00000000000000000",
"originalPublishedStartDate": "2017-06-26T00:00:00.000Z",
"contentMetaAttributes": {
"en_US": {
"languageCode": "en_US",
"metaContentName": "Content 1",
"metaContentDescription": "Content 1 Article"
}
},
"contentId": "a00000000000000000",
"contentAttributes": {
"en_US": [{
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Content 1",
"name": "Headline"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Related Articles",
"name": "RelatedArticleLabelText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "<div><span>I am rendered content</span></div>",
"name": "HTMLContent"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "/servlet/servlet.FileDownload?file=00P000000000000000",
"name": "ImageId"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "/servlet/servlet.FileDownload?file=00P000000000000001",
"name": "LargeImageId"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "I am rendered content",
"name": "SummaryContent"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Rendered Content",
"name": "AltImageText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Rendered Content",
"name": "TitleImageText"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "<div><span>I am rendered content</span></div>",
"name": "body"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "More Info.",
"name": "mainLinkTitle"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Link 1",
"name": "link1Title"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Link 1",
"name": "link2Title"
}, {
"simple": false,
"languageCode": "en_US",
"valueType": "Text",
"value": "Content 1",
"name": "title"
}]
}
}
}
}
timeNow: "2017-06-26T00:00:00.000Z"
transactionId: null
type: "FilteringBundle"
}
The returned API Response is a generic object that contains a responseObject for the specific data from the request.
getRecentlyPublishedContent will also return published content with a start date in the future. If you wish to exclude these from search results, when iterating through a list of returned ContentBundles, a check should be made against each ContentBundles' published start date to determine if this is greater than the current time.
searchContent
This method retrieves content items whose attributes contain a match for the requested search term. The term must match a full word within an attribute to be considered a match.
Apex Request Example
FilteringAPIRequest filteringRequest = new FilteringAPIRequest();
List<String> contentTypes = new List<String>{'a0100000000000000'};
List<String> filterGroups = new List<String>{'Taxonomy', 'OriginalPublishedDate'};
List<String> order = new List<String>{'Relevance:DESC', 'OriginalPublishedDate:DESC', 'PublishedDate'};
filteringRequest.parameters.put('term', 'Content 1');
filteringRequest.parameters.put('limit', '1');
filteringRequest.listParameters.put('contentTypesAndLayouts', contentTypes);
filteringRequest.listParameters.put('filterGroups', filterGroups);
filteringRequest.listParameters.put('order', order);
filteringRequest.requestFlags.put('contentType', true);
filteringRequest.requestFlags.put('contentLayouts', true);
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('service', 'FilteringAPI');
parameters.put('action', 'searchContent');
parameters.put('filteringRequest', json.serialize(filteringRequest));
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('Could not retrieve renderings for this node');
if (apiResponse.type != 'FilteringBundle')
throw new APIException('Unexpected result from Filtering API');
System.Debug(apiResponse.responseObject);
JavaScript Request Example
var listparams = {
contentTypesAndLayouts: ['a0100000000000000'],
filterGroups: ['Taxonomy', 'OriginalPublishedDate'],
order: ['Relevance:DESC', 'OriginalPublishedDate:DESC', 'PublishedDate']
};
var params = {
term: 'Content 1',
limit: '1'
};
var requestFlags = {
contentType: true,
contentLayouts: true,
targeted: true
};
var filteringRequest = {
listParameters: listparams,
parameters: params,
requestFlags: requestFlags
};
var response; // Used to get the JSON Object Response from action
var data = {
service: 'FilteringAPI',
action: 'searchContent',
filteringRequest: JSON.stringify(filteringRequest),
apiVersion: '5.0'
};
// Handle response of a successful ajax call
var callBackHandler = function(json, Success) {
console.log(json);
response = JSON.parse(json);
}
var options = {
cb: callBackHandler,
cbHandlerOnComplete: function(textStatus) {}, // Handle response on complete
readonly: true // Whether it is a read only call
};
doServiceRequest(data, options);
JSON-Serialized Response Example
{
error: null
isSuccess: true
message: "searchContent"
responseObject: {
"relevance": {
"a00000000000000000": 2
},
"filters": [{
"name": "root_taxonomy",
"filterType": "Taxonomy",
"count": 1,
"children": [{
"name": "level1",
"filterType": "TaxonomyItem",
"count": 1,
"originIds": ["a00000000000000000"],
"filter": "/root_taxonomy/level1"
}]
}, {
"name": "OriginalPublishedDate",
"filterType": "OriginalPublishedDate",
"count": 0,
"children": [{
"name": "today",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Today"
}, {
"name": "yesterday",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Yesterday"
}, {
"name": "last 7 days",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Last 7 Days"
}, {
"name": "last 30 days",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Last 30 Days"
}, {
"name": "last 90 days",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Last 90 Days"
}, {
"name": "last 12 months",
"filterType": "Date",
"count": 0,
"originIds": [],
"filter": "Last 12 Months"
}]
}],
"contentOrdering": {},
"contentBundles": {
"a00000000000000000": {
"publishedStartDate": "2016-06-02T18:33:24.000Z",
"originId": "a00000000000000000",
"originalPublishedStartDate": "2016-06-02T18:33:24.000Z",
"contentType": {
"type": "Custom",
"name": "Article",
"label": "Article",
"contentTypeId": "a0100000000000000"
},
"contentLayouts": {
"a0200000000000000": {
"name": "ArticleDetail",
"label": "Article Detail",
"contentLayoutId": "a0300000000000000"
},
"a0200000000000001": {
"name": "ArticleDetailWithRelated",
"label": "Article Detail with Related Articles",
"contentLayoutId": "a0300000000000001"
},
"a0200000000000002": {
"name": "ArticleSummary",
"label": "Article Summary",
"contentLayoutId": "a0300000000000002"
},
"a0200000000000003": {
"name": "ArticleSummarySmallWithImage",
"label": "Article Summary with Small Image",
"contentLayoutId": "a0300000000000003"
}
},
"contentId": "a00000000000000000"
}
}
}
timeNow: "2017-06-26T00:00:00.000Z"
transactionId: null
type: "FilteringBundle"
}
The returned API Response is a generic object that contains a responseObject for the specific data from the request.
Returned content bundles have a limited set of properties populated by default. Request flags can cause additional properties to be populated in the bundles.
The search string used in the term parameter is passed directly into a SOSL query. Terms with spaces will be searched as my AND search AND term while the use of quotation marks will do phrase matching. To utilize other search operators, you will need to perform custom pre-processing on the search term to include the desired operators before assigning to the term parameter passing it to the Filtering API.
FilteringAPIRequest
The FilteringAPIRequest class is accepted by all Filtering API methods. All method parameters are passed to the API within this class. This simplifies the process of writing API clients as there is only one structure the developer needs to learn and common parameters are shared across methods.
The APIRequest class includes properties common to all API requests. Below are the relevant properties for a filtering request.
Parameters
- limit : String (optional; default: 2000), Maximum number of items to retrieve. Must be 2000 or less. Used with getRecentlyPublishedContent.
- offset : String (optional), Number of items to offset the results by. Used with getRecentlyPublishedContent.
- term : String, The search term to apply. Used with searchContent.
List Parameters
- contentNames : List<String>, The names to search for. Used with getContentByName.
- contentTypesAndLayouts : List<String> , Content type IDs to restrict results to. Used with searchContent.
- filterGroups : List<String> (optional), List of filter types to apply to search results. Possible values: OriginalPublishedDate, PublishedDate, Taxonomy. Used with searchContent.
- order : List<String> (optional; default: ASC), List of orderings (ascending or descending) to apply to results. Possible values: Relevance, OrginalPublishedDate, PublishedDate. To specify DESC, append a colon to the ordering followed by DESC. For example, 'Relevance:DESC'. Multiple sort order options can be specified by separating the desire sort criteria with an underscore. Used with searchContent.
As of version 8.219, multiple sort order options can be specified by separating the desired sort criteria with an underscore. Using Relevance:DESC_PublishedDate:DESC would retrieve results in descending order first by relevance, then published start date.
Flags
- published : Boolean, Published means only the latest published version of content is returned. Used with getContentByName.
- unpublished : Boolean, Unpublished means only unpublished content is returned. Used with getContentByName.
- taxonomy : Boolean (optional), Whether to populate the taxonomyTagPaths property on the returned content bundles. Used with searchContent.
- contentLayouts : Boolean (optional), Whether to populate the contentLayouts property on the returned content bundles. Used with searchContent.
- contentTypes : Boolean (optional), Whether to populate the contentType property on the returned content bundles. Used with getRecentlyPublishedContent.
- targeted : Boolean (optional; default: true), Whether to apply targeting to the search results. Used with searchContent.
The following example demonstrates how to use the FilteringAPIRequest flags.
FilteringAPIRequest filteringRequest = new FilteringAPIRequest();
// parameters
filteringRequest.parameters.put('limit', '5');
filteringRequest.parameters.put('offset', '0');
filteringRequest.parameters.put('term', 'test');
// requestFlags
filteringRequest.requestFlags.put('published', true);
filteringRequest.requestFlags.put('unpublished', true);
filteringRequest.requestFlags.put('taxonomy', true);
filteringRequest.requestFlags.put('contentLayouts', true);
filteringRequest.requestFlags.put('contentType', true);
filteringRequest.requestFlags.put('targeted', true);
All Filtering API requests return a FilteringBundle or list of FilteringBundles.