ShoreTel Report Scheduler Application Installation and User Guide

INSTALLATION & USER GUIDE

ShoreTel Report Scheduler Application ShoreTel Professional Servcies

Introduction The ShoreTel Report Scheduler is an application which runs, stores, and delivers ShoreTel reports (built-in and enhanced) unattended. The application consists of report templates (one for each ShoreTel report) and a program which runs the report based on parameters specified in the report template. The Windows task scheduler (Scheduled Tasks) is configured to run the program periodically to create the report. When the Report Scheduler runs, it uses the current date/time and a configured reporting interval (e.g., daily, weekly, monthly...) to determine the report start and stop dates. Therefore, the application must be installed on a PC which is always running with network access to the CDR database on the ShoreTel Headquarters (Director) server and optional CDR archive database server. If a report was scheduled to run during a time the PC was powered off, this report will NOT run when power is restored to the PC. The application is geared toward system administrators who configure and schedule the report for users. Note: Administrators of this application will need to be comfortable with Microsoft tools including the Task Scheduler and knowledgable in general about their ShoreTel and general network setups. Features:  Reporting intervals: Daily, Work Week (5 consecutive days), Weekly, Monthly, Quarterly, Semiannually, Annually, and Custom. Note: the archive CDR database should be used for the longer reporting intervals.  Report output formats: PDF, RTF, XML, Excel, and Crystal  Report output is saved in the specified file system directory.  Email options to send the report as an email link or as an email attachment.  Supports main and archive CDR databases  Supports the Standard and Enhanced reports.

Notes:  The Report Scheduler cannot be installed on a ShoreTel server.  ShoreTel release 10.2 or greater is required to schedule enhanced reports.

ShoreTel Report Scheduler

Version 1.3.4

Page 1 of 39

Table of Contents Introduction ................................................................................................................................ 1 Table of Contents ....................................................................................................................... 2 Installation .................................................................................................................................. 3 Copy the ShoreTel Director Report Files ................................................................................ 8 ShoreTel Release 9.2 CDR Database Update ...................................................................... 10 Installation Folders ............................................................................................................... 11 Configuring Report Templates .................................................................................................. 12 Using InfoPath Forms to Create Report Templates .............................................................. 12 Manually Creating Report Templates.................................................................................... 14 Create a Scheduled Task to Run the Report Template ............................................................. 14 Windows XP/Server 2003 ..................................................................................................... 15 Windows 7/ Server 2008....................................................................................................... 22 Test the Report Template ......................................................................................................... 29 Windows XP/Server 2003 ..................................................................................................... 29 Windows 7/Server 2008........................................................................................................ 30 ShoreTel HQ Server Configuration ........................................................................................... 31 Log Files................................................................................................................................... 31 Appendix A - Report Template File ........................................................................................... 33 Scheduler Parameters .......................................................................................................... 33 Report Parameters ............................................................................................................... 35 Appendix B – Windows Task Scheduler Report Configurations ................................................ 37

ShoreTel Report Scheduler

Version 1.3.4

Page 2 of 39

Installation The application cannot be installed on a ShoreTel server. It must be installed on permanent running Windows server or PC:  The application requires the Windows (x86, 32 bit) version of the “MySQL ODBC 5.1 Driver” to access the CDR data on the ShoreTel Server. This driver must be downloaded and installed before installing the application. The driver can be downloaded from the MySQL website: http://www.mysql.com/products/connector/  You should have received a zip file named “STPSReportScheduler.X.Y.Z.zip”.  From the folder run the STPSReportSchedulerSetup.exe.  If you have not already installed the Microsoft .NET 2.0 runtime on the server you will be prompted to do so. If so, follow the prompts which should automatically download and install .NET from the Internet. Once this completes, continue with the install.  The Crystal Reports 2008 Runtime software will be downloaded and installed if necessary. Note: Administator privleges are required to install the Crystal Reports Runtime software. Follow the install prompts:

ShoreTel Report Scheduler

Version 1.3.4

Page 3 of 39

ShoreTel Report Scheduler

Version 1.3.4

Page 4 of 39

ShoreTel Report Scheduler

Version 1.3.4

Page 5 of 39

ShoreTel Report Scheduler

Version 1.3.4

Page 6 of 39

ShoreTel Report Scheduler

Version 1.3.4

Page 7 of 39

Copy the ShoreTel Director Report Files The Report Scheduler requires that the ShoreTel Director standard report files be copied to the the “Report Files” subdirectory. This should be done during the initial installation of the Report Scheduler and whenever the ShoreTel server is upgraded to a new software release. The ShoreTel standard report files are located in the “Reports” subdirectory on the Director (HQ) server as shown below. The report files have a file extension of “.rpt”.

All of the above report files must be copied to the Report Scheduler’s “Report Files” subdirectory as shown below.

ShoreTel Report Scheduler

Version 1.3.4

Page 8 of 39

A Windows event log entry is written when a new version of the ShoreTel software is detected. This warning will logged until adminstrator recopies the ShoreTel Director report files to the Report Scheduler’s “Report Files” subdirectory.

ShoreTel Report Scheduler

Version 1.3.4

Page 9 of 39

ShoreTel Release 9.2 CDR Database Update In order for the Report Scheduler to run trunk reports with ShoreTel Release 9.2, the CDR database must be updated to include a new database stored procedure. NOTE: The following procedure is only required for Release 9.2. Use the following steps to update the CDR database:  Copy the “Rel 9.2 CDR DB Update” folder (in the Report Scheduler installation folder) to the ShoreTel Headquarters (Director) server.  Logon to the ShoreTel Headquarters (Director) server and go to the “Rel 9.2 CDR DB Update” subdirectory.  The script “CreateCdrTrunkReports_sp.bat” contains a “mysql” command (as shown below) which may need to be modified if the ShoreTel Server software is not installed in the default location or if the “mysql” command is in a different folder on a CDR archive server.



Run the “CreateCdrTrunkReports_sp.bat” command.

ShoreTel Report Scheduler

Version 1.3.4

Page 10 of 39

Installation Folders The installation creates the following subfolders:

There are two categories of reports: the Standard Reports and the Enhanced Reports. The folders beginning with “Enhanced” pertain to the ShoreTel Enhanced Reports. The Enhanced Reports are licensed and require the installation of a application license key on the ShoreTel HQ (Director) server to run. The folders contain the following information:  [Enhanced] InfoPath Report Templates These two folders contain InfoPath templates which provide a graphical interface for configuring report parameters.  [Enhanced] Report Files These two folders contain the Crystal Reports report files.  [Enhanced] Report These two folders contain XML template files for configuring report parameters.

ShoreTel Report Scheduler

Version 1.3.4

Page 11 of 39

Configuring Report Templates The report template is an XML file containing the parameters to run the report and to save the report output. The following sections describe two methods for creating the report template file.

Using InfoPath Forms to Create Report Templates Microsoft InfoPath is included in Office Professional and provides a GUI interface for creating XML documents. The InfoPath form templates for each report are located in the application’s installation subfolders named “Infopath Report Templates” and “Enhanced InforPath Report Templates”::

Double-clicking on the “UserActivitySummary.xsn” brings up the form as shown below. If a new version of the InfoPath form is installed (e.g., Report Scheduler upgrade), you will be prompted to replace the old form on your computer with the new form.

ShoreTel Report Scheduler

Version 1.3.4

Page 12 of 39

After completing the form, the form can be saved as the Report Template. It is recommended that the filename be similar to the name given to the Windows Scheduled Task to run the report. See “Appendix A - Report Template File” for a description of the scheduler parameters.

ShoreTel Report Scheduler

Version 1.3.4

Page 13 of 39

Manually Creating Report Templates The report templates are located in the application’s installation subfolder named “Report Templates”:

The administrator should copy and rename a report template file to a subdirectory containing the configured report templates. It is recommended that the filename be similar to the name given to the Windows Scheduled Task to run the report. The template file is then edited (with Notepad or other editor) to contain the required scheduler and report parameters. See “Appendix A - Report Template File” for a description of the scheduler parameters.

Create a Scheduled Task to Run the Report Template The Report Scheduler uses the current date and time to determine the report start and end dates. Therefore, the report must be scheduled to run after complete CDR data is available for the end of the reporting interval. For example, a daily report which runs Monday through Friday that includes the hours from 8:00 am – 6:00 pm should be scheduled to run after 6:10 pm. If the report is run before 6:00 pm, the report is created for the previous day (since all the CDR data is not available) and results in generating reports for Sunday though Thursday. Listed below are guidelines for scheduling reports:    

Reports should run during non-busy hours (i.e., evenings, weekends) Only one report should be running at a time to minimize database performance issues. Reports should not be run between 2:00-3:00 am to avoid incomplete CDR data due to daily light savings time changes. Reports with long report intervals (e.g., quarterly, biannually, and annually) should be configured to use the CDR archive database.

ShoreTel Report Scheduler

Version 1.3.4

Page 14 of 39

Refer to “Appendix B – Windows Task Scheduler Report Configurations” for a list of report scheduling configurations.

Windows XP/Server 2003 The following steps demonstrate how to use Windows Scheduled Tasks to run a weekly (workweek) report: Start the Windows Task Scheduler by: Start->All Programs->Accessories->System Tools->Scheduled Tasks

Click on “Add Scheduled Task”

ShoreTel Report Scheduler

Version 1.3.4

Page 15 of 39

Click “Next”

Select “Browse…” and browse to the Report Scheduler installation directory.

Select “STPSReportScheduler.exe” and then “Open” ShoreTel Report Scheduler

Version 1.3.4

Page 16 of 39

Select Weekly and then press “Next”.

Set the start time, day of the week, and then press “Next”.

ShoreTel Report Scheduler

Version 1.3.4

Page 17 of 39

Enter the User account the Report Scheduler will run under and then press “Next”. This user should be domain user with an email account.

Select “Open advanced properties …” and press “Finish”.

ShoreTel Report Scheduler

Version 1.3.4

Page 18 of 39

The “Run” command must be modified to add the report template parameter. The report template filename is enclosed in double quotes and is added after the command name. For example, the command line should have: “c:\Program Files\ShoreTel\ShoreTel Report Scheduler\STPSReportScheduler.exe” “c:\temp\Report Templates\ SalesWeeklyGroupSummary.xml”. Note: The “Custom” reporting interval additionally requires the starting and ending report dates be passed as parameters after the report template. The dates must be in the US English format (e.g., mm/dd/yyyy) and each date should be enclosed in double quotes.

ShoreTel Report Scheduler

Version 1.3.4

Page 19 of 39

Select the “Settings” tab

. The default time to run a report should be changed to a smaller value depending on the ReportingInterval and the size of the database. For example, a daily report on a small system should not take longer than 30 minutes. In addition, the “Wake the computer to run this task” should be selected if the computer is configured to enter a power saving mode. Select “OK”

ShoreTel Report Scheduler

Version 1.3.4

Page 20 of 39

Enter the configured password from before and press “OK”.

Select “rename” and give this a name which reflects the report template:

ShoreTel Report Scheduler

Version 1.3.4

Page 21 of 39

Windows 7/ Server 2008 The following steps demonstrate how to use Windows Scheduled Tasks to run a weekly (workweek) report: Click on Start, type “task” and then select “Task Scheduler:

ShoreTel Report Scheduler

Version 1.3.4

Page 22 of 39

Select “New Folder” to create a folder for ShoreTel Reports:

Select “Create Basic Task” to create a new scheduled report:

ShoreTel Report Scheduler

Version 1.3.4

Page 23 of 39

Enter the report name and press next:

Select how often to run the report and press next:

ShoreTel Report Scheduler

Version 1.3.4

Page 24 of 39

Enter the report start time and day of the week, and then press next:

Select “Start a program” and press next:

ShoreTel Report Scheduler

Version 1.3.4

Page 25 of 39

Browse and select the Report Scheduler program. The default installation folder is “C:\Program Files (x86)\ShoreTel Report Scheduler\STPSReportScheduler.exe”

Select the “Open the Properties…” option and then press “Finish”.

ShoreTel Report Scheduler

Version 1.3.4

Page 26 of 39

Select the “Run whether user is logon on or not” and then select “Change User or Group …”

Enter the User credentials for the scheduled task:

ShoreTel Report Scheduler

Version 1.3.4

Page 27 of 39

Select the “Conditions” tab and select the “Wake the computer to run this task” option.

Select the “Open the Properties…” option and then press “Finish”.

ShoreTel Report Scheduler

Version 1.3.4

Page 28 of 39

Test the Report Template The report template can be tested by manually running the scheduled task.

Windows XP/Server 2003 Right click on the scheduled task and selecting “Run”:

The Scheduled Tasks status now changes to “Running”:

The Scheduled Tasks “Status” changes back to blank when the task has completed and displays the “Last Results”.

ShoreTel Report Scheduler

Version 1.3.4

Page 29 of 39

A “Last Results” of 0x0 indicates the report completed successfully. If an error occurs, the following command window is briefly displayed:

Windows 7/Server 2008 Select the scheduled task and then click on “Run”:

ShoreTel Report Scheduler

Version 1.3.4

Page 30 of 39

ShoreTel HQ Server Configuration The ShoreTel HQ server configuration is kept in the registry as displayed below. The Report Scheduler uses this configuration to validate the application is licensed and to access the server configuration data and CDR data.

Log Files By default, the application will write a log file containing informational and error messages. The logging feature allows more or less details to be logged by editing the logging XML file. As configured, the application will maintain a rolling history of up to 10 log files with a maximum of 1 Megabytes in each file. The log file is stored in the “%appdata%\ShoreTel Report Scheduler” where “%appdata%” is the application data folder for the User the report scheduler is running under. Assuming the report scheduler was running as “jmaskell” the log files are at: C:\Documents and Settings\jmaskell\Application Data\ShoreTel Report Scheduler The XML file which controls the logging is located in the application's directory and is named log4net.config. If you edit the file with (for example) notepad.exe, this shows the contents of the file:

ShoreTel Report Scheduler

Version 1.3.4

Page 31 of 39

To change the level of detail logged, you would want to change the "level value" in the root section and save the changes. Changes to the log level do NOT require a service restart. The above screen shot shows the value. The valid values in order of increasingly detailed logging (each level includes lower levels) are as follows:  FATAL Only fatal errors are logged.  ERROR Errors are logged.  WARN Warnings are logged.  INFO Informational events are logged.  DEBUG All logging is enabled.

ShoreTel Report Scheduler

Version 1.3.4

Page 32 of 39

Appendix A - Report Template File The report template file contains the parameters in an XML format for running a report. There are separate template files for each report. The template file contains two sections: scheduler parameters and report parameters. The scheduler parameters define such things as the report interval (date range of the report), the report output format (e.g., PDF, XML …), where the report is saved, and various options for emailing the report. The reporting parameters are the same as in ShoreTel Director with the exception of the report start and end date parameters. The report Scheduler calculates these parameters using the current date and configured reporting interval. The Report Template file is an XML file. Each parameter has a starting tag and an ending tag. Values for the parameter are placed between the starting and ending tags. The starting tag for a parameter consists of the parameter name enclosed by the less than (‘’) characters. Similarly, the ending tag consists of the parameter name enclosed by the less than and forward slash (‘’) characters. For example, , defines the SmtpHost parameter. To configure this parameter to “mySmtpHost.domain.com”, the value is placed between the beginning and closing tags like this: mySmtpHost.domain.com The following sections define the scheduler parameters and the reporting parameter types. The specific reporting parameters are documented in the report template files.

Scheduler Parameters 

UseArchiveDB (Boolean, mandatory) Specifies if the CDR archive database should be used.



ReportInterval (string, mandatory) The calendar period for the report. When the report runs, the current date and time are used to calculate the report start and end dates. The report dates are adjusted based on the reporting interval and daily start and end times to ensure the complete CDR data is in the database. For example, if a daily report with hours from 8:00 am to 6:00 pm runs at 3:00 pm, a report is created for the prior day since the data is not complete for the current day. o Daily Report includes the day’s data between the specified start and end times. If the report runs before the report end time, the report start and end date is adjusted to the prior day. o

Work Week Report includes the data from the prior 5 days. This interval allows a flexible work week that can begin on any day of the week. For example if the report runs on Friday after the report end time, the reporting period would include Monday through Friday. Likewise, a report run on Thursday would include Sunday through Thursday.

o

Weekly Report is for the prior 7 days of data.

ShoreTel Report Scheduler

Version 1.3.4

Page 33 of 39

o

Monthly Report is for the prior calendar month starting on the first day of the month and ending on the last day of the month.

o

Quarterly Report is for the prior 3 months

o

Biannually Report is for the prior 6 months

o

Annually Report is for the prior 12 months

o

Custom Report is scheduled to run once in the future and is based on a custom date interval. The start and stop dates are specified as report scheduler command line parameters.



WeekStartDay (string, mandatory) Specifies the starting day of week. This value is used for the work week and weekly report intervals. Values are Sunday, Monday (default), Tuesday, Wednesday, Thursday, Friday, and Saturday.



ReportOutputFormat (string, mandatory) Specifies the output format of the report. These following values correspond to the Crystal Reports export types: o CrystalReport (rpt file) o EditableRTF, RichText (rtf file) o Excel, ExcelRecord (xls file) o PortableDocFormat (pdf file) o WordForWindows (rtf file) o Xml (xml file)



DestinationFolder (string, optional if report is sent as an email attachment) The directory where the report is saved. If the scheduled report is configured to send an email with a link to the report, the destination folder should be specified as a UNC pathname.



FilenamePrefix (string, mandatory) The prefix of the report filename. A unique filename is automatically created by adding a filename suffix based on the date and time.



EmailReportLink (boolean, mandatory) Specifies if the email body should include a link to the saved report.



EmailAttachment (boolean, mandatory) Specifies if the report should be added as an email attachment.



SmtpHost (string, optional if email is not sent)

ShoreTel Report Scheduler

Version 1.3.4

Page 34 of 39

The smtp server name or IP address for sending email. This may be a Microsoft Exchange server. 

SmtpPort (integer, optional if email is not sent) The TCP/IP port number for the smtp server. The default value is port 25.



EnableSmtpSSL (Boolean, optional if email is not sent) Specifies if SSL is used to encrypt the connection.



EmailSubject (string, optional if email is not sent) The subject line for the email.



EmailFrom (string, optional if email is not sent) The sender’s email address. This email must correspond to the User’s credentials which the report is running under.



EmailTo (string, optional if email is not sent) Contains a single destination email address. Multiple “EmailTo” parameters may be added to send the report to multiple recipients.



EmailUseDefaultCredentials (Boolean, optional if email is not sent) Indicates the current report scheduler credentials (scheduled task credentials) are used for the SMTP server credentials. The preferred method is to use the default credentials. If this parameter is enabled, the following parameters “EmailUserCredentials” and “EmailPassowrdCredentials” are ignored.



EmailUserCredentials (string, optional if email is not sent) Specifies the username of the SMTP credential.



EmailPasswordCredentials (string, optional if email is not sent) Specifies the username password for the SMTP credential.

Report Parameters Report parameters are specific to each report but have following attributes: 

Kind: Discrete or Range A discrete kind of parameter represents a single value while a range parameter represents the inclusive values between the start and end value. A range value is indicated by a tilde (‘~‘) between the starting and ending values. Listed below are examples of range values: 2000~2999 (Inclusive values between 2000 and 2999) ~1999 (Values less than or equal to 1999) 3000~ (Values greater than or equal to 3000) ~ (All values) Note: the ‘~‘ value may be used in a discrete kind parameter to represent all values.

ShoreTel Report Scheduler

Version 1.3.4

Page 35 of 39





Type: one of the following data types: o Boolean - a value of either “True” or “False” o

String - a string of characters Note: extensions and workgroup numbers are defined as string values.

o

Time: a time value A time value may be in the 24 hour format of “hh:mm:ss” or the 12 hour format of “hh:mm:ss am/pm”. When the time parameter is used to define the report ending hour, the time should represent the second before the ending hour. For example, if the report time ends is 5:00 pm, the time should set as “4:59:59 pm”.

Multiple Values: indicates if multiple values are allowed Allows a parameter to be repeated in the template file with different values. The following is an example of multiple extension ranges for a the parameter named “Extensions”: 110~199 300~499 700~799

ShoreTel Report Scheduler

Version 1.3.4

Page 36 of 39

Appendix B – Windows Task Scheduler Report Configurations Desired Report Content

Report Interval

Windows Scheduled Tasks Configuration

Report Scheduler Notes

Daily  A daily report

Daily



Generates a daily report Monday through Sunday, 7 days a week. The “Start Time” is set to a time after the report end time.

Weekly  Daily for specified days of the week

Daily



Generates a daily report Monday though Friday (assuming work hour ends before 11:30 pm) The “Start Time” is set to a time after the report end time.

Weekly  Weekly (Monday thru Friday)

ShoreTel Report Scheduler

 WorkWeek

Version 1.3.4

Page 37 of 39

May run on any day before the ending time of the following week. The “WeekStartDay” parameter defines the report start day. For example, the report would include Monday though Friday if the work week began on Monday.

Desired Report Content

Report Interval

Windows Scheduled Tasks Configuration

Report Scheduler Notes

Weekly  Weekly (Monday through Sunday)

Weekly



May run on any day before the ending time of the following week. The week start day parameter defines work week

Monthly

Monthly

Monthly



Report runs on the first Saturday of the following month.



Report runs on the first Saturday following the quarter end.

Monthly

Quarterly (JanMar, Apr-Jun, JulSep, Oct-Dec)

ShoreTel Report Scheduler

Quarterly

Version 1.3.4

Page 38 of 39

Desired Report Content

Report Interval

Windows Scheduled Tasks Configuration

Report Scheduler Notes

Monthly

Biannually (JanMay and Jun-Dec)

Biannual



Report runs on the first Saturday following the biannual end.



Runs on the first Saturday of the next year.



The starting and ending report dates are passed as report scheduler command parameters following the report template. Date parameters are in the US English format (e.g., mm/dd/yyyy). The report should be scheduled to run after the end date for the report.

Monthly

Annually

Annual

One time only

Specific Date Range

Custom

 

ShoreTel Report Scheduler

Version 1.3.4

Page 39 of 39