INSTALLATION & USER GUIDE ShoreTel Report Scheduler Application ShoreTel Professional Servcies

Transcription

1 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. options to send the report as an link or as an 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 Page 1 of 39

2 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 Installation Folders Configuring Report Templates Using InfoPath Forms to Create Report Templates Manually Creating Report Templates Create a Scheduled Task to Run the Report Template Windows XP/Server Windows 7/ Server Test the Report Template Windows XP/Server Windows 7/Server ShoreTel HQ Server Configuration Log Files Appendix A - Report Template File Scheduler Parameters Report Parameters Appendix B Windows Task Scheduler Report Configurations ShoreTel Report Scheduler Version Page 2 of 39

3 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: 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 Page 3 of 39

4 ShoreTel Report Scheduler Version Page 4 of 39

5 ShoreTel Report Scheduler Version Page 5 of 39

6 ShoreTel Report Scheduler Version Page 6 of 39

7 ShoreTel Report Scheduler Version Page 7 of 39

8 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 Page 8 of 39

9 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 Page 9 of 39

10 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 Page 10 of 39

11 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 Page 11 of 39

12 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 Page 12 of 39

13 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 Page 13 of 39

14 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 Page 14 of 39

15 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 Page 15 of 39

16 Click Next Select Browse and browse to the Report Scheduler installation directory. Select STPSReportScheduler.exe and then Open ShoreTel Report Scheduler Version Page 16 of 39

17 Select Weekly and then press Next. Set the start time, day of the week, and then press Next. ShoreTel Report Scheduler Version Page 17 of 39

18 Enter the User account the Report Scheduler will run under and then press Next. This user should be domain user with an account. Select Open advanced properties and press Finish. ShoreTel Report Scheduler Version Page 18 of 39

19 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 Page 19 of 39

20 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 Page 20 of 39

21 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 Page 21 of 39

22 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 Page 22 of 39

23 Select New Folder to create a folder for ShoreTel Reports: Select Create Basic Task to create a new scheduled report: ShoreTel Report Scheduler Version Page 23 of 39

24 Enter the report name and press next: Select how often to run the report and press next: ShoreTel Report Scheduler Version Page 24 of 39

25 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 Page 25 of 39

26 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 Page 26 of 39

27 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 Page 27 of 39

28 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 Page 28 of 39

29 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 Page 29 of 39

30 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 Page 30 of 39

31 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 Page 31 of 39

32 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 Page 32 of 39

33 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 ing 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 ( < ) and greater than ( > ) characters. Similarly, the ending tag consists of the parameter name enclosed by the less than and forward slash ( </ ) characters and the greater than ( > ) characters. For example, <SmtpHost></SmtpHost>, defines the SmtpHost parameter. To configure this parameter to mysmtphost.domain.com, the value is placed between the beginning and closing tags like this: <SmtpHost> mysmtphost.domain.com </SmtpHost> 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 Page 33 of 39

34 o o o o 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. Quarterly Report is for the prior 3 months Biannually Report is for the prior 6 months Annually Report is for the prior 12 months 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 attachment) The directory where the report is saved. If the scheduled report is configured to send an 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. ReportLink (boolean, mandatory) Specifies if the body should include a link to the saved report. Attachment (boolean, mandatory) Specifies if the report should be added as an attachment. SmtpHost (string, optional if is not sent) ShoreTel Report Scheduler Version Page 34 of 39

35 The smtp server name or IP address for sending . This may be a Microsoft Exchange server. SmtpPort (integer, optional if is not sent) The TCP/IP port number for the smtp server. The default value is port 25. EnableSmtpSSL (Boolean, optional if is not sent) Specifies if SSL is used to encrypt the connection. Subject (string, optional if is not sent) The subject line for the . From (string, optional if is not sent) The sender s address. This must correspond to the User s credentials which the report is running under. To (string, optional if is not sent) Contains a single destination address. Multiple To parameters may be added to send the report to multiple recipients. UseDefaultCredentials (Boolean, optional if 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 UserCredentials and PassowrdCredentials are ignored. UserCredentials (string, optional if is not sent) Specifies the username of the SMTP credential. PasswordCredentials (string, optional if 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 Page 35 of 39

36 Type: one of the following data types: o Boolean - a value of either True or False o o String - a string of characters Note: extensions and workgroup numbers are defined as string values. 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 : <Extensions>110~199</Extensions> <Extensions>300~499</Extensions> <Extensions>700~799</Extensions> ShoreTel Report Scheduler Version Page 36 of 39

37 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) WorkWeek 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. ShoreTel Report Scheduler Version Page 37 of 39

38 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. Monthly Quarterly (Jan- Mar, Apr-Jun, Jul- Sep, Oct-Dec) Quarterly Report runs on the first Saturday following the quarter end. ShoreTel Report Scheduler Version Page 38 of 39

39 Desired Report Content Report Interval Windows Scheduled Tasks Configuration Report Scheduler Notes Monthly Biannually (Jan- May and Jun-Dec) Biannual Report runs on the first Saturday following the biannual end. Monthly Annually Annual Runs on the first Saturday of the next year. One time only Specific Date Range Custom 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. ShoreTel Report Scheduler Version Page 39 of 39