Jump to: navigation, search

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.
This page was last edited on May 29, 2018, at 20:38.
Comments or questions about this documentation? Contact us for support!