Reporting API

Overview

The Reporting API provides access to the historical reporting data collected by the Genesys Knowledge Center Server.

Historical reporting is based on atomic events captured by the solution during its operations. These events are produced by activities carried out via the Knowledge API and, optionally, by Management API and application activities, as well.

Authorization

You must have agent or reporter privileges to access the Reporting API, as noted below. This can be configured in the Knowledge Center Administrator plugin.

Collected Data

Data collected for each event consists of two parts:

• Basic structure—fixed event attributes captured for all events in the system
• Event-specific structure—event-specific data that is only captured for events of a specific type and which provides information that is valuable for understanding that type of event

Data expiration

Events stored in the reporting index are subject to expiration, with a default expiration period of 14 days.

{
    "history" : {
        "_ttl" : { "enabled" : true, "default" : "14d" }
    }
}

You can override this value by replacing the default configuration value in the Genesys Knowledge Center Server options, as shown here:

option: reporting\ttl
value: 0 or <number><unit>
default: 14d
-1 - infinite ttl
<number><unit> - defines period for ttl
unit: d (days), m (minutes), h (hours), or w(weeks)
Need restart: yes

The value of this option is applied when any node in the cluster is started.

Basic Structure

Attribute	Required	Type	Description
nodename	Yes	String	Name of the node for which the event was generated
knowledgebase	Yes	String	ID of the knowledge base that event belongs to
language	Yes	String	Language of data that the operation is executed with
agentId	No	String	ID of the agent involved in operation
customerId	No	String	Customer identity
timestamp	Yes	Date-Time	UTC timestamp for the operation
duration	Yes	int	Duration of the operation in ms
type	Yes	enum	Event type (comes from a fixed list of all operations that create events)
tenantId	Yes	String	Tenant ID
sessionId	No	String	Session ID provided by Genesys Knowledge Center Server
visitId	No	String	ID of the visit tracked by Genesys Proactive Engagement
Originator	Yes	enum	Originator of event, could be AGENT or CUSTOMER
keyNouns	No	String []	List of key Nouns from text of user query
keyProperNouns	No	String []	List of key Proper Nouns from text of user query
keyVerbs	No	String []	List of key Verbs from text of user query
keyAdjectives	No	String []	List of key Adjectives from text of user query
remoteIp	No	String	IP addres off client, that called GKS functionality that burnt this particular record in history
geoLocationHash	No	String	HashCode of geo location, that was determined against obtained remoteIp for this history record
lonLat	No	double []	Longtitude and Latitude of geo position against obtained remoteIp for this history record
countryCode	No	String	Code of country for this particular geo location.

Event Types

EVENT TYPE	DESCRIPTION	PARAMETERS
FEEDBACK	Feedback to one of the knowledge elements	query: Query document: Document agentId: String customerId: String feedbacktype: enum language: String
OPEN	Events describing the viewed content	document: Document agentId: String customerId: String language: String
NONANSWERED	Events that indicate that the user's question was not answered	query: Query language: String customerId: String agentId: String
SEARCH	Search request posted with results returned	query: Query- search query result: array<Document> - full document or just document ids (depends on the application configuration) agentId: String customerId: String language: String
USE	Events that indicate that document used by agent to reply customer	document: Document agentId: String language: String

Query

Field	Type	Description
query	String	User-typed query string
filters	FilterCondition	Array of filters
categories	String	Array of categories
tags	String	Array of tags

API

You can use the Reporting API to gather the following kinds of information:

• Agent history for a specific time period
• Customer history for a specific time period
• Articles that have been used (with positive feedback) during a specific time period
• Queries posted during a specific time period
• Knowledge base summaries, providing:
  • Static information about a knowledge base, such as its name, ID, or languages
  • Dynamic information, such as the number of articles or categories it currently contains, the average query time, or the average relevancy of the top answer

Search History

Description	Search history activities for a specific time period
URL	/history
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	Agent
Parameters	Parameter Type Required Location Description id String No Body History entry ID start Date No Body Start date of requested period end Date No Body End date of requested period types EventType No Body Filter based on the event types described in the table above kbId String No URL Knowledge base ID lang String No URL Language tenantId String Yes URL Tenant identifier sessionId String No Body Session ID customer String No Body Customer name agent String No Body Agent name
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). data HistoryEntry No List of found history entries.

Get history of queries

HistoryOfQueries Complex Type

Field	Type	Description
count	Int	total count of query items according to given parameters
From	Int	pagination offset
Size	Int	count of items in current page (pagination)
items	HistoryOfQueryItem[]	request history items itself

HistoryOfQuery Complex Type

Field	Type	Description
query	String	Registered in the storage history of the user query
Moment	Datetime	The moment of time when this query was sent to the server
userId	String	User identified on behalf of which query is received
sessionId	String	Session identifier related to the given user query

Get history of queries

Description	Gathers history of user queries.
URL	/{kbId}/{lang}/queries
Method	GET
Request Content-Type	application/json
Response Content-Type	application/json
Role	Reporter
Url identifiers	Parameter Type Required URL/Body Description kbId String No URL Knowledge base ID lang String No URL Language
Parameters	Parameter Type Required Description sessionId String No Session ID tenantId String Yes Tenant identifier customerId String No Customer name from Int No Starting position of pagination, default=0 size Int No Page size of pagination, default=0. 0 means that you will retrieve all queries that match the input parameters.
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation -duplicates the HTTP code error Error Yes (if statusCode <> OK) Detailed information about the error message. Becomes present only if the operation is executed unsuccessfully (statusCode<>OK). response HistoryOfQueries Yes Retrieved history of queries
Notes

Export History

Description	Gather history for a specific tenant for a specific date range.
URL	/history/export
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	Reporter
Parameters	Parameter Type Required URL/Body Description start Date No Body Start date of requested period end Date No Body End date of requested period types EventType No Body Filter based on the event types described in the table above kbId String No URL Knowledge base ID lang String No URL Language tenantId String Yes URL Tenant identifier sessionId String No Body Session ID customer String No Body Customer name agent String No Body Agent name
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). url String No Path to archive destination applicationName String No Knowledge node name
Notes	Archive settings can be configured under the Options tab of the Knowledge Node application in Genesys Administrator. For more information on configuration options for Knowledge Center Server, consult the Knowledge Center Options Reference Guide.