com.day.cq.analytics.sitecatalyst

Interface ClassificationsService

public interface ClassificationsService

Provides methods for Analytics Classification API related calls as specified by the Classifications API.

Since:

6.1

Method Summary

Modifier and Type	Method and Description
boolean	commitImport(Configuration configuration, int jobId) Commits the import for processing.
int	createExport(Configuration configuration, java.lang.String campaignStartDate, java.lang.String campaignEndDate, java.lang.String filterStartDate, java.lang.String filterEndDate, java.lang.String email, java.lang.String encoding, int element) This is a convenience method for createExport(Configuration, String, String, String, String, String, String, int, String[], String, String, int, boolean)
int	createExport(Configuration configuration, java.lang.String campaignStartDate, java.lang.String campaignEndDate, java.lang.String filterStartDate, java.lang.String filterEndDate, java.lang.String email, java.lang.String encoding, int element, java.lang.String[] reportSuites, java.lang.String rowFilterColumnName, java.lang.String rowFilterColumnValue, int rowCount, boolean quoteOutput) Creates a classifications export job.
int	createImport(Configuration configuration, java.lang.String description, java.lang.String email, java.lang.String[] header, java.lang.String element, boolean checkDivisions, boolean exportResults, boolean overwrite, java.lang.String... reportSuites) Creates an import job.
JSONArray	getCompatibilityElements(Configuration configuration, java.lang.String... reportSuites) Returns the available elements for a given report suite, and compatibility across report suites.
JSONArray	getExport(Configuration configuration, int id, int page) Retrieves a page of data, known as a file segment, from a completed classifications job.
JSONArray	getFilters(Configuration configuration, int element, java.lang.String[] reportSuites) Returns classification export filters.
JSONObject	getStatus(Configuration configuration, int jobId) Checks for the status of a job.
JSONObject	getTemplate(Configuration configuration, java.lang.String[] reportSuites, java.lang.String element, java.lang.String encoding, java.lang.String... classifications) Retrieves a template to use for importing classifications data.
boolean	populateImport(Configuration configuration, int jobId, int page, java.util.Collection<java.lang.String[]> rows) Appends row data to a previously created import job.

Method Detail

getStatus

JSONObject getStatus(Configuration configuration,
                     int jobId)
              throws SitecatalystException

Checks for the status of a job.

Parameters:

configuration - Web service support configuration

jobId - Classification job identifier

Returns:

A JSONObject containing the job information. The object is of the following structure:

{
id: (int),
type: (string: "Job"|"File"),
viewable_pages: (int),
status: (string: "Waiting For User Data"|"In Progress"|"Completed"|"Completed--With Errors")
}


Throws:

SitecatalystException - SitecatalystException

getCompatibilityElements

JSONArray getCompatibilityElements(Configuration configuration,
                                   java.lang.String... reportSuites)
                            throws SitecatalystException

Returns the available elements for a given report suite, and compatibility across report suites.

Parameters:

configuration - Web service support configuration

reportSuites - Report suite identifiers

Returns:

A JSONArray of JSONObjects containing compatible elements. The objects are of the following structure:

{
id: (int),
name: (string)
}

Throws:

SitecatalystException - SitecatalystException

getFilters

JSONArray getFilters(Configuration configuration,
                     int element,
                     java.lang.String[] reportSuites)
              throws SitecatalystException

Returns classification export filters. The returned data consists of values that can be passed in as parameters of createExport(com.day.cq.wcm.webservicesupport.Configuration, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, int, java.lang.String[], java.lang.String, java.lang.String, int, boolean), including column numbers and names, and valid dates for filtering data rows in a classifications export.

Parameters:

configuration - Web service support configuration

element - Element for which you want to get file information

reportSuites - Array of report suite identifiers

Returns:

A JSONArray of JSONObjects containing the information about valid data filters for a classification job. The objects are of the following structure:

{
filter_dates: [{date: (string)},...]
columns: [{num: (int), name: (string)},...]
}

Throws:

SitecatalystException - SitecatalystException

createExport

int createExport(Configuration configuration,
                 java.lang.String campaignStartDate,
                 java.lang.String campaignEndDate,
                 java.lang.String filterStartDate,
                 java.lang.String filterEndDate,
                 java.lang.String email,
                 java.lang.String encoding,
                 int element,
                 java.lang.String[] reportSuites,
                 java.lang.String rowFilterColumnName,
                 java.lang.String rowFilterColumnValue,
                 int rowCount,
                 boolean quoteOutput)
          throws SitecatalystException

Creates a classifications export job. This file represents classifications for a given relation. Before calling this API, use getFilters(Configuration, int, String[]) to obtain valid column numbers and names, and filter dates. After creating an export job, use getStatus(Configuration, int) to determine when the export data is ready for download. When ready, use getExport(com.day.cq.wcm.webservicesupport.Configuration, int, int) to retrieve the data.

Parameters:

configuration - Web service support configuration

campaignStartDate - The campaign start date. Accepts any date string parseable by php:date(). Accepts the keywords ::all:: and ::active:: to filter by all campaigns, or by only active ones.

campaignEndDate - The campaign end date. Accepts any date string parseable by php:date().

filterStartDate - The start date for including rows in the export. Accepts any date string parseable by php:date().

filterEndDate - The end date for including rows in the export. Accepts any date string parseable by php:date().

email - E-Mail address to receive job notifications.

encoding - The language encoding to use with the export file. For example, UTF-8.

element - Relation identifier of classification the import should be done for. You get this ID as a return value from getCompatibilityElements(Configuration, String...).

reportSuites - (Optional) The list of report suites on which classifications exports data.

rowFilterColumnName - (Optional) The column name that classifications checks for cell values that match the value specified in the row_match_filter_match_column_value parameter.

rowFilterColumnValue - (Optional) Include this parameter when using the row_match_filter_match_column_name parameter. If the cell value matches the value, classifications includes it in the export. Include ::empty:: to filter empty rows.

rowCount - (Optional) Limits the number of data rows in the export file to the specified value. The default is 1000.

quoteOutput - Whether to quote the output. In some cases, turning this on helps with duplicate keys containing whitespace.

Returns:

Export job identifier

Throws:

SitecatalystException - SitecatalystException

createExport

int createExport(Configuration configuration,
                 java.lang.String campaignStartDate,
                 java.lang.String campaignEndDate,
                 java.lang.String filterStartDate,
                 java.lang.String filterEndDate,
                 java.lang.String email,
                 java.lang.String encoding,
                 int element)
          throws SitecatalystException

This is a convenience method for createExport(Configuration, String, String, String, String, String, String, int, String[], String, String, int, boolean)

Parameters:

configuration - Web service support configuration

campaignStartDate - The campaign start date. Accepts any date string parseable by php:date(). Accepts the keywords ::all:: and ::active:: to filter by all campaigns, or by only active ones.

campaignEndDate - The campaign end date. Accepts any date string parseable by php:date().

filterStartDate - The start date for including rows in the export. Accepts any date string parseable by php:date().

filterEndDate - The end date for including rows in the export. Accepts any date string parseable by php:date().

email - E-Mail address to receive job notifications.

encoding - The language encoding to use with the export file. For example, UTF-8.

element - Relation identifier of classification the import should be done for. You get this ID as a return value from getCompatibilityElements(Configuration, String...)

Returns:

result as provided by createExport(Configuration, String, String, String, String, String, String, int, String[], String, String, int, boolean)

Throws:

SitecatalystException - #createExport(Configuration, String, String, String, String, String, String, int, String[], String, String, int, boolean).

See Also:

createExport(Configuration, String, String, String, String, String, String, int, String[], String, String, int, boolean)

getExport

JSONArray getExport(Configuration configuration,
                    int id,
                    int page)
             throws SitecatalystException

Retrieves a page of data, known as a file segment, from a completed classifications job.

Parameters:

configuration - Web service support configuration

id - The ID of the export file you want to view. You can get this value from getStatus(Configuration, int).

page - The number of the data page you want to view from the export job. Default is 1. The viewable_pages value in getStatus(Configuration, int) indicates the number of data pages in the job. Valid values for page are between 1 and the value of viewable_pages.

Returns:

A JSONArray of JSONObjects containing information from a single data page of a classifications export job. The objects are of the following structure:

{
warnings: [(string),...]
header: [(string),...]
data: [[(string)],...]
}

Throws:

SitecatalystException - SitecatalystException

getTemplate

JSONObject getTemplate(Configuration configuration,
                       java.lang.String[] reportSuites,
                       java.lang.String element,
                       java.lang.String encoding,
                       java.lang.String... classifications)
                throws SitecatalystException

Retrieves a template to use for importing classifications data.

Parameters:

configuration - Web service support configuration

reportSuites - The report suite where you want to import data

element - relation_id for which you want to get a template (e.g. 101=evar1, 51=product, etc)

encoding - The encoding to use for the template

classifications - Optional array of text classification names to include as columns in the template

Returns:

A JSONObject containing the template data for a classifications import. The objects are of the following structure:

{
rsid: (string),
site_title: (string),
template: (string),
}

Throws:

SitecatalystException - SitecatalystException

createImport

int createImport(Configuration configuration,
                 java.lang.String description,
                 java.lang.String email,
                 java.lang.String[] header,
                 java.lang.String element,
                 boolean checkDivisions,
                 boolean exportResults,
                 boolean overwrite,
                 java.lang.String... reportSuites)
          throws SitecatalystException

Creates an import job. To successfully submit an import, call createImport(Configuration, String, String, String[], String, boolean, boolean, boolean, String...) to specify the parameters for the Import job and the header columns to be classified. After submitting the job, you can iteratively populate row data by calling populateImport(Configuration, int, int, Collection). After sending all data, call commitImport(Configuration, int) to finalize the Import job and submit it to the processing queue.

Parameters:

configuration - Web service support configuration

description - Description of the import job.

email - E-Mail address to receive job notifications.

header - Array of column values for classification.

element - The report for which you want to perform a classifications import.

checkDivisions - Specifies whether to check report suites for compatible divisions.

exportResults - Specifies whether to automatically perform an export when the import job finishes processing.

overwrite - Specifies whether to overwrite data when conflicts occur.

reportSuites - Optional list of report suites to receive the import job.

Returns:

Import job identifier

Throws:

SitecatalystException - SitecatalystException

populateImport

boolean populateImport(Configuration configuration,
                       int jobId,
                       int page,
                       java.util.Collection<java.lang.String[]> rows)
                throws SitecatalystException

Appends row data to a previously created import job. Data can be separated into pages, but the pages must be sent sequentially (either ascending or descending) to avoid errors when jobs are processed.

Note: Individual job pages cannot exceed 25,000 rows.

Parameters:

configuration - Web service support configuration

jobId - Job identifier to append row data

page - Page number that identifies the sequential position in the import job. For example, if you submit a spreadsheet with 1000 values, divided into 4 pages, page 1 includes values 1 - 250, page 2 includes values 251 - 500, and so on.

rows - Collection of row data that matches the column heading

Returns:

true if population was successful, false otherwise.

Throws:

SitecatalystException - SitecatalystException

commitImport

boolean commitImport(Configuration configuration,
                     int jobId)
              throws SitecatalystException

Commits the import for processing.

Parameters:

configuration - Web service support configuration

jobId - Import job identifier

Returns:

true if job has been processed successfully, false otherwise.

Throws:

SitecatalystException - SitecatalystException