Internal Documentation

This document may change at any time without prior notice.
Changes may break backwards compatibility.
Do not rely on it!

Session Statistics REST service specification

1. Purpose

This document is the specification of the statistics retrieval REST service.

2. Storing of statistical relevant timestamps

Session timestamps (start, end) must always be stored as UTC+0000 timestamps (see jira: UNBLU-2884)

3. Session Statistics Timezone


The time zone of user datetime ranges is specified via configuration property statisticsTimeZoneInUTC.
This property must be modifiable in the adminUI and be stored on account level. The default (if no such property has been set) is UTC+0000.

The available values and how they're supposed to be displayed is visible in this attachment here.


The format of the propertys value is: UTC+-XXYY, where X is the time offset in hours, and Y the offset in minutes. Example: UTC+0100. UTC itself should be specified as this: UTC+0000.

Important: The UTC offset of the property must not in any way include daylight saving calculations. That is: Switzerland/Bern is always UTC+0100, no matter whether Switzerland has daylight savings or not and no matter whether summer or winter time would apply for any of the statistical dates.


Handling of daylight saving times may need more consideration in future releases, depending on the customers requirements / needs.

4. Session Statistics Rest Service

4.1. General guidelines

The following rules apply for the session statistics rest service:

4.1.1. Request (parameter / argument) guidelines

  • Whenever possible, the service REST calls should use dates and date ranges, since they are timezone independant.
  • Date ranges specified in REST calls have a start date which is inclusive and an end date, which is exclusive.
  • On the server, date ranges will be extended to datetime values with exact timestamps in UTC. To achieve this, the server picks 00:00 for the start (inclusive) and end day (exclusive) of the specified timezone statisticsTimeZoneInUTC. To retrieve the data from the RDBMS, the server then converts these datetime timestamps to UTC+0000.
    Example:
    • Customer wants to have a report for January 1st, 2014. Account has PST (Pacific Standard Time UTC-0800) as configured timezone.
    • Browser calls REST service with startDate=2014-01-01 and endDate=2014-01-02
    • Server extends date to datetime values: startDatetime=2014-01-01T00:00:00 and endDatetime=2014-01-02T00:00:00
    • Server picks up statisticsTimeZoneInUTC and converts from configured PST to UTC+0000: utcStartDatetime=2014-01-01T08:00:00 and utcEndDatetime=2014-01-02T08:00:00
    • Server retrieves all session informations utcStartDatetime <= utcStoredSessionStartDatetime < utcEndDatetime
  • The format of date arguments (as part of the REST call path) is: YYYY (full year) for year and MM (1-based) for month
  • The format of date and time parameters used in REST call requests is the extended format of ISO-8601 (see http://en.wikipedia.org/wiki/ISO_8601 for details) without the 'Z' zulu time zone indicator (or any other time zone designator appended).
    To note it explicitly here, it is: YYYY-MM-DD for a date, hh:mm:ss for time and YYYY-MM-DDThh:mm:ss for datetime (delimiter: character 'T').
    Note
    :
    • month, day, hour, minute and seconds must have two digits at all times. The following date is not ISO-8601 compliant: 2014-1-2. Correct would be: 2014-01-02
    • the typical 'Z' character suffix (indicating "zulu time" or UTC) must be omitted, because it is not zulu time transmitted (nor is it "local time" technically, but that's something, the server has to deal with)
    • in Javascript and Java, when retrieving the month of a date object, it is 0-based. January is returned as month 00, February 01, March 02, etc. ISO-8601 requires months to start with January=01, February=02, etc. Be aware of that, when constructing or parsing ISO dates manually.
    • in Javascript, when creating date objects using the constructor, local time is used. When later using toISOString, it will produce wrong results. See "Hints for the Javascript coder" chapter below for details.


Examples:

2014-01-01
2013-12-30
2014-12-01T03:00:10

4.1.2. Response guidelines

  • The response format is typically JSON. This JSON may contain metadata properties, such as __cls or pandorasBox. The caller must ignore "unexpected" or "unknown" properties, i.e. he must only interpret the properties described in the REST service call details.
  • The timezone of any datetime value in the response must be the one effectively evaluated by the server (either statisticsTimeZoneInUTC or the default UTC+0000).
  • Format of date and time parameters in the response is the extended format of ISO-8601 (see http://en.wikipedia.org/wiki/ISO_8601 for details) including the appropriate time zone designator in the format +-hhmm
    Example: 2014-01-01T03:45:12+0100

4.2. REST service call details

4.2.1. getMonthsContainingData call

getMonthsContainingData call
url/unblu/rest/statsService/getMonthsContainingData/amount
purposeRetrieve a list of the now - XX months containing session data
arguments
nametyperange / formatdefaultcomments
amountinteger1 - 1212

optional.

If provided, retrieves the last amount months.
If not provided, retrieves the default amount of last months. Use -1 to indicate "all" months (may need lots of time!)

parametersnone
result
{
  timezone: "UTC+0100",
  months: [
   {year: 2013, month: 12},
   {year: 2014, month: 1}
  ]
}

month values are 1-based (1 for January, 2 for February, etc).

nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the required information
monthsarray array of months with existing session data
yearinteger0 - INFINITEthe full year
monthinteger1 - 12the month (1-based)

4.2.2. getSummaryOfMonth call

getSummaryOfMonth call
url/unblu/rest/statsService/getSummaryOfMonth/year/month
purpose

Retrieve a summary for the range of one month. The summary includes the following session informations:

  • averageDuration
  • maxConcurrentConnections
  • totalDuration
  • totalSessions
  • uniqueOwners
arguments
nametyperange / formatdefaultcomments
yearstringYYYY (full year)"current" - interpreted as the current yearThe year to retrieve the summary for
monthstringMM (1-based)"current" - interpreted as the current monthThe month to retrieve the summary for
parameters

none

result
{
  timezone: "UTC+0100",
  summaries: [
    {
      year: 2014,
      month: 1,
      averageDuration: 100,
      totalDuration: 1200,
      totalSessions: 3,
      maxConcurrentConnections: 0,
      uniqueOwners: 2
    }
  ]
}
nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the summary information
summariesarray array of summary information (in this call, always only contains one element)
yearinteger0 - INFINITEthe full year of this summary's month
monthinteger1 - 12the month, this summary was created for (1-based)
averageDurationfloat0 - INFINITEaverage session duration in seconds
totalDurationinteger0 - INFINITEtotal (summarized) session duration in seconds
totalSessionsinteger0 - INFINITEtotal amount of sessions
maxConcurrentConnectionsinteger0 - INFINITEthe observed max of concurrent connections
uniqueOwnersinteger0 - INFINITEthe number of unique agents that started sessions

4.2.3. getDailySummaryOfMonth call

getDailySummaryOfMonth call
url

/unblu/rest/statsService/getDailySummaryOfMonth/year/month/day

or

/unblu/rest/statsService/getDailySummaryOfMonth/dayAsAdverb

purpose

Retrieve list of summarized values for the range of one day. The summarized values include

  • averageDuration
  • maxConcurrentConnections
  • totalDuration
  • totalSessions
  • uniqueOwners
arguments
nametyperange / formatdefaultcomments
yearstringYYYY (full year)"current" - interpreted as the current yearThe year to retrieve the summary for
monthstringMM (1-based)"current" - interpreted as the current monthThe month to retrieve the summary for
daystringDDempty

The day to retrieve the summary for.
If "current" is specified, it is interpreted as the current month.

Optional: If left away, will retrieve a list of all days of the given month

Alternate variant with only dayAsAdverb

nametyperange / formatdefaultcomments
dayAsAdverbstring"yesterday", "today""yesterday"Calculate the day to retrieve the summary for relative to the current day
parametersnone
result
{
  timezone: "UTC+0100",
  summaries: [
    {
      year: 2014,
      month: 1,
      day: 1,
      averageDuration: 100,
      totalDuration: 1200,
      totalSessions: 3,
      uniqueOwners: 2
    },
    {
      year: 2014,
      month: 1,
      day: 2,
      averageDuration: 200.5,
      totalDuration: 401,
      totalSessions: 2,
      uniqueOwners: 2
    }
  ]
}
nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the summary information
summariesarray array of summary information.
The array contains entries for each day of the selected month that provides session data. Days without session data may be ommited by the server.
The array is ordered with date ascending.
yearinteger0 - INFINITEthe full year of this summary's month
monthinteger1 - 12the month, this summary was created for (1-based)
dayinteger1 - 31the day, this summary was created for
averageDurationfloat0 - INFINITEaverage session duration in seconds
totalDurationinteger0 - INFINITEtotal (summarized) session duration in seconds
totalSessionsinteger0 - INFINITEtotal amount of sessions
maxConcurrentConnectionsinteger0 - INFINITEthe observed max of concurrent connections
uniqueOwnersinteger0 - INFINITEthe number of unique agents that started sessions

4.2.4. getSessionsOfDay call

getSessionsByDay call
url

/unblu/rest/statsService/getSessionsOfDay/year/month/day

or

/unblu/rest/statsService/ getSessionsOfDay / dayAsAdverb

purpose

Retrieve list of all sessions details for the range of one day. The session details include:

  • accountId
  • startTime
  • endTime
  • duration
  • ownerId
  • ownerFirstName
  • ownerLastName
  • ownerDisplayName
  • terminatorId
  • terminatorFristName
  • terminatorLastName
  • terminatorDisplayName
arguments

name

typerange / formatdefaultcomments
yearstringYYYY (full year)"current" - interpreted as the current yearThe year to retrieve the sessions for
monthstringMM (1-based)"current" - interpreted as the current monthThe month to retrieve the sessions for
daystringDD"current" - interpreted as the current day

The day to retrieve the sessions for

Alternate variant with only dayAsAdverb

nametyperange / formatdefaultcomments
dayAsAdverbstring"yesterday", "today""yesterday"Calculate the day to retrieve the sessions for relative to the current day
parametersnone
result
{
  timezone: "UTC+0100",
  sessions: [
    {
      year: 2014,
      month: 1,
      day: 1,
      startTime: "2014-01-01T09:13:03+0100",
      endTime: "2014-01-01T09:15:12+0100",
      duration: 129,
      ownerId: "6X-4_c9_S-345izSKIwDQ",
      ownerFirstName: "John",
      ownerLastName: "Doe",
      ownerDisplayName: "John Doe",
      terminatorId: "6X-4_c9_S-345izSabcDQ",
      terminatorFirstName: "Angie",
      terminatorLastName: "Johnson",
      terminatorDisplayName: "Angie Johnson"
    },
    {
      year: 2014,
      month: 1,
      day: 1,
      startTime: "2014-01-01T09:16:03+0100",
      endTime: "2014-01-01T09:17:04+0100",
      duration: 61,
      ownerId: "6X-4_c9_S-345izSKIwDQ",
      ownerFirstName: "John",
      ownerLastName: "Doe",
      ownerDisplayName: "John Doe",
      terminatorId: "6X-4_c9_S-345izSabcDQ",
      terminatorFirstName: "Angie",
      terminatorLastName: "Johnson",
      terminatorDisplayName: "Angie Johnson"
    }
  ]
} 
nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the session information
sessionsarray array of session information.
The array contains entries for the given day.
The array is ordered with session startTime ascending.
yearinteger0 - INFINITEthe full year of this session info's month
monthinteger1 - 12the month, this session info was created for (1-based)
dayinteger1 - 31the day, this session info was created for
startTimestringISO-8601 extended format (including timezone designator)session start time in timezone as selected for the call (see statisticsTimeZoneInUTC)
endTimestringISO-8601 extended format (including timezone designator)session end time in timezone as selected for the call (see statisticsTimeZoneInUTC)
durationinteger0 - INFINITEduration of session in seconds
ownerIdstringWebUUIDan (unique) identifier of the session owner (typically, the agent initiating the session)
ownerFirstNamestring the first name of the session owner
ownerLastNamestring 

the last name of the session owner

ownerDisplayNamestring if present: the preferred way to display the session owner's name
terminatorIdstringWebUUIDan (unique) identifier of the session terminator (may be a person or the system, e.g. due to timeout)
terminatorFirstNamestring the first name of the session terminator
terminatorLastNamestring 

the last name of the session terminator

terminatorDisplayNamestring if present: the preferred way to display the session terminator's name

4.2.5. getAgentSummaryOfMonth call

getAgentSummaryOfMonth call
url/unblu/rest/statsService/getAgentSummaryOfMonth/year/month
purpose

Retrieve a list of all agents that initated a session in the specified month and return a summary for each. The following summarizing informations are provided for each agent:

  • agentId
  • agentFirstName
  • agentLastName
  • agentDisplayName
  • averageDuration
  • totalDuration
  • totalSessions
arguments
nametyperange / formatdefaultcomments
yearstringYYYY (full year)"current" - interpreted as the current yearThe year to retrieve the agent summary for
monthstringMM (1-based)"current" - interpreted as the current monthThe month to retrieve the agent summary for
parametersnone
result
{
  timezone: "UTC+0100",
  agents: [
    {
      year: 2014,
      month: 1,
      agentId: "6X-4_c9_S-345izSKIwDQ",
      agentFirstName: "John",
      agentLastName: "Doe",
      agentDisplayName: "John Doe",
      averageDuration: 821,
      totalDuration: 821,
      totalSessions: 1
    }
  ]
} 
nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the agent information
agentsarray 

array of agent information for the specified month.
The array is ordered by agentLastName first, agentFirstName second.
The array includes informations for all agents, even if the agent did not start a session

yearinteger0 - INFINITEthe full year of this agent info's month
monthinteger1 - 12the month, this agent info was created for (1-based)
agentIdstringWebUUIDunique identifier of the agent (corresponds to the userId in the user list of the adminRestService)
agentFirstNamestring the first name of the session owner
agentLastNamestring 

the last name of the session owner

agentDisplayNamestring if present: the preferred way to display the session owner's name
averageDurationfloat0 - INFINITEthe average duration of a session with this agent participating
totalDurationinteger0 - INFINITEthe total duration, this agent was participating in co-browsing sessions (in seconds)
totalSessionsinteger0 - INFINITE

the amount of sessions, this agent was participating

 

 

4.2.6. getAgentSessionsOfMonth call

getAgentSessionsOfMonth call
url/unblu/rest/statsService/getAgentSessionsOfMonth/agentId/year/month
purpose

Retrieve list of all sessions details for the range of one month filtered by an agentId. The session details include:

  • accountId
  • startTime
  • endTime
  • duration
  • ownerId
  • ownerFirstName
  • ownerLastName
  • ownerDisplayName
  • terminatorId
  • terminatorFristName
  • terminatorLastName
  • terminatorDisplayName
arguments
nametyperange / formatdefaultcomments
agentIdstringWebUUID"current" - interpreted as the current logged in userThe agent id to retrieve the agent session details for
yearstringYYYY (full year)"current" - interpreted as the current yearThe year to retrieve the agent session details for
monthstringMM (1-based)"current" - interpreted as the current monthThe month to retrieve the agent session details for
parametersnone
result
{
  timezone: "UTC+0100",
  sessions: [
    {
      year: 2014,
      month: 1,
      startTime: "2014-01-01T09:13:03+0100",
      endTime: "2014-01-01T09:15:12+0100",
      duration: 129,
      ownerId: "6X-4_c9_S-345izSKIwDQ",
      ownerFirstName: "John",
      ownerLastName: "Doe",
      ownerDisplayName: "John Doe",
      terminatorId: "6X-4_c9_S-345izSabcDQ",
      terminatorFirstName: "Angie",
      terminatorLastName: "Johnson",
      terminatorDisplayName: "Angie Johnson"
    },
    {
      year: 2014,
      month: 1,
      startTime: "2014-01-01T09:16:03+0100",
      endTime: "2014-01-01T09:17:04+0100",
      duration: 61,
      ownerId: "6X-4_c9_S-345izSKIwDQ",
      ownerFirstName: "John",
      ownerLastName: "Doe",
      ownerDisplayName: "John Doe",
      terminatorId: "6X-4_c9_S-345izSabcDQ",
      terminatorFirstName: "Angie",
      terminatorLastName: "Johnson",
      terminatorDisplayName: "Angie Johnson"
    }
  ]
}  
nametyperange / formatcomments
timezonestringUTC+-XXYYthe effective timezone used by the server to select the agent session information
sessionsarray array of agent session information.
The array contains entries for the given month and agent.
The array is ordered with session startTime ascending.
yearinteger0 - INFINITEthe full year of this session info's month
monthinteger1 - 12the month, this session info was created for (1-based)
startTimestringISO-8601 extended format (including timezone designator)session start time in timezone as selected for the call (see statisticsTimeZoneInUTC)
endTimestringISO-8601 extended format (including timezone designator)session end time in timezone as selected for the call (see statisticsTimeZoneInUTC)
durationinteger0 - INFINITEduration of session in seconds
ownerIdstringWebUUIDan (unique) identifier of the session owner (typically, the agent initiating the session)
ownerFirstNamestring the first name of the session owner
ownerLastNamestring 

the last name of the session owner

ownerDisplayNamestring if present: the preferred way to display the session owner's name
terminatorIdstringWebUUIDan (unique) identifier of the session terminator (may be a person or the system, e.g. due to timeout)
terminatorFirstNamestring the first name of the session terminator
terminatorLastNamestring 

the last name of the session terminator

terminatorDisplayNamestring if present: the preferred way to display the session terminator's name

4.2.7. getChatProtocolForSessions call

getChatProtocolForSessions call
url/unblu/rest/statsService/getChatProtocolForSessions/sessionIds
purposeRetrieve chat protocols for a list of sessions
arguments
nametyperange / formatdefaultcomments
sessionIdslist of Stringcomma separated list of session idsnone

mandatory.

 

parametersnone
result
{
	"sessions":[
		{
			"sessionId":"YZZ..."
			"messages":[
				{"senderDisplayName":"John","senderId":"rhI...","time":"2013-10-10T14:15:45+0100","message":"Hello Linda"},	
				{"senderDisplayName":"Linda","senderId":"aVH...","time":"2013-10-10T14:15:45+0100","message":"Hello John"}
			]
		},
		{
			"sessionId":"Nyb..."
			"messages":[
				{"senderDisplayName":"Jude","senderFirstName":"Jude","senderLastName":"Miller","senderId":"qrJ...","time":"2013-10-10T14:15:45+0100","message":"Hello Kate"},	
				{"senderDisplayName":"Kate","time":"2013-10-10T14:15:45+0100","message":"Hello Jude"}
			]
		}		
	]
}

The return value contains an object with a single property "sessions", which contains an array holding a chat protocol for

every session requested.

Each chat protocol entry in the list holds a "sessionId" property with the session id and a "messages" property with an array

of chat messages.

 

nametyperange / formatcomments
sessionsarray array of chat protocols, one for every sessionId in the request
sessionIdstring the sessionId of the session, the chat protocol belongs to
messagesarray array of chat messages
timestringISO-8601 extended format (including timezone designator)the time the message was sent
senderDisplayNamestring display name of the sender
senderFirstNamestring optional first name of the sender
senderLastNamestring optional last name of the sender
senderIdstring optional id of the sender
messagestring The actual message

4.2.8. getParticipationProtocolForSessions call

getChatProtocolForSessions call
url/unblu/rest/statsService/getParticipationProtocolForSessions/sessionIds
purposeRetrieve participation protocols for a list of sessions
arguments
nametyperange / formatdefaultcomments
sessionIdslist of Stringcomma separated list of session idsnone

mandatory.

 

parametersnone
result
{
	"sessions":[
		{
			"sessionId":"YZZ...",
			"participations":[
				{
					"startTime":"2013-10-10T14:14:08+0100",
					"endTime":"2013-10-10T14:38:46+0100",
					"type":"OWNER",
					"userName":"José Valcarce",
					"userId":"1QL..."
				}
			],
		}
	]
}

The return value contains an object with a single property "sessions", which contains an array holding a chat protocol for

every session requested.

Each chat protocol entry in the list holds a "sessionId" property with the session id and a "participations" property with an array

of chat messages.

 

nametyperange / formatcomments
sessionsarray array of chat protocols, one for every sessionId in the request
sessionIdstring the sessionId of the session, the chat protocol belongs to
participationsarray array of participations
startTimestringISO-8601 extended format (including timezone designator)the time the participation has started
endTimestringISO-8601 extended format (including timezone designator)the time the participation has ended
typestringOWNER or GUESTtype of the participation
userNamestring display name of the participation
userIdstring optional id of the sender

 

5. Hints for the Javascript coder

The following hints are targetted to the javascript coder that has to use the session stats service. It includes hints of common pitfalls.

In Javascript, the Date.prototype.toISOString function provides simple means to produce a proper ISO string. However, toISOString is always UTC+0000 based. When constructing a date however, e.g. with var dt = new Date(2014, 1, 1, 0, 0, 0, 0); the input is interpreted as local time. This is not obvious and leads to a number of "strange behaviours".
Example:

// BAD EXAMPLE - do not do this!

// the following example is executed on a computer with local time UTC+0100
var dt = new Date(2014, 0, 1, 0, 0, 0, 0); // note: month is 0-based: 0 means "January"
var localDate = dt.toString();  // localDate is "Wed Jan 01 2014 00:00:00 GMT+0100 (Mitteleuropäische Zeit)"
var isoDate = dt.toISOString(); // isoDate is "2013-12-31T23:00:00.000Z" -> Note the fact, that year, month and day have switched, due to timezone conversion!

From this example, we can derive, that it is a bad idea, to use toISOString in conjunction with Date objects created from the standard constructor.

Instead, use this:

// GOOD EXAMPLE: This is how to do it correctly.

// the following example is executed on a computer with local time UTC+0100
var dt = new Date(Date.UTC(2014, 0, 1, 0, 0, 0, 0));
var localDate = dt.toString();  // localDate is "Wed Jan 01 2014 01:00:00 GMT+0100 (Mitteleuropäische Zeit)"
var isoDate = dt.toISOString(); // isoDate is "2014-01-01T00:00:00.000Z" -> correct!