PINES Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Basic Reports Guide ======

===== Introduction =====

With the exception of transit list and cash reporting, reporting within Evergreen is quite different from many reporting modules out there.  It is designed to be as flexible as possible, to allow users to gather any type of data that is stored in the ILS database, and to design their own report queries.

The flip-side of this power and flexibility is that reporting in Evergreen is a somewhat complex operation.  Out of the box, Evergreen does not have any specific types of reports set up; a user or administrator must create report templates from scratch.  Also, reporting within Evergreen returns exactly the information that is requested, but does not turn it in a “pretty” form.  Evergreen returns the data as an Excel spreadsheet, bar or line graphs, and/or comma-delimited files.  It is up to the user to use this data to create documents as desired.

To streamline day-to-day reporting tasks, Evergreen allows sharing and reuse of user-created templates for reports.  For PINES, many commonly used reports have been set up by Evergreen administrators and made available to all PINES libraries. 

The information provided in this section is also available through the [[https://my.nicheacademy.com/pines/course/9061|Basic Reports Class]] in the PINES Learning Center.
===== Permissions, Components, and Navigation =====

==== Requisite User Permissions ====

See: [[reports:permissions|Permissions]]


==== Components of Reports ====

Evergreen reports are divided into three components:
  * Templates
  * Reports
  * Output

//**Templates**// generically define the type of report that will be generated and what sort of information will appear in it. In a template, the columns to be displayed in the report and types of filters are defined. In other words, a template defines the kind of question that is being asked. 

For example, one may wish to retrieve a count of new items added to a certain library branch in a given time interval. The template would specify that the requested data pertains to ‘creation date of copies’ and the filters are ‘by organizational unit’ and ‘within time interval’. The template would most likely not contain the specific library(ies) and date interval to be searched; these parameters would, instead, be specified by a report.

//**Reports**// are created from a template to define a specific query for information. Report creation is the step in which the user selects the options allowed by the template to gather a specific set of data. To continue the above example, one such option could be a list of libraries that could be chosen. Other options that might be defined here are the start and end date of the time interval.

Continuing with the example used above, if the same information is desired for a different library or date/relative date, a new report can be created from the template with the proper parameters. A report can be thought of as the specific question being asked; this question is derived from a template that defines the type of question being asked.

//**Output**// is the result of a report, containing the requested information – this is Evergreen’s answer to the question. The Output can be in the form of Excel spreadsheets, CSV (comma-delimited) files, or HTML. The Excel or CSV file formats allow the user to download the data and manipulate or format it with a spreadsheet program such as Microsoft Excel or Open Office. The HTML format presents the data visually as a bar graph, table, or line graph.

==== Organization ====

To open the Reports interface, click on **Reports** from the staff client home page.

{{:reports:egreports:pasted:20190502-120437.png}}

Upon opening the Reports interface, you will see a link to PINES Reports Classes, a link to this PINES Reports documentation, and sections for "My Folders" and "Shared Folders." "My Folders" and "Shared Folders" are each organized into a group of folders based on the three components of reports: Templates, Reports, and Output. 

{{:reports:egreports:reports_interface.png?600|}}

"Shared Folders" contain folders and report components shared by other users. This is where you can locate templates shared by PINES staff and other staff in your system who have the ability to create templates. “My Folders” is under the user’s control and is always accessible to the user. These folders reside permanently on the Evergreen server, so are accessible from any workstation. In order to properly save and run reports, users must create subfolders under each of the three main folders. It is recommended that each subfolder for any one of the components should have a corollary subfolder of the same name under the other two components. 

For example, a user may create a group of templates to gather circulation statistics. If a user creates a subfolder under “Templates” called “Circ Stats,” they should also create a “Circ Stats” folder under “Reports” and “Output,” and store reports and outputs created from the Circ Stats templates there. This is a good practice to keep related components organized.

To create a subfolder, click on the name of the main folder, enter the Subfolder name and share settings, and click **Create Sub Folder**. (Note: if you do not have the proper permissions for running reports, you will not be able to create subfolders. This action will fail silently.)

{{:reports:egreports:pasted:20220418-135206.png}}

In the reports creation process, the user’s templates are always stored in a subfolder of the user’s "Templates” folder; likewise, reports are always stored in a subfolder of the user’s “Reports” folder and outputs are always stored in a subfolder of the user’s “Output” folder. The location is specified at the time of creation, which will be covered below. Report components can be moved to other folders after creation, which will be covered in the Folder Management section of this document.

Depending on permissions, the user may be able to share folders within their local branch or system. Only PINES staff are able to share at the consortium level. A user can also see any folders that are shared with their organizational unit.

Shared folders can be used to disseminate useful templates so other organizations can benefit from your work. They can also be used to make specific reports and/or results available to other staff client users.  

=== Viewing and Managing Folders ===

Subfolders contain a folder management interface. To see the list of subfolders, click on the arrow or folder icon next to the main folder (Templates, Reports, Output). 

{{:reports:egreports:reports_expand_subfolders_2.png?300|}}

Click on the subfolder name next to the small page icon to display the subfolder contents as well as a management interface at the top of the display. The “Manage Folder Contents” option gives the user options for managing the templates, reports, and output in contained in the subfolder, and is the default display when opening a subfolder. 

{{:reports:egreports:reports_open_subfolder.png?600|}}

The “Manage Folder” option allows for editing the folder name and deleting, sharing, and hiding the current subfolder.

{{:reports:egreports:reports_manage_folder.png?600|}}

Components may be moved from one folder to another, as well. To do this, from the "Manage Folder Contents" screen, check the box next to the component to be moved. Then, select **Move the selected template/report/output(s) to a different folder** from the dropdown menu and click **Submit**.

{{:reports:egreports:reports_move_template.png?600|}}

This will take you to a list of your subfolders. Click on the name of the folder you would like the template to be moved to and click **Select Folder**.

{{:reports:egreports:reports_move_template_select_folder.png?300|}}

===== Using Pre-Made Templates =====

==== Finding a Suitable Report Template ====

PINES staff have created numerous pre-made templates that you can run without having to build your own templates or alter any settings. These are located under Shared Folders > Templates. In some cases, PINES staff will provide a 'path' for you to follow to run a specific template such as: 

//Shared Folders > Templates > terran > Help Desk > Bills > Daily Cash Report//

There is a list of [[reports:circ|Available Reports Templates]] in this document. You may also browse through lists of existing reports in the staff client. Good places to look for reports are:
  * Shared Folders > Templates > ddale > Web Client Templates > Helpdesk Request
  * Shared Folders > Templates > csharp > csharp-shared
  * Shared Folders > Templates > terran > Help Desk
  * Shared Folders > Templates > smorrison > Help Desk
  * Shared Folders > Templates > QRADMIN > Simple Reporting Tool

You may also use the search function at the top of the screen. We recommend typing in your keywords into the Template Query box but leaving the All Fields and All Folders dropdowns as-is:

{{:reports:egreports:pasted:20190502-121652.png}}

A sample list of reports will look something like this:

{{:reports:egreports:pasted:20190502-121750.png}}

<note tip>Be sure to change the 'Limit output to' field to All to see all available templates.</note>

<note tip>Check the date the report template was created (column titled create_time). If it is older than 3 years or you see XUL (instead of WebStaff) in the ui column, this means it was created in the old interface and may not be a reliable report template. If you try to clone a template and the fields aren’t populating, please submit a Help Desk ticket.</note>

==== Running a Report Template ====

Once you find a report template that you wish to run, check the box to the left of it, choose **Create a new report from selected template** at the top of the page, and click **Submit**. This will open a form with a few fields to fill in:

{{:reports:egreports:pasted:20190502-122210.png}}

  - Fill in a **report name** (the only rule on report names is that they must be unique - you cannot run two reports with the same name). As when running Quick Reports, it is a good idea to make the report name as descriptive as possible so that you may easily identify it in a list of reports.
  - Choose the **report folder** (as defined under My Folders > Reports) to store this saved form in.
  - Choose your **report parameters**. 
  - Choose the **output folder** (as defined under My Folders > Output) to store the report results.
  - Click **Save Report**.

**Notes on common parameters:**
  * A date can be a "Real Date" (specific calendar date) or a "Relative Date" (number of days ago).
  * Whenever filling in a date range, be sure to fill in the earliest date first (April 1 through April 7, or 8 days ago to 1 day ago).
  * When selecting a library, select the individual branch. If you need to select the entire system, select all branches in the system (//not// the system name itself - MOGL-SSI and MOGL-BWK rather than just MOGL). 
  * An email notification will automatically go to the email address associated with the current staff account when the report is complete. If you wish the notification to go to someone else, change the email address in the "Send completion notification to this Email address" field. Please be aware that to obtain email reports results, the recipient must be able to login into Evergreen and have the appropriate permissions. To send report results to a non-staff member, you will need to run the report, download the Excel file, and email the file as an attachment.
  * Multiple email addresses can be entered with commas between. Remove the email address entirely if you do not wish the system to send a notification.
  * Output Options: By default, your report will be created in Excel (preferred by most users) and HTML (for viewing in the browser). Depending on your needs, you may also choose CSV (comma-separated values), and you may choose to have it create simple bar and/or line charts with the HTML output as well.
  * Pivot Label Column and Pivot Data Column: Use these to change the layout of the resulting report output (for example, have the labels display on the side instead of the top). 

=== Running a Recurring Report ===

If you wish to create a recurring (repeating) report: 
  * Check the **Recurring Report** checkbox.
  * Set the **Recurrence Interval** to a specific number of days, weeks, or months.
  * Change the Run as soon as possible checkbox to the date checkbox for the starting date. 
  * Make sure that any dates referenced in the report parameters are relative dates, like in the example below (if you specify real dates, the report will run on the same set of dates every time; it is also possible to use a real date for the first date and a relative date for the second.)

{{:reports:egreports:reports_relative_date_range.png?400|}}

For example, to run a report every Monday morning on the previous week's activities:
  * Check the **Recurring Report** checkbox.
  * Set the **Recurrence Interval** to 1 week.
  * Change the **Run as soon as possible** checkbox to the upcoming Monday at 3am (or any time overnight). 
  * In the date range filter, make sure Choose a relative date range of 8 days ago to 1 day ago.

{{:reports:egreports:reports_recurring_options.png?400|}}

=== Cancel a Recurring Report ===
To stop a recurring report, go to the Output subfolder that houses the recurring report you are wanting to cancel. Click the checkbox next to the report and in the dropdown menu at the top of the screen, click **Delete selected output(s)** and then click **Submit**.

{{:reports:egreports:reports_delete_recurring_output.png?600|}}

=== How to Update the Email Address on a Recurring Report ===
It is fairly common for a recurring report to need to be transferred to a different email address. To accomplish this:

  - Log into the account that set up the recurring report.
  - Go to the **Reports** screen.
  - Click on **My Folders** > **Reports**
  - Navigate to where the recurring report is.
  - Click on the report line where it says **Edit**.

{{:reports:egreports:reports_edit_report.png?800|}}

  - Update the email address.
  - Click **Save Report**.

{{:reports:egreports:reports_email_update.png?300|}}

  - It will prompt you with a message saying that the change will be applied to future reports. **Click Accept**.

==== Viewing Report Results ====

1. Click on **My Folders** > **Output** (then your subfolder name(s)) to see the list of your reports that you have already run, that are currently running, and that you have scheduled to run in the future. 

2. **Pending Reports** (reports which are currently running or which are scheduled to run in the future) appear in the top section, and **Completed Reports** appear in the bottom section.

{{:reports:egreports:pasted:20190502-125536.png}}

3. View your completed report by checking the box next to the report, choosing **View Report Output** at the top of the page, and clicking **Submit**.

{{:reports:pasted:20190502-113058.png}}

If you chose the default report output options, you will see a page with links to **Tabular Output** (HTML, viewed in the browser screen) and to **Excel Output**. Most people prefer to view the results in Excel because they are able to take advantage of Excel’s sorting and calculating functions to further organize data and create charts.
==== Barcodes in Excel ====

The one small issue with using Excel is that it does not know how to display long numbers such as barcodes properly, so you may see columns of data that say “5.07E+13” or similar. To format these numbers correctly, see: [[reports:excel|Formatting Long Numbers in Excel]]

===== Cloning Existing Templates =====

If you find a template that you like, we recommend that you clone (copy) it to your own folder so that you can find it more easily next time you want to use it. (You can also modify templates during the cloning process, but that is covered in [[reports:egreports:advanced|Advanced Reports]].)

To clone a report template:
  - Check the box next to the report name.
  - Choose **Clone selected template** from the dropdown list at the top of the page.
  - Click **Submit**.
  - Select the report template folder (as defined under My Folders > Templates) to put the copy of the report template in.
  - Click **Select Folder**.

{{:reports:egreports:pasted:20190502-131308.png}}

The report template will open in the template editor view. If you do not wish to change anything about the template, you will only need to click the **Save Template** button and then **OK/Continue**. (Changing the Template Name and Template Description will not change anything about how the report runs, so they are safe to change without understanding the template editor.)

{{:reports:egreports:pasted:20190502-131633.png}}

Once the template is successfully cloned and saved, it will return you to the main screen, where you will be able to run it from your My Folders > Templates folder. A pop-up window will occur if there is an error.

{{:reports:egreports:reports_template_save_failed.png?200|}}