README.md

NICE-Telstra

WFM-NICE-IEX-Integration

Description

This is the repository for the Telstra WFM-IEX-Integration project.

Files

This project consists of the following Python and Bash scripts:

• 15_min_reports.py contains the main code for generating the 15-minute reports from data collected through requests to LivePerson API.

• loop.sh contains the sequence of steps to be performed every 15 minutes in order to generate the 15-minute reports. It calls the 15_min_reports.py script for report generation. This script should run in a loop scheduled using Cron job(s).

• config.navomi contains basic (some mandatory) configuration information, from access credentials for using LP API to local configurations of folders and FTP.

• rerun.sh contains the sequence of steps to be performed when there is a need to generate 15-minute reports for a given period in the past, up to 24 hours (limit imposed by the LP API). The number of reports to be generated is defined by the interval in the argument line (see usage below).

Configuring

Dependencies

These dependencies have to be fixed so that the scripts listed above run properly.

Install pip

pip will later be used to install other Python packages. To install pip you have to first download the installer at https://bootstrap.pypa.io/get-pip.py

Then you have to run the following command (as sudo):
# sudo python get-pip.py

Install requests package for Python

The requests package is used to send requests to the LivePerson API. To install this package you have to run the following command (as sudo):
# sudo pip install requests requests_oauthlib

Install datetime package for Python

The datetime package is used to do some date and time calculations and conversions. To install this package you have to run the following command (as sudo):
# sudo pip install datetime

Install bc command

The bc command is used to make mathematical operations within bash scripts. To install bc you have to run the following command (as sudo):
# sudo yum install bc for CentOS distro, or
# sudo apt-get install bc for Ubuntu/Debian-based distros.

Operational System considerations

The scripts use the command date for various operations. The date command has specific syntax for Mac OS and for Linux, and that is the reason why one of the arguments for running both loop.sh and rerun.sh is the indication of Operating System in which the script will run.

The specific difference within the date command syntax for the context of our scripts is when giving a timestamp as input to date. For Mac OS systems the command looks as follows:
# date -r [TIMESTAMP]
And for Linux (CentOS):
# date -d @[TIMESTAMP]
In both cases [TIMESTAMP] has to be provided with seconds resolution the least.

Report Conventions

Reports are generated always for the interval of 15 minutes. The date constituting the name of the report reflects the start of the 15-minute interval.

Report Naming

Reports name are like the following (in accordance to the NICE WFM Data Connector specification):
XX_MMDDYY.hhmm.xml

Where:

• XX: Letter combination identifying the TYPE of report. Possible values are
  AS: Agent System Data, AQ: Agent Queue Data, and Q: Queue Data
• MM: Two numeric digits representing the MONTH of the report interval
• DD: Two numeric digits representing the DAY of the report interval
• YY: Two numeric digits representing the last two digits of the YEAR of the
  report interval
• hh: Two numeric digits representing the 24h-clock HOUR of the report interval
• mm: Two numeric digits representing the MINUTES of the report interval

The extension of the report is set to .xml representing the structure of the report content.

Report Interval

When requested for a report, the script will generate the report for the 15-minute interval immediately before the calling time. Save the case of rerun.sh, which runs for intervals specified in the arguments of the script command call.

The hour is strictly divided into four periods of 15 minutes each, which are used to identify the report to be generated and also to define which time intervals of data collected through LivePerson API to process. The table below gives the relastionship between report time and data intervals. (Request time indicates the period in which a report can be requested.)

Request time	Report time	Intervals to be used *	Report name
hh:15:01:00 -- hh:29:59	hh:00	hh:05, hh:10, hh:15	XX_MMDDYY.hh00.xml
hh:30:01:00 -- hh:44:59	hh:15	hh:20, hh:25, hh:30	XX_MMDDYY.hh15.xml
hh:45:01:00 -- hh:59:59	hh:30	hh:35, hh:40, hh:45	XX_MMDDYY.hh30.xml
hh:00:01:00 -- hh:14:59	hh:45	hh:50, hh:55, hh:00 **	XX_MMDDYY.hh45.xml

* Intervals in LivePerson API are identified by the last minute of measured data. That is, hh:15 means the closing time for the interval containing data from hh:10:00 to hh:14:59.

** hh:00 means that hh is of the next hour.

Report Content

The report content and XML structure follow the specifications within the document NICE WFM Data Connector -- Historical Data Interface Design Specification (from 12/11/14, document version 1.10). For specifics about the structure of the XML files, please take a look at:

• Section 7.3 for Queue Data report
• Section 7.4 for Agent Queue Data report
• Section 7.5 for Agent System Data report

Running Scripts

For generating the 15-minute reports, the script loop.sh is the master script, i.e., the one to be run manually and that will make the calls to the other scripts automatically. The command line and expected arguments for calling each script is given below.

Running loop.sh

For running loop.sh the expected line arguments are, in this exact order:
# ./loop.sh [CONFIG FILE] [FTP OPT] [OS TYPE] [DEBUG OPT]

Where:

• CONFIG FILE is the path/to/config.file (default configuration file is config.navomi)
• FTP OPT is the FTP option, possible values are 1:Push and 2:Pull
• OS TYPE is the Operational System, possible values are 1:MacOS and 2:Linux
• DEBUG OPT is the debugging level, possible values are 0:None, 1:Basic and 2:Verbose

Examples:
# ./loop.sh config.navomi 2 1 0
To use configuration file config.navomi, reports will be stored in the folder specified in the configuration file to be retrieved via FTP pull, running in a Mac OS environment, and without debugging messages.

# ./loop.sh config.navomi 1 2 2
To use configuration file config.navomi, reports will be sent via FTP using destination host and credentials specified in the configuration file, running in a Linux environment, and with verbose debugging.

Running rerun.sh

For running rerun.sh the expected line arguments are, in this exact order:
# ./rerun.sh [CONFIG FILE] [FTP OPT] [OS TYPE] [DEBUG OPT] [OUTPUT PATH] [START TIME] [END TIME]

Where:

• CONFIG FILE is the path/to/config.file (default configuration file is config.navomi)
• FTP OPT is the FTP option, possible values are 1:Push and 2:Pull
• OS TYPE is the Operational System, possible values are 1:MacOS and 2:Linux
• DEBUG OPT is the debugging level, possible values are 0:None, 1:Basic and 2:Verbose
• OUTPUT PATH is the output folder to store reports to be generated (it has to be different than the one specified in the configuration file)
• START TIME is the start time for the report generation, i.e. the time for the first report to be generated. It has to be less than 24 hours back in time, and has to follow the format MMDDYY.hhmm* (UTC)
• END TIME is the end time for the report generation, i.e. the time for the last report to be generated. If only one report is to be generated, end time has to be equal than start time. It has to be less than 24 hours back in time, and has to follow the format MMDDYY.hhmm* (UTC)

* MMDDYY are the two digit month, day and year respectively; and hhmm are the two digit, 24-clock hour and minute respectively.

Example:
# ./rerun.sh config.navomi 1 1 1 old-reports/ 180917.1000 180917.1045
To use configuration file config.navomi, reports will be copied to the FTP folder given in the configuration file to be retrieved via FTP pull, running in a Mac OS environment, debugging messages set to basic, reports to be stored locally in the folder old-reports/. In this run, 4 reports will be generated, one for each quarter starting on 10AM o'clock of Sep 18th, 2017 (check table above for report naming).

Running 15_min_reports.py

For running 15_min_reports.py the expected line arguments are (all mandatory):

• -a : LivePerson API account number
• -k : LivePerson API key
• -s : LivePerson API secret
• -t : LivePerson API token
• -T : LivePerson API token secret
• -m : LivePerson API signature method
• -o : Output path for report
• -l : Output path for log files
• -f : LivePerson API request timeframe
• -i : LivePerson API request interval
• -v : LivePerson API request version
• -A : LivePerson API request agents IDs (comma separated if more than one)
• -S : LivePerson API request skill IDs (comma separated if more than one)
• -e : Input file with agent-to-employee IDs mapping
• -d : Start timestamp used to control which time intervals to process
• -F : End timestamp used to control which time intervals to process
• -V : Debug level (0:off, 1:basic, 2:verbose)
• -n : Base of the report name _MMDDYY.hhmm
• -j : Output path to store JSON files with replies from API (only used when debug is set to verbose mode)
• -es : Email server used to send out notifications
• -ep : Email server port, if any
• -ew : Email password for accessing the server to send out messages
• -ef : Address that is sending the message (account name in the server)
• -et : Address of message destination (only one address)
• -ej : Email subject line

NOTE: all the parameters above are either automatically calculated or retrieved from the configuration file informed on the command line of loop.sh and rerun.sh.