Oreka TR 2.11 Administrator Manual

Revision 2.11-6288


Table of Contents

1. Introduction
What is Oreka
Architecture
2. Pre-requisites
Server Specs
Operating System
Database
Active Recording Methods
Passive Recording (via port mirroring)
About Audio Recording Files
About Screen Recording Files
3. OrkAudio
Overview
Typical Installation (Single Server)
On Linux
On Windows
Multiple Server Configuration (OrkAudio)
Applying OrkAudio License File
Upgrade
Upgrade with RPM installer (Linux)
Upgrade with individual RPM files (Linux)
Upgrade with Windows installer
Upgrade with Windows binary archive
Files Location
Audio Output Files
Configuration Files
Log Files
Plugins Files
Audio Encodings and Formats
Wire audio encodings
Storage audio formats
Configuration
Basic Configuration
File and Path Names in OrkAudio
Configuring the VoIP plugin
Live Monitoring
Running OrkAudio
Starting the OrkAudio service
Verifying that OrkAudio started
OrkAudio Auto-Start
Migrating OrkAudio to Another Server
Load balancing - orkbalancer
Troubleshooting
OrkAudio does not record any VoIP traffic
Not possible to replay recorded files
Only one side of the conversation is recorded
Metadata is not detected
4. OrkWeb - OrkTrack
Overview
Installation
On Linux
On Windows
Upgrade
Upgrade using installer
Upgrade using WAR files
Applying OrkWeb License File
Trial versus Production license
Files Location
OrkWeb/OrkTrack Configuration files
OrkWeb/OrkTrack Log files
Running OrkWeb - OrkTrack
On Linux
On Windows
Accessing OrkWeb
Recordings
Tags
System Tag Types
User-Defined Tag Types
Using Tags
Managing Users
Login Strings
Importing CSV List of Users
Local Party Mapping
Remote Party Mapping
User Auto-Provisioning (UAP)
User Authentication with Single Sign On (SSO)
Managing Groups
Security groups
Regular groups
Access Policies
Example 1: Call center with Agents and Supervisors
Example 2: Business hosted telephony provider
Programs
Overview
Triggers
Criteria
Actions
Selective Recording (Audio and/or Screen)
Media Manager (Copy, Move, Delete, Email recordings)
Speech Analytics
File and Path Names in OrkWeb
Programs Priority
Media Servers, Services and Media Access Modes
Services
Media Access Modes
Live Monitoring (On-Demand Recording)
Quality Monitoring (QM)
Creating Scorecards
Importing Scorecards
Scoring calls based on scorecards
Generating QM reports
Security
Securing access to your media files
Securing access to the application (OrkWeb) using SSL
Foreign Language Support
Languages Included
Changing your Browser's Language
Migrating OrkWeb to Another Server
Customizing
Customizing the layout, style and colors
Customizations and software upgrades
Changing the application name
Accessing OrkWeb without specifying a port number
Troubleshooting
Cannot login as admin/admin
No recordings are appearing in the Browse page
Cannot replay recordings
Cannot login as a user I have just created
I don't get the latest recordings
OrkWeb's performance has slowed down. What do I do?
5. Addendum
Auto-Delete (obsolete)
Obsolescence Notice
Overview
Configuration Example
Deleting Remote Files
Notes
File Manager (obsolete)
Obsolescence Notice
Overview
Running Modes
Configuration
6. API
REST API
Legacy API
7. FAQ
How do I manually install orkaudio?
How do I backup oreka?
How do I configure Microsoft SQL Server (MS-SQL)?
OrkWeb does not recognize non latin-based characters?!
How do I configure a scorecard for QM?
Scorecard CSV File Format
Scorecard CSV File Example
8. Glossary
Glossary

Chapter 1. Introduction

Table of Contents

What is Oreka
Architecture

What is Oreka

Oreka is an enterprise cross-platform system for recording and retrieval of audio streams, computer screens, and text messages (SMS). It supports recording from VoIP telephony systems via active and passive recording methods It also supports recording from TDM telephony systems. An optional quality monitoring module makes it a perfect tool for measuring call center performance and track its progress. The Oreka user interface (OrkWeb) is web-based and provides a rich feature set such as call live monitoring, recordings playback, extensive search and query capabilities, audit trail, reporting, tagging, media manager, and many others.

Architecture

The Oreka system consists of a combination of the following services

  • OrkAudio : this is the audio capture background service. It supports active and passive VoIP recording as well as TDM based recording.

  • OrkTrack : this service centrally tracks activity on the entire system and logs recordings to any popular SQL database. It is also responsible for backgroud tasks such as the Media Manager, User and Group Auto-Provisioning as well as most API functionality through a RESTful interface.

  • OrkWeb : this service is the web interface accessible via any standard compliant web browser. It relies on the Tomcat web server.

  • OrkRfb : this is the screen capture background service. It relies on the RFB protocol used in VNC.

  • A range of CTI connectors : these are software services that perform Computer Telephony Integration and extract call metadata from various telephony systems such as Avaya, Cisco, Genesys, Mitel, Shoretel, etc.

The system supports multiple instances of OrkAudio and OrkRfb reporting to OrkTrack so that multiple recording servers can be seen as one recording system. OrkTrack and OrkWeb are installed as one package. They may reside on the same server as the recorder or on a different server.

For the sake of simplicity, Oreka TR will be refered to simply as Oreka in the rest of this document.

Chapter 2. Pre-requisites

Server Specs

The most important parameter for performance is CPU L2 cache. Recording higher number of concurrent calls is facilitated by using big CPU L2 caches such as 12 MB or even more.

Running Oreka in Virtual Machines (VM) is supported

Test machine (PC or Laptop or VM)

  • Dual core CPU, 2MB L2 cache
  • 2 GB RAM
  • 500 MB Hard Drive

Production Server or VM

  • 0-100 concurrent calls: Dual Core CPU, 4MB L2 Cache, 4 GB RAM
  • 100-300 concurrent calls: Quad Core CPU, 8MB L2 cache, 8 GB RAM
  • Above 300 concurrent calls: 4 CPU cores and 4GB RAM per OrkAudio engine with up to 400 calls per engine (for a total of up to 2000 concurrent calls on a single physical server)

Operating System

Oreka TR runs on Linux and Windows platforms.

OrecX's preferred platform is Linux CentOS 7 64-bit . Oreka can also be deployed on Linux CentOS 6 64-bit. All recent Windows versions are also supported since Windows XP and Windows 2003 server.

For support of other operating systems, please inquire at .

Database

MySQL is recommended as Orecx LLC's primary database environment. Oreka also supports most major database systems including MS-SQL, PostgreSQL and Oracle.

Active Recording Methods

Oreka can record telephony audio via various active recording methods such as IETF SIPREC (For BroadWorks, Metaswitch, Oracle SBC, Sonus SBC, ...), Cisco BIB and Avaya DMCC. When an active recording method is chosen, the recorder becomes an integral part of the telephony platform and interacts with it. Advantages of active recording methods are:

  • The recorder is typically only exposed to the wanted traffic rather than to the global traffic. This increases scalability, especially in use cases where only a small fraction of the traffic needs to be recorded
  • Losing recordings under intense traffic is less likely

For more details on active recording methods, please contact

Passive Recording (via port mirroring)

Passive recording via port mirroring means that the recorder does not interact with the telephony platform and silently intercepts packets and reconstructs voice sessions before saving them as audio and metadata. Advantages of port mirroring are therefore:

  • No licenses need to be acquired for the telephony platform's active recording interface, which makes the recording system more cost effective
  • The recording application has no impact whatsoever on the main telephony platform
  • It is possible to record many more types of telephony platforms via port mirroring than via active recording because a lot of telephony platforms do not offer an option for active recording

Before Oreka can start recording, ensure that VoIP traffic is seen on a server interface. Use SPAN port mirroring to get the right traffic to the Oreka server. Two configurations are possible:

  • SPAN monitoring the entire VoIP VLAN so that all traffic to and from phones is intercepted;
  • SPAN monitoring the PSTN Gateways and the Signalling server (e.g. SIP proxy, Cisco Call Manager, Avaya Communication Manager, ...)

This is to ensure that both the media traffic (RTP) and signalling (SIP, Skinny, H.323, UNISTIM, ...) are intercepted by the recorder. Use a packet analyzer such as the free Wireshark tool to verify that both types of packets are appearing on the Oreka server's interface.

Once the VoIP traffic appears on the server, you are ready to start using the Oreka software.

Mechanisms to get VoIP traffic

In terms of insertion point, Oreka can intercept packets via several mechanisms:

  • Ethernet switch SPAN monitoring port: for Ethernet switches that have this capability. For Cisco, see http://www.cisco.com/en/US/products/hw/switches/ps708/products_tech_note09186a008015c612.shtml . This is the most popular solution.
  • Ethernet tap: requires additional hardware, this option has become fairly cheap lately. See Netoptics Teeny Tap or Barracuda Ethernet Tap products for example.
  • Being installed directly on the PBX or media gateway server. Not ideal.
  • Old style Ethernet hub inserted in the Ethernet path, i.e. all traffic copied to all ports. Not recommended, do this only for testing or low traffic sites.
  • Setup the machine as an Ethernet bridge inserted in the Ethernet path. Not recommended, do this only for testing.

About Audio Recording Files

Oreka uses the compressed GSM WAV format to store audio recording files. This format is extremely universal and compact and can be played back on any media player.

This format uses about 1.6 KBytes for 1 sec of recording (or 13 kbits/sec). As an example, 2,000 hours of audio would require approximately 10 GBs of disk space.

About Screen Recording Files

Oreka uses the compressed FBS file format to store screen video recording files. This format is also used by some open source tools such as rfbproxy and tightvnc. The format is very efficient at losslessly storing screen updates compared to regular video codecs such as MPEG4 or h.264.

The bandwidth/storage requirements can vary greatly depending on screen size and how much the screens changes during recording. We have found the average storage requirement for a call center is about 1 MByte/min which translates to a bandwidth of about 133 Kbit/s per concurrent recording session.

Chapter 3. OrkAudio

Overview

OrkAudio is the Oreka audio recorder component. It is a process that runs on Windows or Linux and records audio packets received on one of the server interfaces. It can record VoIP packets as well as TDM-based voice calls.

Typical Installation (Single Server)

On Linux

Here are the steps to install OrkAudio using installers on CentOS or Red Hat Enterprise Linux (RHEL).

Requirements

  • You need a minimal installation of CentOS or RHEL. A graphical desktop is not required.
  • You need to be logged in as "root" to install the Oreka software.

Installation

  • Use the installer file provided to you by OrecX, e.g. orkaudio-1.2-660-x1459-i386.centos5-installer.sh.tar
  • Untar it: tar -xvf orkaudio-1.2-660-x1459-i386.centos5-installer.sh.tar
  • Run the installer: ./orkaudio-1.2-660-x1459-i386.centos5-installer.sh (accept all required components)
  • If the installer fails, please contact . It is also possible to attempt the procedure in the section called “How do I manually install orkaudio?”

On Windows

Requirements

  • You need to be logged in as Administrator before proceeding.
  • Access to the internet is highly recommended for download of the Oreka software.

Installation

Use the installer file provided to you by OrecX, e.g. orkaudio-1.2-657-x1463-win32-installer.zip . Copy this file to a temporary folder on the target machine, unzip it and run the embedded executable. This will install WinPcap as well as OrkAudio.

Multiple Server Configuration (OrkAudio)

When installing Oreka on multiple servers, one or more OrkAudio recording servers are reporting to a single OrkWeb/OrkTrack central server. In this case, additional configuration in both OrkWeb and OrkAudio is required.

Communication with OrkTrack

The recorder needs to communicate to OrkTrack to report the recording metadata to be stored in the database. Thus, it needs to know where OrkTrack is running.

Make sure the <TrackerHostname> entry in the OrkAudio config.xml is properly set to the OrkWeb/OrkTrack hostname or IP address.

OrkWeb access to media files

For OrkWeb to be able to access the media files stored on the recorder's server, a web server application such as Apache httpd or Apache Tomcat needs to be installed and configured on the recorder's server. For a quick solution, use the OrkWeb installer and install only the Tomcat and Java Run-Time components. E.g., run ./orkweb-1.7-2586-x64-linux-installer.sh --nomysql --nooreka on Linux. In Windows, you can stop the installer after Java and Tomcat are installed.

OrkWeb also needs some special configuration, please refer to the section called “Media Servers, Services and Media Access Modes”

For more details, contact .

Applying OrkAudio License File

For OrkAudio to run properly, a license file must be applied. This file is provided to you by OrecX (e.g. orkaudio-30-days-trial-license-20090320.txt ). Store this file in the folder where OrkAudio was installed, typically /etc/orkaudio on Linux and C:\Program Files\OrkAudio on Windows. Make sure to rename it to license.txt .

Warning: under Windows, you need to make sure file extensions are shown (go to My Computer/Explore/Tools/Folder Options/View and uncheck "Hide extensions for known file types"). Otherwise you risk naming the file licence.txt.txt without realizing it.

Whenever a new license file is applied, the orkaudio service must be restarted for the change to take effect.

Upgrade

Upgrade with RPM installer (Linux)

In this procedure, please replace version numbers with the relevant ones.

  • Take a copy of /etc/orkaudio/config.xml and /etc/orkaudio/logging.properties if you had customized them
  • # service orkaudio stop
  • # rpm -e orkaudio-addons
  • # rpm -e orkaudio
  • # rpm -e orkbasecxx
  • # tar xvf orkaudio-1.2-660-x1459-i386.centos5-installer.sh.tar
  • # ./orkaudio-1.2-660-x1459-i386.centos5-installer.sh
  • If any custom changes had been made to the old config.xml or logging.properties files such as IP filtering or NIC selection, apply those changes to the new files (do not simply overwrite the new files with the old ones, some configuration settings might have changed between the two versions)
  • # service orkaudio start

Upgrade with individual RPM files (Linux)

In this procedure, please replace version numbers with the relevant ones.

  • Take a copy of /etc/orkaudio/config.xml and /etc/orkaudio/logging.properties if you had customized them
  • # service orkaudio stop
  • # rpm -e orkaudio-addons
  • # rpm -e orkaudio
  • # rpm -e orkbasecxx
  • # rpm -i orkbasecxx-1.2-691.i386.centos5.rpm
  • # rpm -i orkaudio-1.2-691.i386.centos5.rpm
  • # rpm -i --nodeps orkaudio-addons-1.2-1526.i386.centos5.rpm
  • If any custom changes had been made to the old config.xml or logging.properties files such as IP filtering or NIC selection, apply those changes to the new files (do not simply overwrite the new files with the old ones, some configuration settings might have changed between the two versions)
  • # service orkaudio start

Upgrade with Windows installer

  • Take a backup copy of the orkaudio directory under Program Files
  • Stop the orkaudio service
  • Uninstall previous version OrkAudio
  • Run the latest orkaudio installer (e.g. orkaudio-1.2-657-x1463-win32-installer.exe)
  • If any custom changes had been made to the old config.xml or logging.properties files such as IP filtering or NIC selection, apply those changes to the new files (do not simply overwrite the new files with the old ones, some configuration settings might have changed between the two versions)

Upgrade with Windows binary archive

  • Stop the OrkAudio service
  • Unpack the orkaudio zip archive downloaded from your OrecX space (e.g orkaudio-1.2-688-x1537.zip)
  • Select and copy all files inside the top directory. This should include orkaudio.exe, some .dll files as well as subdirectories
  • Paste the files on top of your orkaudio install directory so that all .exe and .dll files are all replaced by the new ones in the archive
  • When done, all replaced files are usually seen as selected in the Windows file explorer This can give you a good indication of the success of the operation
  • Restart the OrkAudio service

Files Location

Audio Output Files

Audio output files are written to the c:\oreka\audio under Windows and in /var/log/orkaudio under Linux by default.

Audio files are classified according to the following default scheme (see also TapeFileNaming and TapePathNaming in the section called “File and Path Names in OrkAudio” ):

yyyy/MM/dd/hh

Audio file themselves are named after the following scheme:

yyyyMMdd_hhmmss_trackingID.extension

You can modify the audio files location by editing the <AudioOutputPath> configuration parameter described in the section called “Configuration” . Note that if this parameter is changed, OrkWeb needs to be told where to look for the recordings. This requires modifying Tomcat's $tomcat/conf/server.xml file to update the context path docBase parameter accordingly:

					
<Context path="/audio" docBase="c:/oreka/audio/" ></Context>
					
				

If this parameter does not exist already, just add it under the <Host> section. Don't forget to restart Tomcat after this change.

Configuration Files

OrkAudio configuration files are located in the install directory under Windows and in /etc/oreka under Linux. The files are:

Log Files

Log files are located in the install directory under Windows and in /var/log/oreka under Linux. By default, Oreka produces the following output:

  • orkaudio.log : this is the main OrkAudio logfile.

  • tapelist.log : this logfile contains the details (metadata) for each recording that was performed by OrkAudio.

  • messages.log : : this log file contains a subset of details (metadata) for each recording that was performed by OrkAudio. Useful for re-creating database entries.

Plugins Files

Plugins exist as dll files under Windows and as DSO (Dynamic Shared Objects) with .so extensions under Linux. They are located in {OrkAudioInstallDirectory}/audiocaptureplugins under Windows and in /usr/lib under Linux.

  • VoIp.dll - libvoip.so : VoIP recording plugin for SIP, Cisco Skinny and pure RTP protocols.

  • H323voip.dll : VoIP recording plugin for H.323, Avaya, Nortel UNISTIM and MGCP protocols.

  • SoundDevice.dll - libsounddevice.so : Sound Card based recording

  • Generator.dll - libgenerator.so : Audio generator for faking audio capture (useful when testing)

Audio Encodings and Formats

Wire audio encodings

Wire audio encodings are detected automatically by OrkAudio. Audio is not usually stored in its original wire format. Audio is recorded in real time to mcf files in order to maximize capturing performance and is later transcoded to the final storage format as specified in the section called “Storage audio formats” . The following encodings are supported:

  • G.711 ulaw
  • G.711 alaw
  • GSM 6.10
  • iLBC
  • G.729A
  • G.723.1
  • G.722

Storage audio formats

The storage format is the file format used to archive recordings to disk. Mcf capture files are transcoded from the wire encoding to the final storage format on a best effort basis. All possible storage encodings are currently wrapped into the wav container format. This means that all generated audio files have a .wav file extension and easily play on any existing Windows or Linux media player. The following formats are supported, please see the section called “Configuration” for more details.

  • GSM 6.10 wav : default format
  • G.711 ulaw wav
  • G.711 alaw wav
  • PCM wav : uncompressed audio, not recommended.

Configuration

Basic Configuration

Configuration of OrkAudio and its plugins is performed by modifying the config.xml file (see also the section called “Configuration Files” ). Core OrkAudio configuring parameters are the following:

  • <AudioOutputPath> : this parameter controls the root directory where capture and storage audio files are stored. It can be a relative or absolute path.

  • <CapturePlugin> : this parameter controls which audio capture plugin should be used. Valid values are VoIP.dll and libh323voip.dll in Windows, and libvoip.so and libh323voip.so under Linux.

  • <TrackerHostname> : the hostname or IP address of the server where OrkTrack (a component installed with OrkWeb) resides. If you use the OrkTrack hostname instead of the IP address (recommended), make sure that DNS is set up correctly and that you can ping that hostname from this OrkAudio server. Exemple:

    									
    <TrackerHostname>my-orktrack-server1</TrackerHostname>
    									
    								

    You can also enter several orktrack engines, e.g. for redundancy. They must be comma separated. When using non-standard TCP ports for OrkWeb/OrkTrack (standard is port 8080), it is possible to specify them in the hostname:port format. For example, if one tracker is on port 8080 and the second tracker is on port 80:

    									
    <TrackerHostname>my-orktrack-server1:8080, my-orktrack-server2:80</TrackerHostname>
    									
    								

  • <StorageAudioFormat> : this parameter controls the final file format of the tapes. Valid values are the following: gsm, ulaw, alaw and pcmwav. "gsm" is the default value and is the best compression rate available. All values generate wav files with various degrees of compression.

  • <TapeProcessors> : usually set to BatchProcessing, Reporting. Reporting ensures that the metadata about recordings is "reported" to the database through OrkTrack.

  • <DeleteNativeFile> : this parameter allows you to keep the uncompressed .mcf file even after the transcoding to the .wav is complete. The default is "yes". Set it to "no" to keep the .mcf file.

  • <TapeDurationMinimumSec> : minimum duration in seconds for a call to be recorded.

  • <AllowAutomaticRecording> : if set to "yes" (default setting), calls will be recorded by default. "no" indicates that only explicitly requested recording will occur (e.g. from Live Monitoring in OrkWeb).

  • <LookBackRecording> : if set to "yes" (default), will always record the call from the beginning regardless of when the request to start the recording was initiated, while a "no" setting will record only from the time the request was made.

File and Path Names in OrkAudio

It is possible to configure the path to which audio files are written as well as the audio file names through dynamic parameters

First, the TapeFileNaming tape processor needs to be added to the list of processors in the top node of the orkaudio config.xml file:

					
<TapeProcessors>BatchProcessing, TapeFileNaming, Reporting</TapeProcessors>
					
				

Secondly, the <TapeFileNaming> and/or <TapePathNaming> must also be added in the top node of the orkaudio config.xml file. They both contain a CSV list of elements. If an element appears between square brackets, it will be replaced by the value corresponding to the keyword. If an element appears without square brackets, it will be used verbatim in the file name. Example:

						
<TapeFileNaming>myrecordings-,[nativecallid]</TapeFileNaming>
						
					

with a native call ID of FDBCE@69.13.45.6 will result in the following file name: myrecordings-FDBCE@69.13.45.6.wav .

If the TapeFileNaming parameter is missing, the default naming scheme applies which is a timestamp plus the internal trackingID.

If the TapePathNaming parameter is missing, recordings are distributed to the default year/month/day/hour folder tree structure described in the section called “Files Location” .

Note: TapePathNaming configuration is always relative to AudioOutputPath.

Here is a list of acceptable keywords for tape and path naming:

  • [nativecallid]: this is the call ID extracted from the underlying protocol (SIP, Cisco Skinny, ...)
  • [trackingid]: this is the internal Oreka tracking ID
  • [direction]: in, out or unkn
  • [shortdirection]: I, O or U
  • [remoteparty]
  • [localentrypoint]
  • [localparty]
  • [localip]
  • [remoteip]
  • [hostname]
  • [year]
  • [day]
  • [month]
  • [hour] in 24 hours format
  • [min]
  • [sec]

You can also use any tag or additional custom extracted field in file names by using its tag/field name as a key. e.g for a SIP field called X-Unique-ID, add [X-Unique-ID] to TapeFileNaming or TapePathNaming. See also the section called “Extracting arbitrary fields from SIP headers”

Additional example:

					
<TapeFileNaming>myrecording,[hour],[min],[sec],_,[shortdirection],_,[remoteparty],_,[localparty],_,[hostname]</TapeFileNaming>
<TapePathNaming>mypathprefix/,[year],[month],/,[day]</TapePathNaming>
					
				

Configuring the VoIP plugin

VoIP plugin specific configuration is found in the config.xml file under the VoIpPlugin tag. Many options are available for this plugin, such as limiting traffic, blocking traffic from/to a specific IP address, ... The default config.xml has some of the main options listed in it and commented out. If any of these parameters are not documented here, please contact for more details.

Selecting Network Device(s) to intercept traffic from

It is possible to configure the network device to monitor for VoIP traffic using the <Devices> directive. While OrkAudio attempts to automatically select the server interface on which it detects VoIP traffic, you may need to configure the interface manually if orkaudio.log shows no sign of traffic. E.g.

In Windows:

						
<Devices>\Device\NPF_{E0E496FA-DABF-47C1-97C2-DD914DFD3354}</Devices>
						
					

In Linux:

						
<Devices>eth2</Devices>
						
					

Several comma-separated interfaces may be configured in the examples above

IP addresses based filtering

Filtering based on IP addresses or CIDR style subnets is available via the PcapFilter parameter, e.g.

						
<PcapFilter>host 192.168.0.34 or net 192.168.1.0/24</PcapFilter>
						
					

In the example above, only packets coming from or going to either IP address 192.168.0.34 or any address within the 192.168.1.x range will be retained. Any other packet will be ignored. The syntax is the standard tcpdump syntax as describe here: http://wiki.wireshark.org/CaptureFilters

Extracting arbitrary fields from SIP headers

It is possible to configure the VoIP plugin to extract any given standard or custom added SIP field by adding the following configuration parameter and specifying the wanted fields as a csv list (field names simply need to appear exactly as they appear in the SIP headers as viewed e.g via wireshark):

						
<SipExtractFields>contact, max-forwards, X-UNIQUE-ID</SipExtractFields>
						
					

After the change, the extracted fields will start appearing in OrkWeb as tags in the detailed recording view (when clicking on a recording's timestamp) and will become searchable via the tag name/tag text search boxes. They will also appear as tags in the tape messages that can be found in orkaudio.log

Live Monitoring

For Live Monitoring from OrkWeb to work, the 59120 port must be accessible on the server where OrkAudio is running. In Linux check the iptables settings. in Windows, the firewall settings.

See also the section called “Live Monitoring (On-Demand Recording)” for configuring OrkWeb.

Running OrkAudio

Make sure the OrkAudio license file is properly applied. Refer to the section called “Applying OrkAudio License File” .

Starting the OrkAudio service

Under Windows, start the OrkAudio service in Service Management (start/run/services.msc).

Under Linux, start the OrkAudio service by typing service orkaudio start on the command line.

Verifying that OrkAudio started

You might need to double-check that the orkaudio service was started correctly.

In Linux, use the following command:

# ps -ef | grep orkaudio

A line showing that orkaudio is running must appear:

					root     32071     1  0 10:02 ?        00:00:00
					/usr/sbin/orkaudio
				

In Windows' Service Management tool (start/run/services.msc), ensure that the orkaudio service is started

OrkAudio Auto-Start

During installation using the official installers, OrkAudio will install itself as an automatic service, i.e. a service that restarts automatically if the server is rebooted. This is important in the case of power failure, maintenance or other unpredictable events that may cause the system to fail or be restarted. Ensure that the service is configured properly as follows:

  • In Windows' Service Management tool (start/run/services.msc), right click on the orkaudio service and ensure that the Startup type is set to Automatic
  • In Linux, the command "chkconfig -- list orkaudio" should yield a response such as below:

# orkaudio        0:off   1:off   2:on    3:on    4:on    5:on    6:off

If not, chkconfig orkaudio on will need to be executed.

Migrating OrkAudio to Another Server

To move OrkAudio to a different server with the same operating system follow the procedure below:

  • Stop the orkaudio service on the old server
  • Install OrkAudio (refer to the section called “Typical Installation (Single Server)” ) on the new server
  • Copy the OrkAudio configuration files and license file from the old server to the new server: config.xml , logging.properties and license.txt , in the OrkAudio installation folder
  • Copy all the audio files and folders to the new server
  • Start the OrkAudio service on the new server

Load balancing - orkbalancer

The Oreka load balancer (orkbalancer) is a software service that can take a high amount of VoIP traffic and share it across multiple core recorders (orkaudio). Traffic input can come from one or more network interfaces and be distributed to any number of recorders. Recorders are specified by their IP addresses and ports, meaning that:

  • It is possible to run recorders on the same host as the balancer or on separate servers.
  • It is possible to run multiple recorders on a given server, thereby reaping the benefits of using servers with lots of cores.

The load balancer ensures that the RTP media traffic is well balanced between the recording targets and uses a round robin algorithm. The two directions of a given RTP exchange are always sent to the same recorder so that bidirectional conversations can be recorded. Any non-RTP traffic is sent to all recorders, meaning that signalling traffic is automatically distributed to all recorders.

orkbalancer currently only runs on Linux CentOS targets.

The configuration file for orkbalancer is the following file: /etc/orkbalancer/config.xml

In order to control from what network interfaces the orkbalancer should listen from (port mirroring NICs):

					
<HostDevicesList>eth0, eth1</HostDevicesList>
					
				

In order to control between which orkaudio targets the traffic should be balanced:

					
<LoadBalancingTargets>127.0.0.1:20000,192.168.0.10:20000,192.168.0.11:20002</LoadBalancingTargets>
					
				

The LoadBalancingTargets ports should be spaced by two units, e.g. if one target is on port 20000, the next target should be at least on port 20002. This is because signalling and media traffic are sent to two consecutive ports.

Any participating orkaudio target should be configured correctly for load balancing by adding the following in the orkaudio config.xml under the VoIpPlugin node:

					
<OrekaEncapsulationMode>true</OrekaEncapsulationMode>
<OrekaEncapsulationPort>20000</OrekaEncapsulationPort>
					
				

Troubleshooting

OrkAudio does not record any VoIP traffic

If no recordings appear in the <AudioOutputPath> directory, Here is the checklist:

  • Windows users only: Make sure winpcap3.1 or above is properly installed (start/programs should contain a Winpcap entry)
  • Make sure that the VoIP plugin records from the right network interface(s) specified in the <Devices> xml tag of the config.xml file. A list of all network interfaces is shown in orkaudio.log at startup.
  • Make sure that RTP traffic is actually present on the specified network interface(s). A packet sniffer such as Ethereal can be useful for that.
  • Refer to the section called “Passive Recording (via port mirroring)”

Not possible to replay recorded files

Recoded wav files should all be replayable by a media player such as Windows Media Player. Here is the checklist

  • Make sure that a sound device is installed on your system.
  • Make sure the file is not being processed by OrkAudio. Try again later.
  • Make sure that if the RTP traffic is encoded as G.729A or G.723.1, you are properly licensed for those codecs. OrkAudio logs error messages at startup if there is a licensing problem.

Only one side of the conversation is recorded

Make sure that RTP traffic for both sides is actually seen on the considered network interface. A packet sniffer such as Ethereal can be used for that.

Metadata is not detected

Use wireshark to see if signalling packets (e.g. SIP or Skinny) can be seen on your chosen sniffing NIC. Simply capture some traffic for 1 minute and type "sip" or "skinny" as a wireshark display filter in order to see only the relevant packets. If resultset is empty, it might mean that the packet interception strategy is missing some traffic, see the section called “Passive Recording (via port mirroring)” .

Chapter 4. OrkWeb - OrkTrack

Table of Contents

Overview
Installation
On Linux
On Windows
Upgrade
Upgrade using installer
Upgrade using WAR files
Applying OrkWeb License File
Trial versus Production license
Files Location
OrkWeb/OrkTrack Configuration files
OrkWeb/OrkTrack Log files
Running OrkWeb - OrkTrack
On Linux
On Windows
Accessing OrkWeb
Recordings
Tags
System Tag Types
User-Defined Tag Types
Using Tags
Managing Users
Login Strings
Importing CSV List of Users
Local Party Mapping
Remote Party Mapping
User Auto-Provisioning (UAP)
User Authentication with Single Sign On (SSO)
Managing Groups
Security groups
Regular groups
Access Policies
Example 1: Call center with Agents and Supervisors
Example 2: Business hosted telephony provider
Programs
Overview
Triggers
Criteria
Actions
Selective Recording (Audio and/or Screen)
Media Manager (Copy, Move, Delete, Email recordings)
Speech Analytics
File and Path Names in OrkWeb
Programs Priority
Media Servers, Services and Media Access Modes
Services
Media Access Modes
Live Monitoring (On-Demand Recording)
Quality Monitoring (QM)
Creating Scorecards
Importing Scorecards
Scoring calls based on scorecards
Generating QM reports
Security
Securing access to your media files
Securing access to the application (OrkWeb) using SSL
Foreign Language Support
Languages Included
Changing your Browser's Language
Migrating OrkWeb to Another Server
Customizing
Customizing the layout, style and colors
Customizations and software upgrades
Changing the application name
Accessing OrkWeb without specifying a port number
Troubleshooting
Cannot login as admin/admin
No recordings are appearing in the Browse page
Cannot replay recordings
Cannot login as a user I have just created
I don't get the latest recordings
OrkWeb's performance has slowed down. What do I do?

Overview

OrkWeb and OrkTrack are two components of the Oreka package that are deployed and installed together and are often referred to simply as OrkWeb.

The actual OrkWeb component is the user interface that is accessible through any browser, while the OrkTrack component is mainly responsible for receiving metadata about recordings from OrkAudio and storing them in the database. See diagram below for a usage example.

Installation

On Linux

Here are the steps to install OrkWeb on CentOS or Red Hat Enterprise Linux (RHEL). For assistance with other Linux distributions, contact .

Requirements

  • You need to be logged in as "root"
  • You need an internet connection to download MySQL, Java and Tomcat.

As mentioned earlier, OrkWeb and OrkTrack require a database engine (preferably MySQL), Java and Tomcat. Java and Tomcat are downloaded and installed by the OrkWeb installer provided to you by OrecX. MySQL, on the other hand, needs to be downloaded and installed separately.

Installation

  • If the database server (MySQL) is not already installed, install it: e.g. yum install mysql-server
  • If the MySQL service is not already running, start it: e.g. service mysqld start
  • Make sure that MySQL will restart automatically after a system reboot: e.g. chkconfig mysqld on
  • Untar the OrkWeb installer provided to you by OrecX: e.g. tar -xvf orkweb-1.7-2586-x64-linux-installer.sh.tar
  • If the Apache Tomcat service is already installed and is running, stop the service: e.g. service tomcat stop
  • Run the installer: ./orkweb-1.7-2586-x64-linux-installer.sh

The OrkWeb installer will prompt you for the MySQL "root" user password. By default, MySQL is installed with no default password. If you had set one, enter it here.

The installer will then prompt you for the installation of Java and Tomcat. Accept the default directories. It will then install OrkWeb and OrkTrack under Tomcat, and configure the Tomcat service to be automatically started after a reboot. However, it will not run the Tomcat service at the end of the installation. You will need to start it yourself after you apply the license file, as described in a later section.

On Windows

Requirements

  • You need to be logged in as Administrator before proceeding.
  • Access to the internet is highly recommended for download of the Oreka software, and MySQL.

As mentioned earlier, OrkWeb and OrkTrack require a database engine (preferably MySQL), Java and Tomcat. Java and Tomcat are downloaded and installed by the OrkWeb installer provided to you by OrecX. MySQL, on the other hand, needs to be downloaded and installed separately.

Installation

  • Install MySQL: you can download the MySQL Windows Essentials for your platform at http://dev.mysql.com/downloads/mysql/5.6.html#win32 . Install it accepting all the defaults. Take note of the "root" password if you assign one. It will be needed when you install OrkWeb.
  • If Apache Tomcat service is already installed and is running, stop the service
  • Install OrkWeb: unzip the OrkWeb installer provided to you by OrecX, e.g. orkweb-1.7-2586-win32-installer.zip .
  • Run the embedded executable. This will first install Java, then Tomcat (accept all default options) and finally OrkWeb and OrkTrack.
  • Make sure to enter the correct MySQL "root" password when installing OrkWeb. You can always update it later in the database.hbm.xml file in the OrkWeb installation folder, C:\Program Files\OrkWeb by default.

The installer configures the Tomcat service to be automatically started after a reboot. However, it will not run the Tomcat service at the end of the installation. You will need to start it yourself after you apply the license file, as described in a later section.

Upgrade

Upgrade using installer

  • Back up all files under the configuration folder (typically /etc/orkweb on Linux, and C:\Program Files\OrkWeb in Windows).
  • Back up the database, e.g.: mysqldump -uroot -p<password> oreka > orekaDB.sql
  • Download the OrkWeb installer, e.g. in Linux: wget http://orecx.com/mycompany/orkweb-1.7-2586-x64-linux-installer.sh.tar
  • Stop the Tomcat service, e.g. in Linux: service tomcat stop
  • Untar or unzip OrkWeb the installer
  • Install OrkWeb, e.g. in Linux: ./orkweb-1.7-2586-x64-linux-installer.sh.tar --nomysql --notomcat --nojava . In Windows, simply ignore the installation of Java and Tomcat.
  • If any custom changes were made to the old database.hbm.xml, logging.properties or other configuration files, apply those changes to the new files. Ensure that the database credentials are updated correctly in database.hbm.xml. Do not simply overwrite the new files with the old ones, some configuration settings might have changed between the two versions.
  • Re-start the Tomcat, e.g. in Linux: service tomcat start

Upgrade using WAR files

To upgrade using .war files use the procedure below. The version of the .war file made available to you by OrecX may differ from the example below, but the procedure still applies.

  • Get the orkweb.war and orktrack.war files. Sometimes libraries may be required too. E.g. orkweb-1.50-4295.war , orkweb-1.50-4295.war and oreka-tomcat-java-deps-1.50.zip
  • Backup the database, e.g.: mysqldump -uroot -p<password> oreka > orekaDB.sql
  • Stop the Tomcat service, e.g. in Linux: service tomcat stop
  • If libraries need to be upgraded, move the existing $tomcat/shared/lib folder to a safe location, then unzip the libraries zip file provided to you by OrecX (e.g. oreka-tomcat-java-deps-1.50.zip ) into the $tomcat/ folder. This will re-create the $tomcat/shared/lib folder with the new library files.
  • Move the existing $tomcat/webapps/orkweb and $tomcat/webapps/orktrack folders to a safe place somewhere else than under $tomcat/webapps , you will need them in a later step.
  • Copy the orkweb war file to $tomcat/webapps/orkweb.war
  • Copy the orktrack war file to $tomcat/webapps/orktrack.war
  • If you are upgrading to 2.00 or later from 1.10 or 1.5x:

    • Tomcat needs to be allocated a minimum of 1GB RAM, i.e. the Xmx option in the $tomcat/bin/catalina.sh file for the CATALINA_OPTS variable must be at least 1GB.

    • Tomcat also requires more PermGen space. The following needs to be appended to CATALINA_OPTS in the $tomcat/bin/catalina.sh file: -XX:PermSize=256m -XX:MaxPermSize=512m

  • If you are upgrading to 1.50 or later from version 1.10 or older:

    • Tomcat 7 and Java 7 are required as of 1.50. If you have older versions, you will need to upgrade them. You can use the OrkWeb installers to selectively install only those two components.

    • If you did not use a 1.50 OrkWeb installer to install Tomcat, you will need to configure (only once) a new ORKWEB_HOME environment variable that points to the orkweb configuration folder. As of 1.50 there is no more need to edit the web.xml files every time you upgrade to re-configure the configuration and tomcat folders. The OrkWeb configuration folder is now stored in the ORKWEB_HOME environment variable, and the Tomcat folder path is now obtained automatically by the application.

      • In Linux, the best place to add the ORKWEB_HOME environement variable is in the $tomcat/bin/catalina.sh file right under the lines:

         
        export JAVA_HOME=/opt/java/jre1.7.0_80
        export CATALINA_HOME=/opt/tomcat7
        export CATALINA_OPTS="-Dbuild.compiler.emacs=true -Dfile.encoding=UTF-8 -Xms???m -Xmx???m"

        as follows:

        export ORKWEB_HOME=/etc/orkweb/

      • In Windows, go to Control Panel/System/Environment Variables as Administrator, and add a new variable ORKWEB_HOME with VALUE set to the installation folder, typically C:\Program Files\OrkWeb.

  • Restart the tomcat service. It should create new orkweb and orktrack folders under $tomcat/webapps/
  • Obsolete - only needed when upgrading to older versions of orkweb up to 1.10 :

    Edit the new web.xml files in the $tomcat/orkweb/WEB-INF and $tomcat/orktrack/WEB-INF folders and update the ConfigDirectory and TomcatHome parameters to point to the appropriate folders (in Windows, the defaults are C:\Program Files\OrkWeb and C:\Program Files\Apache Software Foundation\Tomcat 7.0 respectively; on Linux, /etc/orkweb/ and /opt/tomcat7/)

  • Restart the tomcat service

If you prefer a more automated way of running this procedure, you can download and use the upweb.sh script available at http://files.orecx.com/tools/upweb.sh (usage example: ./upweb.sh 1.50-4295). Please read the header of the file for instructions on the steps you need to execute manually before and after running the script. For the Windows platform, you need to have Cygwin installed to use this script.

Applying OrkWeb License File

To apply the OrkWeb license file, e.g. orkweb-30-days-trial-license-20131005.txt , copy and paste its content into the Input License box in OrkWeb, accessible from the login page the first time the software is accessed, or from the Account page at subsequent tries.

Trial versus Production license

Note that there are two types of license files: trial and production. The trial type is sent to you by OrecX as a first license and allows you to record everything on the wire. It is good to start with this type of license to uncover any configuration tweaks that may be necessary.

For example, you may be seeing only the RTP streams but not the control packets, thus no phone number or extensions can be associated to calls. With a trial license, you will be able to quickly detect such a situation and correct it since all calls would be recorded and would appear in the OrkWeb Browse page with the local and remote party typically showing as IP addresses.

With a production license, users must be configured in OrkWeb with their phone numbers or extensions (or other) as a login string, for Oreka to be able to associate the local party in the VoIP packets with the configured user and thus recording the call. If no users have been configured in OrkWeb, a production license will inhibit all recording. See also the section called “Login Strings”

Before migrating to a production license, make sure all extensions, phone numbers, SIP URIs, ... that need to be recorded, are configured as login strings for defined users in OrkWeb. The login string field must match what you see in the local party field in the Browse page.

Files Location

OrkWeb/OrkTrack Configuration files

OrkWeb and OrkTrack have a set of configuration files that allow them to know where and how to access the database, and what information to write to log files. The main configuration files are shared between OrkWeb and OrkTrack and can be found under /etc/orkweb in Linux, and typically under C:\Program Files\OrkWeb in Windows. These folders contain 5 main files:

  • database.hbm.xml : for application database access information.
  • logging.properties : for application logging configuration.
  • localpartyMap.csv : for mapping the local party seen by orkaudio to the one configured in orkweb (e.g. IP address to an extension).
  • remotepartyMap.csv : for mapping the local party seen by orkaudio to the one configured in orkweb.

The OrkWeb and OrkTrack web applications' web.xml files have two important parameters in them: ConfigDirectory and TomcatHome. The former one must point to the installation folder (e.g. /etc/orkweb).while the latter points to the container folder (e.g. /opt/tomcat7).

OrkWeb/OrkTrack Log files

Both the OrkWeb-OrkTrack applications, and the Tomcat web server have their own logging mechanisms. Below are the files of interest for both cases:

  • orkweb.log : this file contains messages logged by OrkWeb and OrkTrack. the level of logging is defined in the logging.properties file. It can be found in /var/log/orkweb under Linux and typically in C:\Program Files\OrkWeb in Windows.
  • catalina.out : this is the file where Apache Tomcat logs its own messages. It resides in the $tomcat/logs/ folder.

Running OrkWeb - OrkTrack

By default, OrkWeb and OrkTrack use port 8080. Thus, ensure that port 8080 is open on the server. In Linux, you need to look at iptables, while in Windows, you can check your Firewall settings from the Control Panel.

Before starting OrkWeb and OrkTrack, ensure that the database server, typically MySQL, is running. Once done, start the Apache Tomcat service which will launch OrkWeb and OrkTrack.

On Linux

You can use ps -ef | grep mysqld to verify if mysqld is running, and service mysqld start to start it if it is not.

Once the MySQL is running, start the Apache Tomcat web server, e.g. service tomcat start .

On Windows

Go to Start/Run... and type services.msc. This opens the Services Manager application. Ensure that the MySQL service is running. If not, start it.

Once the MySQL service is running, start the Apache Tomcat web server, by right-clicking on the Apache Tomcat service and selecting Start.

Accessing OrkWeb

Open any standard web Browser and type the following URL: http://localhost:8080/orkweb . If you are accessing from a location other than the server on which Oreka was installed, replace localhost with the hostname or IP address of the Oreka server.

This will bring up a login screen as the one shown below. Login as admin/admin.

If this is the first time you attempt to login after the installation, you will be presented with a license input screen. Copy the content of the license text file issued to you by Orecx and paste it into the text box.

Recordings

When you first login to OrkWeb, you are presented with the Browse page that allows you to view a list of the most recent recordings. These recordings may be of different type, such as audio, screen or messages (SMS). An extensive set of search filters are available on that page that allow you to zero-in on one or multiple recordings of interest. These filters include local party, remote party, start time, duration, time span, user or group to which the recording is associated, etc. Other tools available on that page are the ability to export, email or delete recordings, and they are subject to the access policies or privileges that the logged-in user is assigned. There is also access to tagging or bookmarking recordings, evaluating recordings according to a Quality Monitoring scorcard (if the QM feature is licensed) as well as viewing more details about the recording.

Tags

Oreka provides you with the ability to tag or bookmark recordings. This is a powerful tool that can be used for many purposes as explained below.

Applying a tag to a recording uses one of the configured "tag types". Tag types can be pre-defined by the system or user-defined. System tag types are usually created by the Oreka system by default at installation or automatically when certain events occur, while user-defined tag types are added manually by the users in the tag types page. Tag types are usually accessible to users based on their access policies, but it is possible to designate tag types as being public for access to all users in the system.

It is important to distinguish between a tag and a tag type: a tag type is a category of tag that might be used to apply to any recording, while the tag itself is the actual application of a given tag type to a specific recording.

Tags have the following attributes:

  • Tag type: the type or category of the tag to be applied, e.g. Monitored, Agent, Patient ID, ...
  • Tag text: a complementary description of the tag type application. For example, a tag of type "Credit Card" would have the credit card number entered as a tag text.
  • Offset (in seconds): offset in seconds from the beginning of the recording where this tag applies. This is very useful for analytics-related bookmarking, among others, to indicate when a specific word or phrase was uttered or the starting point of a particular area in the media file.
  • Duration (in seconds): duration in seconds of the tag starting from the offset. For example, it can be used to describe the length of a silence or a specific topic in the recording.

System Tag Types

System tag types may be pre-defined by the system at installation or applied automatically at the occurrence of specific events. Some of the most common automatic or system tag types are the following:

  • Monitored: automatically applied to a recording when a user listens to a call in the Live Monitoring page.
  • Recordings metadata: additional recording metadata such as nativecallid, on-demand, ucid, split, hunt group, ... some of which are only obtainable through an additional CTI connector.
  • Agent and Agent Group: applied to a recording when it is subject to Agent Tracking - typically used on systems with hotdesking.
  • Speech Analytics keywords: these keywords configured in Speech Analytics profiles are automatically applied when the Speech Analytics engine detects them in an audio recording.

User-Defined Tag Types

User-defined tag types are defined and applied manually by users or through the Oreka API. Here are some examples of common uses:

  • Applying a tag type such as Reviewed to indicate that the call was reviewed by a manager.
  • Applying a tag type such as Patient ID and adding the actual ID as a tag text.
  • Bookmarking a spot in the recording where the agent yelled at a customer. The spot in the recording may be specified with the offset.
  • Bookmarking a recording with the Credit Card tag type, and adding the credit card number as tag text, the time it was uttered at as tag offset and the time length it lasted as duration. This can be useful with PCI compliance where the credit card info acquisition is ommitted from the audio recording.

Using Tags

Tags may be applied in one of three ways:

  • In OrkWeb manually by the user from the Browse page by clicking on the tag icon.
  • In OrkWeb manually by the user from the recordings details page.
  • By API, using one of the addtag API variations.

Tags are listed in the recordings details page. They are also displayed on the OrkMPx media player, when hovering over them. Tags may be used as search criteria to list recordings, but they may also be used as criteria in Audio programs or Media Manager copy, move and delete programs giving great flexibility in terms of filtering capabilities.

Managing Users

OrkWeb users are managed in the Admin/users page. It is possible to create, edit, disable and delete users. You can also configure users to be recordable or not. Non-recordable users are typically users who have administrative privileges, and do not count against the licensed user limit.

Your license key limits the number of active users you can have at any point in time. To free a few licenses, you can delete users or simply disable them. Being disabled, they will still be visible but no new recordings will be associated to them and those disabled users won't be able to log into OrkWeb.

There is one pre-defined and non-editable user in OrkWeb: "admin". This user has all the possible privileges or access policies enabled, and is reserved for the main admininstrator.

Login Strings

Each user can have multiple login strings entered as a cvs list of text strings. Those login strings serve two purposes:

  • They act as unique identifiers for OrkWeb users.
  • They specify what phone numbers or extensions are to be recorded.

When a new call occurs, if the local party field, as would be seen in the OrkWeb Browse page, matches one of the user's login strings, the recording will be associated to that user. The login string matching is case sensitive .

For example, Tom's login strings might be " tom, 5312 ". Any call to extension 5312 will be associated to Tom, and Tom will be able to log into OrkWeb using either " tom " or "5312" as an identifier (assuming Tom has a password defined. OrkWeb login is denied for users with blank passwords).

Configuration of users and login strings is very important for correct behavior when using production licenses. Refer to the section called “Trial versus Production license”

Importing CSV List of Users

When you have a great number of users to define in OrkWeb, it could be a daunting task to create them all, one at a time, from the Admin/users page. In this case, you can use the Import Users feature available on that page. This feature allows you to import a comma-separate list of users directly into OrkWeb. Below are the fields that define the file format:

firstname, lastname, login string, password, recordable, force password change, email, group, external

Only the firstname and lastname fields are mandatory. The rest can be left blank if not required. Also, only one login string can be entered on one line. The "recordable" and "force password change" fields can be set to "false"/"true", "0"/"1" or "no"/"yes". The "force password change" field, if set, forces the corresponding user to change their password the next time they login. This is mainly useful when defining new users.

There are two other global settings that can be configured when importing users: "Keep old login strings" and "Recordable". "Keep old login strings" allows you to select whether a user in the csv list that already exists in OrkWeb should have their login string(s) replaced by the login string in the imported file, or whether the new login string is to be simply added to that user's existing login string(s).

If a login string already exists in the database with different firstname/lastname, no action is executed.

Local Party Mapping

Sometimes, the local party reported by the OrkAudio appears in OrkWeb in a format that does not meet your requirements, e.g. MAC address, IP address, ... In cases where this cannot be modified at a configuration level neither at the recorder level nor at the telephony platform level, Oreka provides you with a special tool to circumvent the issue: local party mapping.

To map the local party to an extension (or other) to meet your requirements, create or edit a localpartyMap.csv file in the OrkWeb installation folder, and add the entries following the example below:

          10.10.1.1, 1540
          10.10.1.2, 1541
          00:08:5d:13:19:a0, 3523
          SIP/SOFTHONE034, 3681
          ...

The first entry is what you want to replace, the second, is the target output.

Once this file is completed, restart Tomcat (or at least OrkTrack), for the new changes to take effect.

Remote Party Mapping

This is the same as the local party mapping above, but for the remote party. The file name is remotepartyMap.csv in this case.

User Auto-Provisioning (UAP)

Oreka may be configured to automatically provision users based on recordings, i.e. whenever a new recording is detected, its local party can be automatically provisioned in OrkWeb. This feature is mainly useful in active recording setups using SIPREC, whereby the decision of what users to record is pre-configured in the telephony platform, hence ensuring that auto-provisioning will only occur for required users.

To configure UAP, first the OrkAudio config.xml configuration file needs to be updated as follows (OrkAudio needs to be restarted for this change to take effect):

						
	<SipUAPlugin>
		<SipRecReportLocalNameAsTag>yes</SipRecReportLocalNameAsTag>
	</SipUAPlugin>
						
					

Then, the following setting must be enabled in the OrkWeb database:

						
	orkuserconfig.userAutoProvisioning = true
	orkuserconfig.uapNameSplitChars    = "_. "  or " "
						
					

The orkuserconfig.uapNameSplitChars field is usually required to contain a blank space.

The user first and last name will be obtained from the OrkAudio recorder typically in the format "firstname lastname", and will be parsed accordingly to provision the user.

Some important notes on how UAP works:

  • With UAP, the recording's local party (i.e. user's login string) is key. If the local party is not found as a configured login string in orkweb, it is provisioned and associated to a new recordable and external user with the corresponding first and last name. This is regardless of whether another user by the same first and last name already exists (the login string is unique in Oreka, but the not the user name.)
  • UAP is subject to user and login string license limits. Once reached, no new users are auto-provisioned.
  • UAP not only adds new users, it can also update existing ones. This is true only if the login string already exists and is associated to a user who is marked as external .

If you need assistance, please contact .

User Authentication with Single Sign On (SSO)

OrkWeb can be configured to act as a single sign on consumer, hence allowing user login based on authentication from an external platform. This may be complemented with user auto-provisioning (SSO UAP), which would automatically add/update the user to the OrkWeb database if SSO authentication succeeds.

When SSO is configured, users attempting to log into OrkWeb will be authenticated by the external platform instead of by OrkWeb. This occurs if the user already exists in the OrkWeb database as an "external" user and is not disabled, or if it is not in the database and SSO UAP is used (see section below). If the user exists as "external" but is disabled, login will be denied.

Two SSO sources (producers) may be configured for better reliability if needed. See ssoURL and ssoURLSecondary parameters below.

Here is a list of parameters to configure in the database to enable SSO functionality for Broadworks and LDAP:

Broadworks SSO configuration example

						
	orkuserconfig.singleSignOn = true
	orkuserconfig.ssoType = "Broadworks"
	orkuserconfig.ssoURL = "https://xsp.bwvoip.net/com.broadsoft.xsi-actions/v2.0/user/$userId/profile"
	orkuserconfig.ssoURLSecondary = "https://secondary.source.com/v2.0/user/$userId/profile"
						
						

LDAP SSO configuration example

						
	orkuserconfig.singleSignOn = true
	orkuserconfig.ssoType = "LDAP"
	orkuserconfig.ssoURL = "ldap://ldap.forumsys.com:389/"
	orkuserconfig.ssoAuth = "simple"
	orkuserconfig.ssoPrincipal = "cn=$cn,dc=example,dc=com"
						
						

  • The ssoType currently supports "Broadworks" and "LDAP". The field is not case sensitive.
  • The ssoURL is the URL that OrkWeb will use to request authentication from the SSO producer. The above examples are typical URL used for Broadworks and LDAP. $userId is a parameter that will host the login user name for Broadworks.
  • The ssoPrincipal field can accept one of a few LDAP parameters to host the user name: $cn, $uid, $UserPrincipalName and $sAMAccountName. Examples:
    						
    	orkuserconfig.ssoPrincipal = "cn=$cn,dc=example,dc=com"
    	orkuserconfig.ssoPrincipal = "uid=$uid,dc=example,dc=com"
    	orkuserconfig.ssoPrincipal = "sAMAccountName=$sAMAccountName,dc=example,dc=com"
    	orkuserconfig.ssoPrincipal = "UserPrincipalName=$UserPrincipalName,dc=example,dc=com"
    						
    						

Single Sign On User Auto-Provisioning (SSO UAP)

SSO may be complemented with user auto-provisioning functionality. In that case, if the user attempting to log into OrkWeb does not exist, it is auto-provisioned with basic access policies ("Users" security group), and is set to be "external". Otherwise, if it already exists as an "external" user, its attributes (mainly first name, last name and email) are updated if necessary.

						
	orkuserconfig.ssoUap = true
						
						

If you need assistance, please contact .

Managing Groups

Oreka has two types of groups:

  • Security groups: This represents a privilege level and might be called a role in other software systems.
  • Regular groups: This represents a logical group of users (e.g. sales, marketing)

The combination of these two types of groups enables fine-grained access to the different features and collected data.

Security groups

Every user in Oreka belongs to one single security group which determines the access privileges for that user. Newly created users are implicitely associated to the default "Users" security group. There are 4 pre-defined groups in OrkWeb. More security groups can be created but it is typically much easier to adapt the existing security groups for your needs than to create completely new ones. The pre-defined security groups have sensible access policies defaults that are fine for most needs. Also, the pre-defined security groups cannot (and should not) be deleted:

Pre-existing security groups are:

  • Users
  • Administrators
  • Group Administrators
  • Supervisors

Regular groups

Regular (non-security) groups can be useful e.g. for filtering or creating specific recording rules on a group of people. Users can belong to multiple regular groups. Groups can also be part of groups, thereby creating a group hierarchy of any depth.

Access Policies

When you view the details of a Security Group in the Admin/groups page, a "Managed Access Policies" button appears. Clicking on it displays the Access Policies definition page. You can create your own security groups and give them the access policies that you wish but it is easier to tweak an existing security group.

Users associated to a particular Security Group inherit that group's access policies.

Example 1: Call center with Agents and Supervisors

In this example, call center agents shall be able to see their own recordings, supervisorA shall be able to see recordings for groupA and groupB, supervisorB shall be able to see recordings for groupB only. Here are the steps to configure this:

  • Create one recordable user per recorded extension
  • Create one non-recordable user per supervisor
  • Create regular group A
  • Create regular group B
  • Add every agent user to either groupA or groupB (it is possible to add certain agents to both groups if wanted)
  • Add supervisorA to groupA and groupB
  • Add supervisorB to groupB only
  • Add both supervisors to the Supervisors security group

Example 2: Business hosted telephony provider

In this example, each end-customer is a company with several users and each company shall be mapped to a group. CompanyA shall be mapped to groupA, CompanyB shall be mapped to groupB. Within each company, one person shall be administering the system. Only this person might be abe to access the live monitoring system. It shall not be possible for any company user to see data for another company, or even know that it exists. Here are the steps to configure this:

  • Create one recordable user per recorded extension for both companies
  • Create one non-recordable user per supervisor, e.g. supervisorA1 and supervisorA2 and supervisorB1
  • Create one non-recordable user per company administrator, e.g. groupadminA and groupadminB
  • Create regular groupA for companyA
  • Create regular groupB for companyB
  • Add every recordable user to either groupA or groupB
  • Add supervisorA1, supervisorA2 and groupadminA to groupA
  • Add supervisorB1 and groupadminB to groupB
  • Add all supervisors to the Supervisors security group
  • Add groupadminA and groupadminB to the Group Administrators security group
  • Edit the access policies of the Supervisors and Users security group in order to remove the live monitoring privilege altogether. The Group Administrators can access live monitoring by default, so no need to change access policies there.

Programs

Overview

In order to restrict what is recorded by Oreka, it is possible to create so-called recording programs from the Programs page. Those programs let OrkWeb administrators specifiy recording schedules as well as filtering criteria. Any number of these programs may be created to achieve high complexity recording rules.

Very important note: when at least one audio or screen recording program is active, recordings become subject to Programs and are no longer retained by default.

A program is initiated by a trigger event, which causes a set of criteria to be evaluated. If the criteria are met, a corresponding action is taken. Hence, the Programs feature's usefulness is not limited to selective recording. The criteria-based functionalities allowed by programs are:

  • Selective audio recording
  • Selective audio and screen recording
  • Selective screen recording (scheduled)
  • Selective copying, moving, deleting or emailing of recordings (Media Manager)
  • Phrase spotting and auto-tagging based on Speech Analytics

The Copy, Move, Delete and Email recordings programs collectively define what we call the Media Manager feature.

Triggers

Triggers are events such as a pre-configured time or the completion of a recording. Scheduled (time-based) triggers may be one-time events or repeatable triggers that restart at a given frequency.

One-shot triggers are configured by setting the "Trigger first execution" field. Recurring triggers also set the "Trigger repeat period (in days)" field which establishes the frequency of the trigger.

Only Media Manager programs currently use those explicit triggers. Audio recording programs have implicit triggers based on the completion of the recording process.

Criteria

Criteria are conditions that are evaluated when the trigger event occurs. If met, they cause the program action to be executed. Examples of criteria are target user, target group, local party, remote party, ... The available criteria depend on the type of program in question. The "Handle as exclusion criteria" option ensures that the action is taken only if the criteria are NOT met.

The criteria list may vary between different programs. Local and remote party criteria where available, support regular expressions (as opposed to wildcards). For example, in order to retain all recordings made to or received from phone numbers starting by the digit 5,6 or 7, enter "[5-7].*" in the remote party field of your program.

Be careful with the Target group criteria: it applies to the recording's user's parent groups as well as all their subgroups.

Scheduled Media Manager programs include among other, the following criteria:

  • Retention period (in days): this specifies the upper boundary of (latest) recordings that may be copied, moved or deleted. Recordings newer than that boundary are kept intact.
  • Earliest timestamp: earliest timestamp is updated automatically by the software every time a new batch of recordings is processed. It sets the earliest recording that should be considered, and ensures that recordings previously evaluated don't get re-processed the next time the program is executed.

Actions

Actions are executed when the program is evaluated and the criteria are met. Actions may be one of the following:

  • Keep an audio recording.
  • Keep an audio/screen recording pair.
  • Star/stop a screen recording.
  • Copy recordings (Media Manager).
  • Move recordings (Media Manager).
  • Delete recordings (Media Manager).
  • Email recordings (Media Manager).
  • Send the recording and its metadata to a third-party tool (Speech Analytics).

Selective Recording (Audio and/or Screen)

Selective recording can be achieved with the Audio recording and Screen recording (scheduled) types of programs.

The basic Audio recording program will simply keep or discard a recording based on the defined criteria. The decision is made when the recording completes. Almost any recording metadata may be used as a program criteria including local party, remote party, call direction, duration, user associated to the recording, time of the recording, ... There is also a "recording percentage" criteria that ensures that only a certain random percentage of recordings is kept.

The Audio recording program may also be used to trigger screen recordings that are to be associated to the audio recordings with the "Trigger Screen Recording?" option. This option is only available when Screen Recording is licensed. In this scenario, when an audio recording starts, the program in question automatically triggers a screen recording. It also sends a message to the screen recorder to stop the recording when the audio recording completes, and associates it to the audio recording counterpart.

The other type of selective recording is Screen recording (scheduled) . This is for screen recordings only, and provides the ability to configure time-based trigger events for starting and stopping the screen recording (e.g. record only between 10AM and 2PM, or only on Thursdays, ...).

Media Manager (Copy, Move, Delete, Email recordings)

The Media Manager (MM) functionality provides a mechanism to apply certain actions to existing recordings. The Media Manager is essentially an extension and a replacement to the old and now obsolete File Manager and Auto-Delete functionalities. The File Manager and Auto-Delete were global in scope and did not permit the definition of criteria. The Media Manager on the other hand provides finer granularity functionality, with the addition of criteria-based execution.

These MM actions may be scheduled (time-based), or triggered when a recording completes. The latter is available for the copy and move programs, but not for the delete program (since it is equivalent to an Audio recording program that would not keep such a recording).

For copy and move programs, the actions are defined by the following parameters:

  • Target service: just like the Target service in the File Manager, this field must point to a File Server type service. It designates the target location where the file is to be copied or moved. Refer to the section called “Services” for more details.
  • Path name (string substitution): Edit the secondary "Pathname" field if the target file's path is to be different from the original file's. Note that this refers only to the Secondary pathname not the Primary pathname . The primary path refers to the "File absolute path" of the service in question, e.g. /var/log/orkaudio/audio , while the secondary path refers to the <TapePathNaming> path configured in the recorder's config.xml. The default being a date-based hierarchy e.g. 2009/11/12/09/20091110_154500_ABC.wav. You can heance use this field to customize your path name based on recording metadata. See the section called “File and Path Names in OrkWeb” for the list of string substitutions available for path naming in OrkWeb.
  • File name (string substitution): Edit the "Filename" field if you wish to customize the name of the target file. See the section called “File and Path Names in OrkWeb” for the list of string substitutions available for file naming in OrkWeb.

Delete programs have the following action parameters:

  • Delete files in file system: enable if actual media files need to be deleted.
  • Delete entries in database: enable if deleting the recordings' metadata in the database is required.

Below are but a few examples of the many Media Manager uses:

  • Configuring different delete retention periods for different groups.
  • Moving recordings to different location depending on underlying customer (group).
  • Backing up recordings for only a handful of groups.
  • Renaming media files differently based on different criteria.
  • Emailing media files immediately after they are written to the associated user.
  • ...

Speech Analytics

Using a third party Speech Analytics tool, Oreka provides the ability to process audio recordings and extract valuable information from them. One important application of this is phrase spotting. When the Speech Analytics tool is able to spot specific words or series of words in a speech, such detection may be reported back to OrkTrack which will in turn auto-tag the recording at the corresponding offset for the keyword or set of keywords of interest. This provides a powerful tool for quickly searching and reviewing calls with red-flag phrases such as "cancel my order" or "not happy" with the ability to take quick corrective action as a business.

Requirements and Configuration

  • A third party Speech Analytics engine (SAE) such as VoiceBase. Ensure that Oreka already has a driver for it. At the moment, only VoiceBase is supported, but drivers for other engines can be easily added by OrecX. Contact support@orecx.com if your third party Speech Analytics engine (SAE) is not currently supported.

  • In the SAE, create one or more groups of keywords to be analyzed. Consult your SAE documentation for how to get this done. For VoiceBase, here is the procedure http://voicebase.readthedocs.io/en/v2-beta/how-to-guides/hello-world.html.

  • Add a new Speech Analytics profile to the oreka database. For example:

    						
    Insert into orkspeechanalyticsprofile(id, baseURI, engineName, profileName, token) values(null, "https://apis.voicebase.com/v2-beta/", "voicebase", "voicebase_greetings", "${ACCESS_TOKEN}");
    								

    Where ${ACCESS_TOKEN} should be replaced by the actual access token from VoiceBase.

  • Add the profile's configuration into the oreka database. For example, for VoiceBase, configure as follows:

    						
    insert into orkspeechanalyticsconfigkvp(id, configKey, configVal, profile_id) values(null, "keywordsgroups", "greetings", 1);
    								

    Where "keywordsgroups" is a reserved value used with the VoiceBase engine. If the profile has more than one group use a CSV list in the configVal value ("greetings", "finance")

  • In OrkWeb, create and enable a new program of type Speech Analytics, configure its criteria, and select one of the pre-configured Speech Analytics profiles that you had created in step 3 above.

Functionality

When a recording is detected that meets the Speech Analytics program's criteria, it is sent along with its metadata to the SAE. Shortly aftewards, the SAE responds with its analysis results. The time it takes depends on the configured polling period (the default is 30 seconds and is configured in orkprogramconfig.pollingPeriodSec for the Speech Analytics programs) as well as the SAE processing speed. If any of the keywords in the profile are detected in the recordings, they are automatically added as system tags to the recording in question, at the offset detected in the audio file analyzed.

Searching in the Browse page for recording's tags with those special keywords can then be applied to quickly pull critical recordings for analysis.

File and Path Names in OrkWeb

It is possible to configure the media files path and filename as a combination of the following dynamic parameters. Note that the pathname refers only to the secondary part ( Secondary pathname ) of the pathname that typically defaults to year/month/day/hour/ .

  • [orkuid]: the unique tape UID
  • [segid]: the segment ID number
  • [direction]: the direction, i.e. IN, OUT, UNKNOWN
  • [shortdirection]: the short representation of the direction, i.e. I, O, U
  • [localparty]: the local party field, typically containing a phone number or extension
  • [remoteparty]: the remote party field, typically containing a phone number or extension
  • [hostname]: the hostname obtained from the service associated to the recording
  • [year]: the year in 4 digit format (e.g. 2009)
  • [yy]: the year in 2 digit format (e.g. 09)
  • [month]: the month, in 2 digit format (e.g. 02)
  • [mm]: the month, in 2 digit format (e.g. 02)
  • [day]: the day, in 2 digit format (e.g. 08)
  • [dd]: the day, in 2 digit format (e.g. 08)
  • [hour]: the hour, in 2 digit, 24 hour format (e.g. 18)
  • [min]; the minutes, in 2 digit, (e.g. 06)
  • [sec]: seconds, in 2 digit, (e.g. 06)
  • [group]: the parent group of the user associated to the recording. NOTE: this assumes the user has only one parent group, otherwise the results are unpredictable.
  • [grandparentgroup]: the grand parent group of the user associated to the recording. NOTE: this assumes the user has only one parent group, and one grandparent group, otherwise the results are unpredictable.
  • [email]: email address of the user associated to the recording.
  • [firstname]: first name of the user associated to the recording.
  • [lastname]: last name of the user associated to the recording.
  • [<tagname>]: a tag type associated to the recording (e.g. [nativecallid])
  • [ucid]: UCID associated to the recording, if CTI is used and yields this metadata.
  • [trunkgroup]: trunk group associated to the recording, if CTI is used and yields this metadata.
  • [trunkmember]: trunk member associated to the recording, if CTI is used and yields this metadata.
  • [nativecallid]: native call id associated to the recording, if CTI is used and yields this metadata.

Programs Priority

Since multiple programs may be defined, a legitimate question that often comes up is: what happens when a given recording meets the criteria of two or more programs? Which program(s) gets priority and which one(s) decides on the fate of the recording?

The answer is that it depends on the priority configuration. By default all deployments give priority to "negative" programs, i.e. to programs that would cause the rejection of a recording. Hence, even if many programs report that a recording should be kept, all it takes is for one program to reject the recording for it to be discarded.

This behavior may be reversed in the database configuration to ensure that one "positive" program guarantees that the recording gets kept.

All recording programs get evaluated for every new recording. When multiple programs agree that a recording should be kept, they all get associated to that recording.

Media Servers, Services and Media Access Modes

Media servers refer to the servers where media files are stored. These servers can be the recorder servers or simple file storage servers. Media files are initially created and stored by the recorder on the recording server itself. They may however be moved later on to another location by a Media Manager program. A common such example is when multiple recorders are used and all media files are moved to one central file storage server.

For more details on how to configure the orkaudio servers in a multi-server setup refer to the section described in the section called “Multiple Server Configuration (OrkAudio)”.

Media files are accessed in one of two ways:

  • By a URL i.e. through http(s). This is typically used for playing back and exporting recordings.
  • Through direct access on the local file system or by using ssh/sftp for remote servers. This is used for copying, moving or deleting files (e.g. Media Manager).

Services play a key role in allowing the application access to the media files by the means above. The section below gives a full picture of their role and scope.

Services

Media Servers are represented in OrkWeb by logical entities called services. Sevices may represent other types of servers such as SMTP servers for emails.

In the context of media servers, services are used to link the recordings' metadata in the database to the corresponding media files: every recording's metadata has a reference to a specific service. When a recording is moved to another location described by another service, its service reference is modified accordingly to keep that association. Services also define the parameters needed to access the media files by URL, directly on the local disk, or by ssh/sftp for remote servers.

There are 4 types of services that can be defined:

  • Audio
  • Screen
  • File Server
  • SMTP Server

The first three all refer to media servers. The Audio and Screen types describe typical recorder servers, while the File Server refers to servers dedicated to media file storage only. Those three types inherit the same configurable attributes as shown below, while the SMTP server has a completely different set of parameters.

Services for recorders are created automatically by Oreka when the recorders are started. The recorders sign into OrkTrack and register themselves. These services may be later edited by the administrator, e.g. for configuring ssh/sftp access information and file absolute path.

File server type services are typically used with the Media Manager move and copy programs to designate a target location where to move or copy files. These services need to be created manually by the administrator.

Services Attributes

It is very important to verify that all services are properly configured to ensure correct functionality of many features in OrkWeb such as playback, exporting, emailing, copying, moving and deleting media files.

All services have the following common parameters:

  • Service ID: unique ID describing the service. It is defined internally by Oreka.
  • Service name: arbitrary name of the service. Audio and screen recorders automatically assign this field.
  • Service type: audio recorder, screen recorder, file server or SMTP server.
  • Description: text field for optional description of service.

Media Servers specific attributes

Parameters for access by URL (for playback and export):

  • File server protocol: protocol used to access files on the underlying server, typically "http".
  • Host name: host name or IP address of the server.
  • Application port: assigned by the recorders, typically 59140 for audio recorder, 59170 for screen recorder. This field is not required for file storage services.
  • File serve port: port to access files on the server. Typically 8080.
  • Context path: this field should match a corresponding entry in Tomcat's server.xml file on the server described by this service and is used to construct the URLs for accessing the media files. The defaults are "/audio" for the audio recorder and "/screen" for the screen recorder.
  • File serve path: this field is appended to the context path parameter to provide more flexibility in URL construction.
  • Streaming TCP port: indicates the port on which streaming will occur. Used mainly by OrkAudio for the Live Monitoring feature.

Parameters for direct access (for deleting, copying and moving files):

  • File absolute path: points to the exact directory or folder in the file system where the files reside. Examples are C:\Oreka\Audio in Windows and /var/log/orkaudio/audio in Linux.
  • Local: indicates whether the service resides on the same server as OrkWeb (local), or on a remote server. For remote servers, the SSH parameters that follow are required for accessing files associated to this service.
  • SSH user name: the user name to access the server using ssh/sftp.
  • SSH password: the password of the user name for accessing the server using ssh/sftp.
  • SSH port: the ssh/sftp port for accessing the server, typically 22.

Important things to verify:

  • Hostname: ensure that the service is accessible from the OrkWeb server by the configured hostname. Often enough, the hostname is local and does not appear in the DNS causing the media files belonging to such a service to be inaccessible.
  • File Absolute Path: it is essential to have this parameter configured for copy, move and delete to work properly. This parameter is empty by default.
  • Ssh parameters: remote servers need to have their ssh parameters manually configured for copy, move and delete to work properly.

SMTP service attributes

The email feature requires a service that describes an SMTP server and a user account. It will use that service to send recordings to users. Below are the parameters needed to configure an SMTP service in OrkWeb:

  • Host name: host name or IP address of the SMTP server.
  • Encryption Protocol: SSL or STARTTLS.
  • Port: the SMTP server port, e.g 485.
  • Use Authentication: usually yes, i.e. checked.
  • Sender Email: the email of the sender that should appear on the sent email. This could be the same as the user account below.
  • User name: the user name of the SMTP account that will be used to send emails.
  • Password: the password of the SMTP account that will be used to send emails.

Media Access Modes

The Media Access Mode, formerly knwon as "replay mode" or "playback replay mode", plays an important role in how internal URLs for accessing media files are constructed by the application. External URLs from the user interface or available as APIs hide those details (e.g. https://orkwebserver:8443/replay?segid=23). For the vast majority of cases, the Centralized Standard mode is used. This is also the default mode at installation. There are a few particular cases where Centralized Simple mode might come in handy as described below.

Note: always use a Centralized Mode. Centralized modes provide security, audio file decryption and transcoding into browser-supported codecs, ability to use OrkMPx (the HTML5-based player),...

The non-centralized Simple and Standard modes are not secure and are limited in capabilities. They should be used only for debugging purposes.

Below is a brief explanation of each available mode:

Centralized Standard Mode

Recommended mode. This is the default mode at installation. It ensures that internal URLs to the media files are constructed using the media server's service parameters such as protocol, hostname, port and context path.

Centralized Simple Mode

This is a special mode that is rarely used. One case where it proves to be useful is when a media storage is simultaneously mounted on the recorders and on the OrkWeb server. The recorders record to the mounted drive and OrkWeb accesses the files off that mounted disk as if they were local. In this case, the internal URL is not constructed based on the recording's service parameters such as in the Centralized Standard Mode, rather from the URL used to access OrkWeb itself. This mode is available as of OrkWeb version 2.10-5644.

Standard Mode

Obsolete, used for debugging only. This mode exposes to the user interface the internal URLs constructed based on the recording's service parameters: protocol, hostname, port and context path. It allows direct access to the media servers from the client side, bypassing any security features, transcoding, decryption, ...

Simple Mode

Obsolete, used for debugging only. This mode exposes to the user interface the internal URLs constructed based on the URL used to access OrkWeb itself. It hence allows direct access to media files on the OrkWeb server from the client side, bypassing any security features, transcoding, decryption, ...

Live Monitoring (On-Demand Recording)

OrkWeb offers a Live Monitoring feature that allows you to see what calls are occurring at any given time. You can listen to these calls live and opt to record them or not (keep and discard options in the Live Monitoring page.)

In order to configure OrkWeb for Live Monitoring, it is necessary to create users for all phone extensions you want to monitor and at least one group. All wanted users must then be added to the group(s). Please refer to the section called “Managing Users” . Once done, the live monitoring page will list all groups for selection.

See also the section called “Live Monitoring” for configuring OrkAudio

Note that by default, OrkAudio records all calls that appear in Live Monitoring, unless programs are defined and exclude such recordings. If you wish to operate in a purely on-demand recording fashion based on the Live keep/discard options, contact for how to set up OrkAudio to default to a non-recording mode.

Quality Monitoring (QM)

The Quality Monitoring feature in Oreka allows managers or supervisors with proper privileges to evaluate calls by “scoring” or “marking” them based on a set of predefined criteria called Scorecards . The QM feature requires a separate license. A typical usage of QM scorecards is in call centers, where agent calls are often reviewed by their supervisors to ensure quality customer support and guide the agent to improve on weaker areas.

The guidelines or criteria are defined within scorecards. A scorecard may be associated to only one group in OrkWeb. Groups may represent company departments or any other logical entity. They typically include one or several users.

The typical steps involved in setting up and using QM are the following:

  • Creating scorecards
  • Importing them into OrkWeb
  • Scoring calls based on those scorecards and saving the results
  • Issuing statitistics reports on scorecard results

We will explore each of those aspects in the sub-sections below.

Creating Scorecards

The first step in setting up QM is to create one or more scorecards. Scorecards establish the criteria that will be used to evaluate a recording. Scorecards may include one or more sections which in turn may host one or more questions. Each question may allow several answers with a different score associated to each. Sections and question scores may also be weighted differently.

Other scorecard features are:

  • Auto-fail: some answers may be designed to automatically fail the scorecard results. This allows flexibility in giving great weight to some very important criteria.
  • Exclusion: some answers may be designed to have no effect on the final score. For example, a not applicable (N/A) answer typically indicates that the corresponding question is moot, and should be omitted from the scorecard results calculation.
  • Comments: there are multiple level of comments that can be added to a scorecard including the scorecard itself, its sections as well as the answers.

Creating a scorecard requires filling a CSV scorecard template file. Please refer to the section called “How do I configure a scorecard for QM?” for more details on the format of the scorecard CSV file.

If a scorecard needs to apply to more than one group, one of two approaches may be used:

  • Create two separate identical scorecards, one for each group, with a slightly different name, and associate them separately to each group,
  • Create a parent group and make both groups in question its member or children groups, then associate the scorecard to the parent group. The two subgroups will automatically inherit access to that scorecard from their common parent group.

Importing Scorecards

Once a scorecard is created and configured to be associated to a group, it may be imported in OrkWeb in the Admin/scorecards page. Errors in the scorecard are detected and reported by the import function, and will cause the entire scorecard to be rejected.

Scoring calls based on scorecards

To "score" a recording, click on the scorecard icon in the OrkWeb "Browse" page or go to the recording details page and select the "Scorecards" tab. OrkWeb looks for the group(s) associated to recording's user, and makes any scorecard template associated to that user's parent groups available for the evaluation. Once the call is “scored”, the scorecard results may be saved for later review as well as for generating QM statistical reports.

Generating QM reports

Reporting on QM is possible through several reports with the ability to define a slew of filters for greater flexibility. In fact, all search filters that are available in the Browse are applicable to the QM statistics reports below. Reports may be generated in 3 formats: PDF, HTML and CSV unless explicitely specified otherwise. Here is a summary of the types of reports available:

  • Scorecard results report (PDF only)
  • Group report: a summary report displaying the number of scored calls, minimum/average/maximum score for each group.
  • Group Detailed report: a report detailing the number of scored calls, minimum/average/maximum score for each question in each scorecard grouped by groups.
  • User report: a summary report displaying the number of scored calls, minimum/average/maximum score for each user.
  • User Detailed report: a report detailing the minimum/average/maximum score for each question in each scorecard grouped by users.
  • Scorer report: a report listing the score and summary info of every recording grouped by scorers.

Security

Oreka addresses security issues at many different levels. Below is a summary:

  • Secure access to the recordings, i.e. access by simple URL can be prohibited in general and allowed only for valid users who are logged into OrkWeb. See below for details.

  • Encryption: : OrkAudio may be configured to encrypt files, and OrkWeb configured to decrypted them for playback. Files would thus be played back only through OrkWeb.

  • Secure access to the application using SSL (https access).

  • Authentication Rules for user login access such as locking a user after a given number of unsuccessful login attempts, and password rules for ensuring a minimum level of difficulty in passwords.

For more information, please contact .

Securing access to your media files

Securing access to media files in Oreka ensures that only users legitimately logged in to OrkWeb are allowed accessing the files. To configure this protection level, two configuration actions are required:

  • Set "Secure access to media files" option to "yes" in OrkWeb's Config/settings page. This will automatically set the Playback mode to "Centralized".

  • For each server that is storing recordings, configure the web server (e.g. tomcat or httpd) to allow access to the files only from the server where orkweb is installed. Direct URL access to the files from user client PCs will no longer be allowed.
    • For single-server deployments, modify tomcat's server.xml file as follows:
      										
      <Context path="/audio" docBase="/var/log/orkaudio/audio" >
      
          <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127.0.0.1" deny=""/>
      
      </Context>
      <Context path="/screen" docBase="/var/log/orkaudio/screen" >
      
          <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127.0.0.1" deny=""/>
      
      </Context>
      										
      									
    • For multi-server deployments, modify every recorder's tomcat's server.xml as above, but change the "allow" field content to include the hostname or ip address of the server where orkweb is running.

Securing access to the application (OrkWeb) using SSL

Secure access to OrkWeb uses SSL, and requires that the URL to the application rely on https instead of http. To configure this functionality, simply edit the web.xml file stored under $tomcat/webapps/orkweb/WEB-INF , and modify the line:

					
<transport-guarantee>NONE</transport-guarantee>
					
				

to

					
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
					
				

After this change, access to OrkWeb becomes https://localhost:8443/orkweb . If you continue using http://localhost:8080/orkweb , you will be automatically re-directed to the new https URL.

Note: the change above assumes that Tomcat was installed by the OrecX OrkWeb installer. The installer performs some customizations to the Tomcat server.xml file to make the functionality above accessible. Contact if your server.xml file does not contain these customizations.

Foreign Language Support

Oreka's architecture was designed with foreign language support in mind. It is thus very modular and requires minimal effort - translation of a couple of files - to integrate a new language. The localization files are available in OrkWeb application's folders (e.g. orkweb.properties for English, orkweb_fr.properties for French).

Languages Included

The following foreign languages are currently included in OrkWeb:

  • English
  • French
  • Japanese
  • Portuguese
  • Spanish
  • Korean
  • Russian
  • Croatian
  • Romanian
  • German
  • Dutch
  • Swedish
  • Italian

For other languages, please contact .

Changing your Browser's Language

The selection of the OrkWeb language usually occurs automatically by default, and depends on your Operating System language. For example, if you are running the Spanish version of Windows, OrkWeb will appear in Spanish by default.

If you would like to change the displayed language, you would have to use the Language Options in your Browser as described below:

In Internet Explorer:

  • Go to Tools/Internet Options
  • Select Language/Add...
  • Choose the language you want, and put it on top of the list
  • Reload the OrkWeb page

In FireFox:

  • Go to Tools/Options/Content
  • Select Languages/Choose...
  • Choose the language and move it to the top of the list
  • Reload the OrkWeb page

Migrating OrkWeb to Another Server

To move OrkWeb functionality to a different server with the same operating system follow the procedure below.

Very important: make sure you are operating out of production hours.

On the old server:

  • Stop the Tomcat service
  • Backup the database, e.g.: mysqldump -u root -p oreka > orekaDB.sql . Note that the default database name is "test" with older OrkWeb Windows versions and "oreka" for all OrkWeb Linux versions as well as newer OrkWeb Windows versions
  • Save the OrkWeb and Tomcat configuration files, as well as the license file: database.hbm.xml , logging.properties , localpartyMap.csv and orkl.txt , and any other file in the OrkWeb installation folder, as well as server.xml , in the tomcat configuration folder ( $tomcat/conf/ .)

On the new server:

  • Install and start the MySQL service.
  • Create the MySQL database on the new server (e.g. "create database oreka;"). It is very important that the database name created here and imported in a later step below is the same as the one configured in the database.hbm.xml file from the old server. If the old database is called "test", this would be a good opportunity to rename it to "oreka" in the database.hbm.xml file and in this step.
  • Install OrkWeb (refer to the section called “Installation” ).
  • Restore the OrkWeb and Tomcat configuration files saved from the old server. Double-check that the database name in the database.hbm.xml file matches the one created above.
  • Make sure MySQL and Tomcat are both services that restart automatically after reboot.
  • Restore the database from the old server, e.g.: mysql -u root -p oreka < orekaDB.sql . Again, the name of the database specified MUST match the one in the database.hbm.xml file.
  • Start the Tomcat service.
  • Important: Make sure that at this point that you can browse the older recordings before applying new traffic to the server . If not the case, verify that your database name is correct and that the new database actually contains the same records as the old database.

If you are uncertain about any aspect of the migration process, contact .

Customizing

Customizing the layout, style and colors

If you wish to brand your application by simply changing the logos that appear in orkweb, all you need to do is modify the 3 files under $tomcat/webapps/orkweb/images: application-logo.png , company-logo.png and company-logo.jpg . Make sure to keep copies of those files in case you upgrade orkweb in the future.

Otherwise, customizations of layout, style and color are a simple matter of tweaking html/css/icon files by a web designer. css files are found in $tomcat/webapps/orkweb/css. icon files are found in $tomcat/webapps/orkweb/images and can be modified with a tools such as Phostoshop. It is also possible to modify application html files in $tomcat/webapps/orkweb/WEB-INF e.g. for inserting proprietary content or tweaking the layout. If you do this, you will need to ensure that such changes are re-applied to any future upgrade of orkweb (refer to the next section).

Customizations and software upgrades

Any modification to OrkWeb will need to be re-applied every time a software upgrade is performed. Tools such as diff and patch might help for automating the application of small changes to html and css files, and this, even if the upgraded html and css files have been altered by OrecX since the software version you had customized.

Changing the application name

For example, to access the application as http://server:8080/myrecorder instead, here is the procedure:

  • Change folder name under $Tomcat/webapps from orkweb to myrecorder
  • Change references to orkweb in $Tomcat/webapps/myrecorder/WEB-INF/web.xml as follows (they appear in two places in web.xml, change both):
    								
                        <display-name>myrecorder</display-name>
                        <servlet-name>myrecorder</servlet-name>
    								
    							
  • Rename the orkweb.application and orkweb*.properties files in $Tomcat/webapps/myrecorder/WEB-INF to myrecorder.application and myrecorder*.properties respectively
  • Edit the relevant orkweb*.properties files depending on the languages you want to support and search and replace all references to OrkWeb with your own application name.
  • Restart tomcat

Accessing OrkWeb without specifying a port number

To access the OrkWeb application without specifying a port number in the URL, such as http://servername/orkweb instead of the typical http://servername:8080/orkweb , you will need to either replace the Connector entry in Tomcat's server.xml configuration file for port 8080 with port 80, or simply copy and paste that connector to a new one for port 80, the default Tomcat port. If there are any other references in that file to port 8080, they also need to be modified (or duplicated) to use port 80 instead.

Troubleshooting

Cannot login as admin/admin

Most likely, the database server is down or there is something wrong in the database URL and credentials in the database.hbm.xml configuration file.

No recordings are appearing in the Browse page

  • Make sure the end date in the multi-criteria search form is set correctly.
  • Make sure that the recorder (orkaudio) is running correctly and is creating new recordings.
  • If you are using a production license, make sure that users are properly defined in the Admin/users page. Refer to the section called “Applying OrkWeb License File” .
  • If you have defined any programs in the Admin/programs page, verify that those programs are configured properly to allow the recordings that you are expecting to see.

Cannot replay recordings

If you fail to replay recordings through OrkWeb, here is the checklist:

  • Test that the sound device is working properly by trying to play a sound or music file using any available application.
  • If you are using Microsoft Internet Explorer, make sure your copy of Windows Media Player works well by opening it from the start menu and trying to replay a sample audio file.
  • If you are using Mozilla Firefox, make sure you have installed Java. You can test this using the following link: http://www.java.com/en/download/help/testvm.xml
  • Verify that the file you are attempting to replay is actually present in the OrkAudio storage folder as configured in the recorder's config.xml file.
    								
    <AudioOutputPath>c:/oreka/audio/</AudioOutputPath>
    								
    							
  • Make sure that a correct context path is configured in Tomcat's server.xml for the storage location of the media files. Make this context path matches the OrkAudio AudioOutputPath. Following the example above, ensure that Tomcat's $tomcat/conf/server.xml contains an entry such as:
    								
    <Context path="/audio" docBase="c:/oreka/audio/" ></Context>
    								
    							
    If this parameter does not exist already, just add it under the <Host> section. Make sure Tomcat is restarted after such a change.
  • If the file is present, try to replay it locally with a media player such as Windows Media Player. If it does not replay, please refer to the section called “Not possible to replay recorded files”
  • Make sure URLs are valid: retrieve the full URL to an audio file by doing a "view source" on the browse page and search for ".wav". Copy the complete URL and paste is directly into a browser's address bar to check if the file can be downloaded manually.
  • If you are running Oreka on multiple servers, check the section called “Multiple Server Configuration (OrkAudio)”

Cannot login as a user I have just created

You need to add at least one login string for the user. Users can log into OrkWeb using any of the login strings they own. For more details, please refer to the section called “Login Strings”

I don't get the latest recordings

Make sure the end date in the multi-criteria search form is not in the past.

OrkWeb's performance has slowed down. What do I do?

Verify that the database indexes were created properly. For a list of indexes, download the script at create_indexes.sql . If the indexes are missing in your database, you will need to run that script. Usage syntax is explained in the header of the file.

Indexing on a large database may take serveral minutes. Hence, it is highly recommended it be done during off hours, when Tomcat is not running.

Chapter 5. Addendum

Auto-Delete (obsolete)

Obsolescence Notice

The Auto-Delete feature is now obsolete and relaced by the Media Manager functionality. Refer to the section called “Media Manager (Copy, Move, Delete, Email recordings)”. We highly discourage its continued used as it is no longer maintained. Please contact our support group at for assistance in migration towards the new Media Manager functionality.

Overview

The Auto-Delete feature may be used to automatically delete files and their metadata in the database after a certain period of time as defined by the "retention period" parameter. When activated, it runs as a background task, at the frequency set by the "wake-up period" parameter.

This feature is global in nature and applies to ALL media files in the system. This is true even for setups with multiple recorders installed on different servers. To delete recordings based on specific criteria (e.g. group, service, ...), refer to the section called “Media Manager (Copy, Move, Delete, Email recordings)” , available as of OrkWeb version 1.8.

The Auto-Delete feature runs as a background task. When it wakes up, it searches in the database for all recordings that are older than the retention period. It then deletes recording files (e.g. .wav for audio and .fbs for screen recordings), in batches of one day, starting from the oldest.

Configuration Example

Below are the instructions for how to configure Oreka to delete all media files in the system and their database info, if they are older than 180 days (approximately 6 months):

  • Set "Delete files in filesystem" to Enabled
  • Set "Delete entries in database" to Enabled
  • Set "Wake-up period" to the frequency at which this task is to run. Typically, 1 day (86400 secs) is sufficient.
  • Set "Date/time of first execution" as desired. This is mainly useful for postdating the start of execution of this feature.
  • Set "Retention period" to the number of days recordings are to be kept in the system before being deleted.

The "Stop Auto-Delete" button provides a quick mean for turning off this feature. It resets the "Delete files in filesystem" and "Delete entries in database" to Disabled, and "Wake-up period" to 0.

Deleting Remote Files

For deletion of remote files, an ssh server needs to be running on the remote server. Also, the corresponding service must be configured with the ssh parameters in OrkWeb, in the Config/services page. Refer to the section called “Services”

for more details on configuring services.

Notes

It is recommended to delete both files and database info with this feature. Deleting only database info leaves orphaned recordings that are neither easily accessible nor identifiable, while deleting files only and leaving the corresponding data in the database means that the Auto-Delete feature will unnecessarily re-attempt to remove already deleted files every time it wakes up.

File Manager (obsolete)

Obsolescence Notice

The File Manager feature is now obsolete and relaced by the Media Manager functionality. Refer to the section called “Media Manager (Copy, Move, Delete, Email recordings)”. We highly discourage its continued used as it is no longer maintained. Please contact our support group at for assistance in migration towards the new Media Manager functionality.

Overview

The File Manager feature allows copying, moving and renaming media files after they are created by the recorder. Copying media files is also referred to as "archiving".

The File Manager may be used in different scenarios. Here are some examples:

  • Multiple recorders are being used and all media files need to be centralized at one location;
  • All recordings are to be copied (archived) to another location for backup.

To activate the File Manager, select the archiving method and running mode as described below, and uncheck the Disable box, then "Submit" the changes.

This feature is global in nature and applies to ALL media files in the system. This is true even for setups with multiple recorders installed on different servers. To copy or move recordings based on specific criteria (e.g. group, user, ...), refer to the section called “Media Manager (Copy, Move, Delete, Email recordings)” , available as of OrkWeb version 1.8.

Running Modes

The File Manager can run in one of two modes: real-time or scheduled. For now, these two modes are mutually exclusive. The sections below give more details.

Real-Time (Immediate) Mode

In real-time or immediate mode, all media files that appear after the File Manager is activated will be archived or moved, almost immediately after the recording completes. What actually happens is that every time a new recording occurs, a corresponding entry is added to a queue to be processed by a background task. The processing of the queue performs the necessary task(s) such as archiving, moving and/or renaming the target file.

Since the processing occurs almost in real-time, the destination storage location needs to be accessible at all times.

To configure this mode, check the box next to "Immediately after recording completes".

Scheduled Mode

The scheduled mode provides a tool to archive or move files on a regular basis, at a pre-configured time of day and with a pre-defined criterion based on the age of the recording. Unlike in the real-time mode, the destination storage location in this case only needs to be accessible at the time when the File Manager is scheduled to wake-up.

To configure the scheduled mode, check the box next to "Every X day(s) ...". Make sure to fill in are fields on that line.

Configuration

  • Uncheck the "Disable" checkbox to activate the feature.
  • "Moving files" is used to move files, thus deleting them from their original location, while "Archiving" copies files to a new location, keeping the original file intact.
  • Check/uncheck the "Access files from original location" checkbox, depending on whether playback of the recordings in OrkWeb is to occur based on the original file location or its new copy - valid only for archiving option.
  • Select the running mode by checking the box next to "Immediately after recording completes" for the real-time mode, or "Every X day(s) ..." for the scheduled mode. The two modes are mutually exclusive. If you select the scheduled mode, you need to specify the time of day when the File Manager is to run, as well as a retention period criterion (0 means all files).
  • Select the target service where the archiving is to occur (see the section called “Services” for adding services). The target service MUST be different from any recording service in use. It is best to define a new service of type File Server and properly define its attributes especially its File Absolute Path and its ssh parameters.
  • Edit the secondary "Pathname" field if the target file's path is to be different from the original file's. Note that this refers only to the Secondary pathname not the Primary pathname . The primary path refers to the "File absolute path" of the service in question, e.g. /var/log/orkaudio/audio , while the secondary path refers to the <TapePathNaming> path configured in the recorder's config.xml. The default being a date-based hierarchy e.g. 2009/11/12/09/20091110_154500_ABC.wav. You can hence use this field to customize your path name based on recording metadata. See the section called “File and Path Names in OrkWeb” for the list of string substitutions available for path naming in OrkWeb.
  • Edit the "Filename" field if you wish to customize the name of the target file. See the section called “File and Path Names in OrkWeb” for the list of string substitutions available for file naming in OrkWeb.

Chapter 6. API

Table of Contents

REST API
Legacy API

REST API

As of version 2.10-5556, Oreka provides a new REST API. The documentation is available at http://files.orecx.com/api/oreka-restapi.pdf. Please contact OrecX at for access credentials.

Legacy API

An older HTTP-based API may also be used for some complementary functionalities and is accessible at http://files.orecx.com/api/oreka-api-document.html. Please contact OrecX at at for access credentials.

Chapter 7. FAQ

How do I manually install orkaudio?

This is not the recommended installation procedure.

Orkaudio comes in two different packagings under Linux : automatic installer (.sh file extension) and RPM archive (.tar file extension). The automatic installer is the recommended way of installing the software. It comes as a single file named e.g. orkaudio-1.2-6560-x1459-i386.centos5-installer.sh . To install it, refer to the section called “On Linux”

While the automatic installer works well on CentOS and RHEL, it may sometimes fail. If you run into errors with it, you can always proceed to a manual installation by extracting the .rpm files from it, and installing them manually. The procedure is described below.

To extract the .rpm files, run the installer. At the first question, exit by pressing CTRL-C. This will create a subdirectory under /tmp with all the required rpm files. You can then proceed as follows:

  • yum install boost-devel
  • yum install libpcap
  • rpm -i xercesc-2.7.0-1.i386.rpm
  • rpm -i ace-5.5.8-1.centos5.i386.rpm
  • rpm -i log4cxx-0.9.7-1.i386.rpm
  • rpm -i libsndfile-1.0.13-1.i386.rpm
  • rpm -i orkbasecxx-1.2-660.i386.centos5.rpm
  • rpm -i intel-ipp_rti-5.0p.x32.rpm
  • rpm -i orkaudio-1.2-660.i386.centos5.rpm
  • rpm -i --nodeps orkaudio-addons-1.2-1459.i386.centos5.rpm

Copy the orkaudio-startup-script to the /etc/init.d directory as orkaudio. This will allow you to start and stop orkaudio either using service orkaudio stop and service orkaudio start or /etc/init.d/orkaudio start and /etc/init.d/orkaudio stop

How do I backup oreka?

This section is intended as a guideline for backing up your Oreka server. It lists all the entities or components that are involved.

  • Media files: the recordings are your main data. They are stored under the <AudioOutputPath> folder as configured in the recorder's config.xml file.

  • Database: contains the metadata about the media files. For mysql, you can back up using

    mysqldump -root -p<password> <database_name> > orekadb.sql

    where database_name is the name of the database, usually "oreka" in Linux, and "test" in Windows.

  • Configuration files: both OrkAudio's and OrkWeb's. Refer to the section called “Configuration Files” and the section called “OrkWeb/OrkTrack Configuration files” for the files' locations.

  • Log files (if necessary): both OrkAudio's and OrkWeb's. Refer to the section called “Log Files” and the section called “OrkWeb/OrkTrack Log files”

  • Customizations (if necessary): if you have made any customizations, make sure to back them up. These may include Tomcat configuration changes, web interface-related tweaks, etc.

  • Oreka software: ensure that you have a copy of the Oreka software or access to the website where the Oreka software was made available to you.

How do I configure Microsoft SQL Server (MS-SQL)?

MS-SQL Driver

Make sure that the Microsoft SQL server driver file (sqljdbc4.jar) is present in the $tomcat/shared/lib folder. If not, download it from Microsoft's web site and store it there.

MS-SQL configuration

  • Download the sample MS-SQL configuration file available at database-mssql-example.hbm.xml .

  • Modify the url, username and password as needed.

  • Move the file to the OrkWeb installation folder (typically C:\Program Files\OrkWeb ) as database.hbm.xml , replacing the existing file.

  • Start (or re-start) the Tomcat service, and verify in the orkweb.log file that all started normally.

Important notes:

  • When using a database created manually as opposed to by the first start of the orkweb application, it is necessary to apply the database indexes manually, to avoid performance issues down the line. Download create_indexes.sql nd execute it as recommended in the header of the file.

  • In the database-mssql-example.hbm.xml file, the recommended hibernate dialect to be used is net.sf.oreka.dialect.SQLServerUnicodeDialect. This dialect supports unicode and helps eliminate some potential performance issues related to queries based on indexed character columns. This dialect is officially available only as of OrkWeb version 1.9-3003. If needed with an earlier version of OrkWeb, please contact .

OrkWeb does not recognize non latin-based characters?!

If you are using MySQL, it may have defaulted to using the latin1 character set at installation. To use UTF8 instead, you need to perform the following steps:

  • Configure MySQL to use UTF8 by adding or modifying the following entries to in /etc/my.cnf file (Linux) or my.ini file (Windows) - make sure to keep a backup of the original files:

    [client]
              default-character-set=utf8
              ...
              [mysql]
              default-character-set=utf8
      
              [mysqld]
              default-character-set=utf8

  • Restart the MySQL service.

  • In MySQL, verify that the character sets are all UTF8 with the following command:

    SHOW VARIABLES LIKE 'character_set_%';

  • Convert all the oreka database tables to UTF8. You can download the mysql2utf8.sql script at http://files.orecx.com/tools/mysql2utf8.sql

    and execute it as follows from the command line:
    mysql -uroot -p<password> oreka < mysql2utf8.sql
    Replace <password> with your MySQL root password.
  • Edit the database.hbm.xml file (in /etc/okrweb on Linux, and typically in c:\program files\orkweb in Windows) and add the following suffix "?characterEncoding=UTF-8" to the "hibernate.connection.url" entry as in the example below:

    <property name="hibernate.connection.url">jdbc:mysql://localhost/oreka?characterEncoding=UTF-8</property>

  • Ensure that Tomcat is configured to run with the -Dfile.encoding=UTF-8 Java option (for the static text).

  • Restart the Tomcat service.

How do I configure a scorecard for QM?

Scorecards are often first written in spreadsheet files. Therefore a CSV format is the most natural extension for importing scorecards into OrkWeb. This means that a spreadsheet file may simply be saved in a CSV format and imported as is into OrkWeb, as long as it follows the guidelines and example below. Note that until OrkWeb version 2.11-6288, the key/value Group,name were used instead of GroupID,ID. It was modified to remove ambiguity around duplicate group names.

Scorecard CSV File Format

  • A line starting with the # symbol is considered to be a comment.

  • A non-comment line must contain comma-separated fields. The number of fields depends on the type of entry. There are 4 types of entries, distinguishable based on the first field:

    • Scorecard, name, comments
    • GroupID, ID
    • Section, name, weight, comments
    • Question, name, weight, comments
    • Answer, description, value, excluded, autofail, comments
  • Fields that are empty may be left blank. If one or more fields at the end of the line are empty, they may be simply omitted. OrkWeb will assign to them default values. Extra trailing fields that should not be there are simply ignored.

  • Entries are hierarchical and at least one entry is required at each level, i.e. a scorecard that does not have separate sections must define a section anyway. The only entry that is optional is the Group. If not specified, the scorecard is not associated to any group (not recommended).

  • A file may include multiple scorecards.

  • About the fields:

    • "id" is the oreka unique ID of the group the scorecard is to be associated with.
    • "name", "description" and "comments" fields are of type String. The string fields must be surrounded by double-quotes, e.g. "Group Name", and should not include any double quotes, commas, etc within them (for now)
    • "weight" fields are decimal values (stored as float). Default weight value: 1.0
    • "value" field is a number (stored as integer).
    • "excluded" and "autofail" are booleans, and take values: true or false, yes or no, 0 or 1. Defaults: false for both.
    • The keywords (Group, Scorcard, Question, Answer) are case-insensitive. They are mandatory at the beginning of the line.
    • name, description and value fields are mandatory. The rest are optional but must be represented (i.e. by a comma separator). See above for the default values for optional fields.

Scorecard CSV File Example

# Oreka sample scorecard CSV file: Scorecard_Generic_Example2_Sales.csv  
# Below 
is a summary description of the fields required:
#
#   Scorecard,name,comments
#   GroupID,id
#   Section,name,weight,comments
#   
Question,name,weight,comments 
#   Answer,text,value,excluded,autofail,comments
#
Scorecard,"Sales QA 
Form",
GroupID,15
#
Section,"Opening Call",,""
Question,"Professional Greeting - Intro",,""
Answer,"No",0,,,
Answer,"Yes",1,false,false,""
#
Section,"Information 
Verification / Data Collection",,""
Question,"Verify Zip Code",,
Answer,"No",0,,,
Answer,"Yes",1,,,
Question,"Collect 
Name",1.0,""
Answer,"No",0,,,
Answer,"Yes",2,,,
Question,"Collect Phone Number",1.0,""
Answer,"No",0,,,
Answer,"Yes",2,,,
Question,"Verify 
if Existing Customer and if Residence or Business",1.0,""
Answer,"No",0,,,
Answer,"Yes",2,,,
#
Section,"Establishing 
Purpose of Call",1.0,""
Question,"Reason for Call",1.0,""
Answer,"No",0,,,
Answer,"Yes",1,,,
Question,"Lead 
Source",1.0,""
Answer,"No",0,,,
Answer,"Yes",4,,,
#
...

Chapter 8. Glossary

Table of Contents

Glossary

Glossary

GSM 6.10 Codec

GSM 6.10 is an audio codec optimized for voice. It is the default storage codec for Oreka (wrapped into a wav file). It is used in the majority of the cellular networks worldwide and has a compression rate of 13 Kbit/s. When wrapped into a wav file it uses roughly 1.6 KByte of disk space per second of recorded audio. This means it's almost ten times more compact than MP3 format at standard compression rate. The advantage of this format is its ubiquity. It is possible to replay it in almost any existing Windows or Linux media player without installing any extra software or codec.

mcf file

Media Capture File format. It contains raw dumps of voice buffers in their original wire encoding. The file extension is ".mcf". This is an intermediate capture file format used before sessions are transcoded to their final storage format.

Primary pathname

The "primary" pathname for a media file is the one configured in the recorder's config.xml , for example in <AudioOutputPath> for OrkAudio.

Secondary pathname

The "secondary" pathname for a media file typically defaults to the YYYY/MM/DD/HH format and gets appended to the primary path. It may be configured separately in config.xml (e.g. <TapePathNaming> for OrkAudio).

Wildcard character

A wildcard character can be used to substitute for any other character or characters in a string. The asterisk character (*) substitutes for any zero or more characters. The question mark (?) substitutes for any one character.