--- /dev/null
+Adding Data Sources to Reporter\r
+-------------------------------\r
+\r
+indexterm:[reports, adding data sources]\r
+\r
+You can further customize your Evergreen reporting environment by adding \r
+additional data sources.\r
+\r
+The Evergreen reporter module does not build and execute SQL queries directly, \r
+but instead uses a data abstraction layer called *Fieldmapper* to mediate queries \r
+on the Evergreen database.Fieldmapper is also used by other core Evergreen DAO \r
+services, including cstore and permacrud. The configuration file _fm_IDL.xml_ \r
+contains the mapping between _Fieldmapper_ class definitions and the database. \r
+The _fm_IDL.xml_ file is located in the _/openils/conf_ directory.\r
+\r
+indexterm:[fm_IDL.xml]\r
+\r
+There are 3 basic steps to adding a new data source. Each step will be discussed \r
+in more detail in the\r
+\r
+. Create a PostgreSQL query, view, or table that will provide the data for your \r
+data source.\r
+. Add a new class to _fm_IDL.xml_ for your data source.\r
+. Restart the affected services to see the new data source in Reporter.\r
+\r
+There are two possbile sources for new data sources:\r
+\r
+indexterm:[PostgreSQL]\r
+\r
+indexterm:[SQL]\r
+\r
+* An SQL query built directly into the class definition in _fm_IDL.xml_. You can \r
+use this method if you are only going to access this data source through the \r
+Evergreen reporter and/or cstore code that you write.\r
+* A new table or view in the Evergreen PostgresSQL database on which a class \r
+definition in _fm_IDL.xml_. You can use this method if you want to be able to \r
+access this data source through directly through SQL or using other reporting tool.\r
+\r
+Create a PostgreSQL query, view, or table for your data source\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[PostgreSQL]\r
+\r
+You need to decide whether you will create your data source as a query, a view, \r
+or a table.\r
+\r
+. Create a query if you are planning to access this data source only through the \r
+Evergreen reporter and/or cstore code that you write. You will use this query to \r
+create an IDL only view.\r
+. Create a view if you are planning to access this data source through other \r
+methods in addition to the Evergreen reporter, or if you may need to do \r
+performance tuning to optimize your query.\r
+. You may also need to use an additional table as part of your data source if \r
+you have additional data that's not included in the base Evergreen, or if you \r
+need to use a table to store the results of a query for performance reasons.\r
+\r
+To develop and test queries, views, and tables, you will need\r
+\r
+* Access to the Evergree PostgreSQL database at the command line. This is \r
+normally the psql application. You \r
+can access the Postgres documentation at the \r
+http://http://www.postgresql.org/docs/[Official Postgres documentation] for \r
+more information about PostgreSQL.\r
+* Knowledge of the Evergreen database structure for the data that you want to \r
+access. You can find this information by looking at the Evergreen schema\r
+http://docs.evergreen-ils.org/2.2/schema/[Evergreen schema] \r
+\r
+indexterm:[database schema]\r
+\r
+If the views that you are creating are purely local in usage and are not intended \r
+for contribution to the core Evergreen code, create the Views and Tables in the \r
+extend_reporter schema. This schema is intended to be used for local \r
+customizations and will not be modified during upgrades to the Evergreen system.\r
+\r
+You should make that you have an appropriate version control pocess for the SQL \r
+used to create you data sources.\r
+\r
+Here's an example of a view created to incorporate some locally defined user \r
+statistical categories:\r
+\r
+.example view for reports\r
+----------\r
+create view extend_reporter.patronstats as\r
+select u.id, \r
+grp.name as "ptype",\r
+rl.stat_cat_entry as "reg_lib",\r
+gr.stat_cat_entry as "gender",\r
+ag.stat_cat_entry as "age_group",\r
+EXTRACT(YEAR FROM age(u.dob)) as "age",\r
+hl.id as "home_lib",\r
+u.create_date,\r
+u.expire_date,\r
+ms_balance_owed\r
+from actor.usr u\r
+join permission.grp_tree grp \r
+ on (u.profile = grp.id and (grp.parent = 2 or grp.name = 'patron')) \r
+join actor.org_unit hl on (u.home_ou = hl.id)\r
+left join money.open_usr_summary ms \r
+ on (ms.usr = u.id) \r
+left join actor.stat_cat_entry_usr_map rl \r
+ on (u.id = rl.target_usr and rl.stat_cat = 4) \r
+left join actor.stat_cat_entry_usr_map bt \r
+ on (u.id = bt.target_usr and bt.stat_cat = 3) \r
+left join actor.stat_cat_entry_usr_map gr \r
+ on (u.id = gr.target_usr and gr.stat_cat = 2) \r
+left join actor.stat_cat_entry_usr_map gr \r
+ on (u.id = gr.target_usr and gr.stat_cat = 2) \r
+left join actor.stat_cat_entry_usr_map ag \r
+ on (u.id = ag.target_usr and ag.stat_cat = 1) \r
+where u.active = 't' and u.deleted <> 't';\r
+-----------\r
+\r
+Add a new class to fm_IDL.xml for your data source\r
+--------------------------------------------------\r
+\r
+Once you have your data source, the next step is to add that data source as a \r
+new class in _fm_IDL.xml_.\r
+\r
+indexterm:[fm_IDL.xml]\r
+\r
+You will need to add the following attributes for the class definition\r
+\r
+* *id*. You should follow a consistent naming convention for your class names \r
+that won't create conflicts in the future with any standard classes added in \r
+future upgrades. Evergreen normally names each class with the first letter of \r
+each word in the schema and table names. You may want to add a local prefix or \r
+suffix to your local class names.\r
+* *controller=”open-ils.cstore”*\r
+* *oils_obj:fieldmapper=”extend_reporter::long_name_of_view”*\r
+* *oils_persist.readonly=”true”*\r
+* *reporter:core=”true”* (if you want this to show up as a “core” reporting source)\r
+* *reporter:label*. This is the name that will appear on the data source list in \r
+the Evergreen reporter.\r
+* *oils_persist:source_definition*. If this is an IDL-only view, add the SQL query \r
+here. You don't need this attribute if your class is based on a PostgreSQL view \r
+or table.\r
+* *oils_persist:tablename="schemaname.viewname or tablename"* If this class is \r
+based on a PostgreSQL view or table, add the table name here. You don't need \r
+this attribute is your class is an IDL-only view.\r
+\r
+For each column in the view or query output, add field element and set the \r
+following attributes. The fields should be wrapped with _<field> </field>_\r
+\r
+* *reporter:label*. This is the name that appears in the Evergreen reporter.\r
+* *name*. This should match the column name in the view or query output.\r
+* *reporter:datatype* (which can be id, bool, money, org_unit, int, number, \r
+interval, float, text, timestamp, or link)\r
+\r
+For each linking field, add a link element with the following attributes. The \r
+elements should be wrapped with _<link> </link>_\r
+* *field* (should match field.name)\r
+* *reltype* (“has_a”, “might_have”, or “has_many”)\r
+* *map* (“”)\r
+* *key* (name of the linking field in the foreign table)\r
+* *class* (ID of the IDL class of the table that is to be linked to)\r
+\r
+The following example is a class definition for the example view that was created \r
+in the previous section.\r
+\r
+.example class definition for reports\r
+----------\r
+<class id="erpstats" controller="open-ils.reporter-store" \r
+oils_obj:fieldmapper="extend_reporter::patronstats" \r
+oils_persist:tablename="extend_reporter.patronstats" oils_persist:readonly="true" \r
+reporter:label="Patron Statistics" reporter:core="true">\r
+ <fields oils_persist:primary="id">\r
+ <field reporter:label="Patron ID" name="id" reporter:datatype="link" />\r
+ <field reporter:label="Patron Type" name="ptype" reporter:datatype="text" />\r
+ <field reporter:label="Reg Lib" name="reg_lib" reporter:datatype="text" />\r
+ <field reporter:label="Boro/Twp" name="boro_twp" reporter:datatype="text" />\r
+ <field reporter:label="Gender" name="gender" reporter:datatype="text" />\r
+ <field reporter:label="Age Group" name="age_group" reporter:datatype="text" />\r
+ <field reporter:label="Age" name="age" reporter:datatype="int" />\r
+ <field reporter:label="Home Lib ID" name="home_lib_id" \r
+ reporter:datatype="link" />\r
+ <field reporter:label="Home Lib Code" name="home_lib_code" \r
+ reporter:datatype="text" />\r
+ <field reporter:label="Home Lib" name="home_lib" reporter:datatype="text" />\r
+ <field reporter:label="Create Date" name="create_date" \r
+ reporter:datatype="timestamp" />\r
+ <field reporter:label="Expire Date" name="expire_date" \r
+ reporter:datatype="timestamp" />\r
+ <field reporter:label="Balance Owed" name="balance_owed" \r
+ reporter:datatype="money" />\r
+</fields>\r
+<links>\r
+ <link field="id" reltype="has_a" key="id" map="" class="au"/>\r
+ <link field="home_lib_id" reltype="has_a" key="id" map="" class="aou"/>\r
+</links>\r
+</class>\r
+---------\r
+\r
+NOTE: _fm_IDL.xml_ is used by other core Evergreen DAO services, including cstore \r
+and permacrud. So changes to this file can affect the entire Evergreen \r
+application, not just reporter. After making changes fm_IDL.xml, it is a good \r
+idea to ensure that it is valid XML by using a utility such as *xmllint* – a \r
+syntax error can render much of Evergreen nonfunctional. Set up a good change \r
+control system for any changes to fm_IDL.xml. You will need to keep a separate \r
+copy of you local class definitions so that you can reapply the changes to \r
+_fm_IDL.xml_ after Evergreen upgrades.\r
+\r
+Restart the affected services to see the new data source in the reporter\r
+------------------------------------------------------------------------\r
+\r
+The following steps are needed to for Evergreen to recognize the changes to \r
+_fm_IDL.xml_\r
+\r
+. Copy the updated _fm_IDL.xml_ Update _/openils/conf/fm_IDL.xml_ to \r
+_/openils/var/web/reports/fm_IDL.xml_\r
++\r
+-------------\r
+cp _/openils/conf/fm_IDL.xml /openils/var/web/reports/fm_IDL.xml\r
+-------------\r
++\r
+. Run Autogen to to update the Javascript versions of the fieldmapper definitions.\r
++\r
+-------------\r
+/openils/bin/autogen.sh\r
+-------------\r
++ \r
+. Restart C services\r
++\r
+-------------\r
+osrf_ctl.sh -l -a restart_c\r
+-------------\r
++\r
+. Restart the Evergreen reporter. You may need to modify this command depending \r
+on your system configuration and pid path\r
++\r
+------------\r
+opensrf-perl.pl -l -action restart -service open-ils.reporter \\r
+-config /openils/conf/opensrf_core.xml -pid-dir /openils/var/run\r
+------------\r
++\r
+. Restart the Evergreen application or _use Admin --> For Developers --> Clear \r
+Cache_\r
+\r
+\r
+\r
--- /dev/null
+Cloning Shared Templates\r
+------------------------\r
+\r
+indexterm:[reports, cloning]\r
+\r
+This chapter describes how to make local copies of shared templates for routine \r
+reports or as a starting point for customization. When creating a new template \r
+it is a good idea to review the shared templates first: even if the exact \r
+template you need does not exist it is often faster to modify an existing \r
+template than to build a brand new one. A Local System Administrator account is \r
+required to clone templates from the _Shared Folders_ section and save them to _My \r
+Folders_.\r
+\r
+The steps below assume you have already created at least one _Templates_ folder. \r
+If you haven’t done this, please see <<reporter_creating_folders,Creating Folders>>.\r
+\r
+. Access the reports interface from the _Admin_ (-) menu under _Local \r
+Administration --> Reports_\r
+. Under _Shared Folders_ expand the _Templates_ folder and the subfolder of the \r
+report you wish to clone. To expand the folders click on the grey arrow or \r
+folder icon. Do not click on the blue underlined hyperlink.\r
+. Click on the subfolder.\r
+. Select the template you wish to clone. From the dropdown menu choose _Clone \r
+selected templates_, then click _Submit_. \r
++\r
+NOTE: By default Evergreen only displays the first 10 items in any folder. To view \r
+all content, change the Limit output setting from 10 to All.\r
++\r
+. Choose the folder where you want to save the cloned template, then click \r
+_Select Folder_. Only template folders created with your account will be visible. \r
+If there are no folders to choose from please see \r
+<<reporter_creating_folders,Creating Folders>>.\r
+\r
+. The cloned template opens in the template editor. From here you may modify \r
+the template by adding, removing, or editing fields and filters as described in \r
+<<reporter_creating_templates,Creating Templates>>. _Template Name_ and \r
+_Description_ can also be edited. When satisfied with your changes click _Save_.\r
+\r
+. Click _OK_ in the resulting confirmation windows.\r
+\r
+Once saved it is not possible to edit a template. To make changes, clone a \r
+template and change the clone. \r
--- /dev/null
+[[reporter_creating_templates]]\r
+Creating Templates\r
+------------------\r
+\r
+indexterm:[reports, creating templates]\r
+\r
+Once you have created a folder, the next step in building a report is to create \r
+or clone a template. Templates allow you to run a report more than once without \r
+building it anew every time, by changing definitions to suit current \r
+requirements. For example, you can create a shared template that reports on \r
+circulation at a given library. Then, other libraries can use your template and \r
+simply select their own library when they run the report.\r
+\r
+It may take several tries to refine a report to give the output that you want. \r
+It can be useful to plan out your report on paper before getting started with \r
+the reporting tool. Group together related fields and try to identify the key \r
+fields that will help you select the correct source.\r
+\r
+It may be useful to create complex queries in several steps. For example, first \r
+add all fields from the table at the highest source level. Run a report and check \r
+to see that you get results that seem reasonable. Then clone the report, add any \r
+filters on fields at that level and run another report. Then drill down to the \r
+next table and add any required fields. Run another report. Add any filters at \r
+that level. Run another report. Continue until you’ve drilled down to all the \r
+fields you need and added all the filters. This might seem time consuming and \r
+you will end up cloning your initial report several times. However, it will help \r
+you to check the correctness of your results, and will help to debug if you run \r
+into problems because you will know exactly what changes caused the problem. \r
+Also consider adding extra fields in the intermediate steps to help you check \r
+your results for correctness.\r
+\r
+This example illustrates creating a template for circulation statistics. This is \r
+an example of the most basic template that you can create. The steps required to \r
+create a template are the same every time, but the tables chosen, how the data \r
+is transformed and displayed, and the filters used will vary depending on your \r
+needs.\r
+\r
+Choosing Report Fields\r
+~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reports, creating templates, choosing reports fields]\r
+\r
+. Click on the My Folder template folder where you want the template to be saved.\r
++\r
+image::media/create-template-1.png[create-template-1]\r
++\r
+. Click on Create a new Template for this folder.\r
++\r
+image::media/create-template-2.png[create-template-2]\r
++\r
+. You can now see the template creating interface. The upper half of the screen \r
+is the _Database Source Browser_. The top left hand pane contains the database \r
+_Sources_ drop-down list. This is the list of tables available as a starting point \r
+for your report. Commonly used sources are _Circulation_ (for circ stats and \r
+overdue reports), _ILS User_ (for patron reports), and _Item_ (for reports on a \r
+library's holdings).\r
++\r
+image::media/create-template-3.png[create-template-3]\r
++\r
+The Enable source nullability checkbox below the sources list is for advanced \r
+reporting and should be left unchecked by default.\r
++\r
+. Select _Circulation_ in the _Sources_ dropdown menu. Note that the _Core \r
+Sources_ for reporting are listed first, however it is possible to access all \r
+available sources at the bottom of this dropdown menu. You may only specify one \r
+source per template.\r
++\r
+image::media/create-template-4.png[create-template-4]\r
++\r
+. Click on _Circulation_ to retrieve all the field names in the Field Name pane. \r
+Note that the _Source_ Specifier (above the middle and right panes) shows the \r
+path that you took to get to the specific field.\r
++\r
+image::media/create-template-5.png[create-template-5]\r
++\r
+. Select _Circ ID_ in the middle _Field Name_ pane, and _Count Distinct_ from the \r
+right _Field Transform_ pane. The _Field Transform_ pane is where you choose how \r
+to manipulate the data from the selected fields. You are counting the number of \r
+circulations.\r
++\r
+indexterm:[reports, field transform]\r
++\r
+image::media/create-template-6.png[create-template-6]\r
++\r
+_Field Transforms_ have either an _Aggregate_ or _Non-Aggregate_ output type. \r
+See the section called <<field_transforms,Field Transforms>> for more about \r
+_Count, _Count Distinct_, and other transform options.\r
++\r
+. Click _Add Selected Fields_ underneath the _Field Transform_ pane to add this \r
+field to your report output. Note that _Circ ID_ now shows up in the bottom left \r
+hand pane under the _Displayed Fields_ tab.\r
++\r
+image::media/create-template-7.png[create-template-7]\r
++\r
+. _Circ ID_ will be the column header in the report output. You can rename \r
+default display names to something more meaningful. To do so in this example, \r
+select the _Circ ID_ row and click _Alter Display Header_.\r
++\r
+image::media/create-template-8.png[create-template-8]\r
++\r
+Double-clicking on the displayed field name is a shortcut to altering the \r
+display header.\r
++\r
+. Type in the new column header name, for example _Circ count_ and click _OK_.\r
++\r
+image::media/create-template-9.png[create-template-9]\r
++\r
+. Add other data to your report by going back to the _Sources_ pane and selecting \r
+the desired fields. In this example, we are going to add _Circulating Item --> \r
+Shelving Location_ to further refine the circulation report.\r
++\r
+In the top left hand _Sources_ pane, expand _Circulation_. Depending on your \r
+computer you will either click on the _+_ sign or on an arrow to expand the tree.\r
++\r
+image::media/create-template-10.png[create-template-10]\r
++\r
+Click on the _+_ or arrow to expand _Circulating Item_. Select \r
+_Shelving Location_.\r
++\r
+image::media/create-template-11.png[create-template-11]\r
++\r
+When you are creating a template take the shortest path to the field you need in \r
+the left hand Sources pane. Sometimes it is possible to find the same field name \r
+further in the file structure, but the shortest path is the most efficient.\r
++\r
+In the Field Name pane select Name.\r
++\r
+image::media/create-template-12.png[create-template-12]\r
++\r
+In the upper right _Field Transform_ pane, select _Raw Data_ and click _Add Selected_ \r
+Fields. Use _Raw Data_ when you do not wish to transform field data in any manner.\r
++\r
+image::media/create-template-13.png[create-template-13]\r
++\r
+Name will appear in the bottom left pane. Select the Name row and click _Alter \r
+Display Header_.\r
++\r
+image::media/create-template-15.png[create-template-15]\r
++\r
+. Enter a new, more descriptive column header, for example, _Shelving location_. \r
+Click _OK_.\r
++\r
+image::media/create-template-16.png[create-template-16]\r
++\r
+. Note that the order of rows (top to bottom) will correspond to the order of \r
+columns (left to right) on the final report. Select _Shelving location_ and click \r
+on _Move Up_ to move _Shelving location_ before _Circ count_.\r
++\r
+image::media/create-template-17.png[create-template-17]\r
++\r
+. Return to the _Sources_ pane to add more fields to your template. Under \r
+_Sources_ click _Circulation_, then select _Check Out Date/Time_ from the middle \r
+_Field Name_ pane.\r
++\r
+image::media/create-template-19.png[create-template-19]\r
++\r
+. Select _Year + Month_ in the right hand _Field Transform_ pane and click _Add \r
+Selected Fields_\r
++\r
+image::media/create-template-20.png[create-template-20]\r
++\r
+. _Check Out Date/Time_ will appear in the _Displayed Fields_ pane. In the report \r
+it will appear as a year and month _(YYYY-MM)_ corresponding to the selected tranform.\r
++\r
+image::media/create-template-21.png[create-template-21]\r
++\r
+. Select the _Check Out Date/Time_ row. Click _Alter Display Header_ and change \r
+the column header to _Check out month_.\r
++\r
+image::media/create-template-22.png[create-template-22]\r
++\r
+. Move _Check out month_ to the top of the list using the _Move Up_ button, so \r
+that it will be the first column in an MS Excel spreadsheet or in a chart. \r
+Report output will sort by the first column.\r
+\r
+image::media/create-template-23.png[create-template-23]\r
+\r
+[NOTE]\r
+======\r
+Note the _Change Transform_ button in the bottom left hand pane. It has the same \r
+function as the upper right _Field Transform_ pane for fields that have already \r
+been added.\r
+\r
+image::media/create-template-24.png[create-template-24]\r
+======\r
+\r
+\r
+Applying Filters\r
+~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reports, applying filters]\r
+\r
+Evergreen reports access the entire database, so to limit report output to a \r
+single library or library system you need to apply filters.\r
+\r
+After following the steps in the previous section you will see three fields in \r
+the bottom left hand _Template Configuration_ pane. There are three tabs in this \r
+pane: _Displayed Fields_ (covered in the previous section), _Base Filters_ and \r
+_Aggregate Filters_. A filter allows you to return only the results that meet \r
+the criteria you set.\r
+\r
+indexterm:[reports, applying filters, base filter]\r
+\r
+indexterm:[reports, applying filters, aggregate filters]\r
+\r
+_Base Filters_ apply to non-aggregate output types, while _Aggregate Filters_ are \r
+used for aggregate types. In most reports you will be using the _Base Filters_ tab. \r
+For more information on aggregate and non-aggregate types see the section called \r
+“Field Transforms”.\r
+\r
+There are many available operators when using filters. Some examples are _Equals_, \r
+_In list_, is _NULL_, _Between_, _Greater than_ or _equal to_, and so on. _In list_ \r
+is the most flexible operator, and in this case will allow you flexibility when \r
+running a report from this template. For example, it would be possible to run a \r
+report on a list of timestamps (in this case will be trimmed to year and month \r
+only), run a report on a single month, or run a report comparing two months. It \r
+is also possible to set up recurring reports to run at the end of each month.\r
+\r
+In this example we are going to use a Base Filter to filter out one library’s \r
+circulations for a specified time frame. The time frame in the template will be \r
+configured so that you can change it each time you run the report.\r
+\r
+Using Base Filters\r
+^^^^^^^^^^^^^^^^^^\r
+\r
+indexterm:[reports, applying filters, base filter]\r
+\r
+. Select the _Base Filters_ tab in the bottom _Template Configuration_ pane.\r
+\r
+. For this circulation statistics example, select _Circulation --> Check Out \r
+Date/Time --> Year + Month_ and click on _Add Selected Fields_. You are going to \r
+filter on the time period.\r
++\r
+image::media/create-template-25.png[create-template-25]\r
++\r
+. Select _Check Out Date/Time_. Click on _Change Operator_ and select _In list_ \r
+from the dropdown menu. \r
++\r
+image::media/create-template-26.png[create-template-26]\r
++\r
+. To filter on the location of the circulation select \r
+_Circulation --> Circulating library --> Raw Data_ and click on _Add Selected Fields_.\r
++\r
+image::media/create-template-27.png[create-template-276]\r
++\r
+. Select _Circulating Library_ and click on _Change Operator_ and select _Equals_. \r
+Note that this is a template, so the value for _Equals_ will be filled out when \r
+you run the report.\r
++\r
+image::media/create-template-28.png[create-template-28]\r
++\r
+For multi-branch libraries, you would select _Circulating Library_ with _In list_ \r
+as the operator, so you could specify the branch(es) when you run the report. This \r
+leaves the template configurable to current requirements. In comparison, sometimes \r
+you will want to hardcode true/false values into a template. For example, deleted \r
+bibliographic records remain in the database, so perhaps you want to hardcode \r
+_deleted=false_, so that deleted records don’t show up in the results. You might \r
+want to use _deleted=true_, for a template for a report on deleted items in the \r
+last month.\r
++\r
+. Once you have configured your template, you must name and save it. Name this \r
+template _Circulations by month for one library_. You can also add a description. \r
+In this example, the title is descriptive enough, so a description is not necessary. \r
+Click _Save_.\r
++\r
+image::media/create-template-29.png[create-template-29]\r
++\r
+. Click _OK_.\r
++\r
+image::media/create-template-30.png[create-template-30]\r
++\r
+. You will get a confirmation dialogue box that the template was successfully \r
+saved. Click OK.\r
++\r
+image::media/create-template-31.png[create-template-31]\r
++\r
+After saving it is not possible to edit a template. To make changes you will \r
+need to clone it and edit the clone\r
+\r
+[NOTE]\r
+==========\r
+The bottom right hand pane is also a source specifier. By selecting one of these \r
+rows you will limit the fields that are visible to the sources you have specified. \r
+This may be helpful when reviewing templates with many fields. Use *Ctrl+Click* to \r
+select or deselect items.\r
+\r
+image::media/create-template-32.png[create-template-32]\r
+==========\r
+\r
+\r
+\r
--- /dev/null
+Starting and Stopping the Reporter Daemon\r
+-----------------------------------------\r
+\r
+indexterm:[reports, starting server application]\r
+\r
+indexterm:[reporter, starting daemon]\r
+\r
+Before you can view reports, the Evergreen administrator must start \r
+the reporter daemon from the command line of the Evergreen server.\r
+\r
+The reporter daemon periodically checks for requests for new reports or \r
+scheduled reports and gets them running.\r
+\r
+Starting the Reporter Daemon\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reporter, starting]\r
+\r
+To start the reporter daemon, run the following command as the opensrf user:\r
+\r
+----\r
+clark-kent.pl --daemon\r
+----\r
+\r
+You can also specify other options:\r
+\r
+* *sleep=interval*: number of seconds to sleep between checks for new reports to \r
+run; defaults to 10\r
+* *lockfile=filename*: where to place the lockfile for the process; defaults to \r
+/tmp/reporter-LOCK\r
+* *concurrency=integer*: number of reporter daemon processes to run; defaults to \r
+1\r
+* *boostrap=filename*: OpenSRF bootstrap configuration file; defaults to \r
+/openils/conf/opensrf_core.xml\r
+\r
+\r
+[NOTE]\r
+=============\r
+The open-ils.reporter process must be running and enabled on the gateway before \r
+the reporter daemon can be started.\r
+\r
+Remember that if the server is restarted, the reporter daemon will need to be \r
+restarted before you can view reports unless you have configured your server to \r
+start the daemonautomatically at start up time. \r
+==============\r
+\r
+Stopping the Reporter Daemon\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reports, stopping server application]\r
+\r
+indexterm:[reporter, stopping daemon]\r
+\r
+To stop the reporter daemon, you have to kill the process and remove the \r
+lockfile. Assuming you're running just a single process and that the \r
+lockfile is in the default location, perform the following commands as the \r
+opensrf user:\r
+\r
+----\r
+kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`\r
+\r
+rm /tmp/reporter-LOCK\r
+----\r
+\r
--- /dev/null
+Exporting Report Templates Using phpPgAdmin\r
+-------------------------------------------\r
+\r
+indexterm:[reports, exporting templates]\r
+\r
+Once the data is exported. Database Administrators/Systems Administrators can \r
+easily import this data into the templates folder to make it available in the \r
+client.\r
+\r
+Dump the Entire Reports Template Table\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+The data exported in this method can create issues importing into a different \r
+system if you do not have a matching folder and owner. This is going to export \r
+report templates created in your system. The most important fields for importing \r
+into the new system are _name_, _description_, and _data_. Data defines the actual \r
+structure of the report. The _owner_ and _folder_ fields will unique to the system \r
+they were exported from and will have to be altered to ensure they match the \r
+appropriate owner and folder information for the new system.\r
+\r
+. Go to the *Reporter* schema. Report templates are located in the *Template* table\r
+. Click on the link to the *Template* table\r
+. Click the *export* button at the top right of the phpPgAdmin screen\r
+. Make sure the following is selected\r
+.. _Data Only_ (checked)\r
+.. _Format_: Select _CSV_ or _Tabbed_ did get the data in a text format\r
+.. _Download_ checked\r
+. Click _export_ button at the bottom\r
+. A text file will download to your local system\r
+\r
+Dump Data with an SQL Statement\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+\r
+The following statement could be used to grab the data in the folder and dump it \r
+with admin account as the owner and the first folder in your system.\r
+\r
+-------------\r
+SELECT 1 as owner, name, description, data, 1 as folder FROM reporter.template\r
+-------------\r
+\r
+or use the following to capture your folder names for export\r
+\r
+--------------\r
+SELECT 1 as owner, t.name, t.description, t.data, f.name as folder \r
+ FROM reporter.template t \r
+ JOIN reporter.template_folder f ON t.folder=f.id\r
+--------------\r
+ \r
+. Run the above query\r
+. Click the *download* link at the bottom of the page\r
+. Select the file format (_CSV_ or _Tabbed_)\r
+. Check _download_\r
+. A text file with the report template data will be downloaded.\r
+\r
+\r
--- /dev/null
+[[reporter_folders]]\r
+Folders\r
+-------\r
+\r
+indexterm:[reports, folders]\r
+\r
+There are three main components to reports: _Templates_, _Reports_, and _Output_. \r
+Each of these components must be stored in a folder. Folders can be private \r
+(accessible to your login only) or shared with other staff at your library, \r
+other libraries in your system or consortium. It is also possible to selectively \r
+share \r
+only certain folders and/or subfolders.\r
+\r
+There are two parts to the folders pane. The _My Folders_ section contains folders \r
+created with your Evergreen account. Folders that other users have shared with \r
+you appear in the _Shared Folders_ section under the username of the sharing \r
+account.\r
+\r
+image::media/folder-1.png[folder-1]\r
+\r
+[[reporter_creating_folders]]\r
+Creating Folders\r
+~~~~~~~~~~~~~~~~\r
+\r
+\r
+indexterm:[reports, folders, creating]\r
+\r
+Whether you are creating a report from scratch or working from a shared template \r
+you must first create at least one folder.\r
+\r
+The steps for creating folders are similar for each reporting function. It is \r
+easier to create folders for templates, reports, and output all at once at the \r
+beginning, though it is possible to do it before each step. This example \r
+demonstrates creating a folder for a template.\r
+\r
+. Click on _Templates_ in the _My Folders_ section.\r
+. Name the folder. Select _Share_ or _Do not share_ from the dropdown menu.\r
+. If you want to share your folder, select who you want to share this folder \r
+with from the dropdown menu.\r
+. Click _Create Sub Folder_.\r
+. Click _OK_.\r
+. Next, create a folder for the report definition to be saved to. Click on \r
+_Reports_.\r
+. Repeat steps 2-5 to create a Reports folder also called _Circulation_.\r
+. Finally, you need to create a folder for the report’s output to be saved in. \r
+Click on _Output_.\r
+. Repeat steps 2-5 to create an Output folder named _Circulation_.\r
+\r
+\r
+TIP: Using a parallel naming scheme for folders in Templates, Reports, \r
+and Output helps keep your reports organized and easier to find\r
+\r
+The folders you just created will now be visible by clicking the arrows in _My \r
+Folders_. Bracketed after the folder name is whom the folder is shared with. For \r
+example, _Circulation (BNCLF)_ is shared with the North Coast Library Federation. \r
+If it is not a shared folder there will be nothing after the folder name. You \r
+may create as many folders and sub-folders as you like.\r
+\r
+Managing Folders\r
+~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reports, folders, managing]\r
+\r
+Once a folder has been created you can change the name, delete it, create a new \r
+subfolder, or change the sharing settings. This example demonstrates changing a \r
+folder name; the other choices follow similar steps\r
+\r
+. Click on the folder that you wish to rename.\r
+. Click _Manage Folder_.\r
+. Select _Change folder name_ from the dropdown menu and click _Go_.\r
+. Enter the new name and click _Submit_.\r
+. Click _OK_.\r
+. You will get a confirmation box that the _Action Succeeded_. Click _OK_.\r
+\r
+\r
+\r
--- /dev/null
+[[generating_reports]]\r
+Generating Reports from Templates\r
+----------------------------------\r
+\r
+indexterm:[reports, generating]\r
+\r
+Now you are ready to run the report from the template you have created.\r
+\r
+. In the My Folders section click the arrow next to _Templates_ to expand this \r
+folder and select _circulation_.\r
++\r
+image::media/generate-report-1.png[generate-report-1]\r
++\r
+. Select the box beside _Circulations by month for one library_. Select _Create a \r
+new report_ from selected template from the dropdown menu. Click _Submit_. \r
++\r
+image::media/generate-report-2.png[generate-report-2]\r
++\r
+. Complete the first part of report settings. Only _Report Name_ and _Choose a \r
+folder_... are required fields.\r
++\r
+image::media/generate-report-3.png[generate-report-3]\r
++\r
+1) _Template Name_, _Template Creator_, and _Template Description_ are for \r
+informational purposes only. They are hard coded when the template is created. \r
+At the report definition stage it is not possible to change them.\r
++\r
+2) _Report Name_ is required. Reports stored in the same folder must have unique \r
+names.\r
++\r
+3) _Report Description_ is optional but may help distinguish among similar \r
+reports.\r
++\r
+4) _Report Columns_ lists the columns that will appear in the output. This is \r
+derived from the template and cannot be changed during report definition.\r
++\r
+5) _Pivot Label Column_ and _Pivot Data Column_ are optional. Pivot tables are a \r
+different way to view data. If you currently use pivot tables in MS Excel it is \r
+better to select an Excel output and continue using pivot tables in Excel.\r
++\r
+6) You must choose a report folder to store this report definition. Only report \r
+folders under My Folders are available. Click on the desired folder to select it.\r
++\r
+. Select values for the _Circulation > Check Out Date/Time_. Use the calendar \r
+widget or manually enter the desired dates, then click Add to include the date \r
+on the list. You may add multiple dates.\r
++\r
+image::media/generate-report-8.png[generate-report-8]\r
++\r
+The Transform for this field is Year + Month, so even if you choose a specific \r
+date (2009-10-20) it will appear as the corresponding month only (2009-10).\r
++\r
+It is possible to select *relative dates*. If you select a relative date 1 month \r
+ago you can schedule reports to automatically run each month. If you want to run \r
+monthly reports that also show comparative data from one year ago, select a \r
+relative date 1 month ago, and 13 months ago.\r
++\r
+. Select a value for the _Circulating Library_.\r
+. Complete the bottom portion of the report definition interface, then click \r
+_Save_.\r
++\r
+image::media/generate-report-10.png[generate-report-10]\r
++\r
+1) Select one or more output formats. In this example the report output will be \r
+available as an Excel spreadsheet, an HTML table (for display in the staff \r
+client or browser), and as a bar chart.\r
++\r
+2) If you want the report to be recurring, check the box and select the \r
+_Recurrence Interval_ as described in <<recurring_reports,Recurring Reports>>. \r
+In this example, as this is a report that will only be run once, the _Recurring \r
+Report_ box is not checked.\r
++\r
+3) Select _Run_ as soon as possible for immediate output. It is also possible to \r
+set up reports that run automatically at future intervals.\r
++\r
+4) It is optional to fill out an email address where a completion notice can be \r
+sent. The email will contain a link to password-protected report output (staff \r
+login required). If you have an email address in your Local System Administrator \r
+account it will automatically appear in the email notification box. However, \r
+you can enter a different email address or multiple addresses separated by commas.\r
++\r
+. Select a folder for the report's output.\r
+. You will get a confirmation dialogue box that the Action Succeeded. Click _OK_.\r
++\r
+image::media/generate-report-14.png[generate-report-14]\r
++\r
+Once saved, reports stay there forever unless you delete them.\r
--- /dev/null
+[[recurring_reports]]\r
+Running Recurring Reports\r
+-------------------------\r
+\r
+indexterm:[reports, recurring]\r
+\r
+Recurring reports are a useful way to save time by scheduling reports that you \r
+run on a regular basis, such as monthly circulation and monthly patron \r
+registration statistics. When you have set up a report to run on a monthly basis \r
+you’ll get an email informing you that the report has successfully run. You can \r
+click on a link in the email that will take you directly to the report output. \r
+You can also access the output through the reporter interface as described in \r
+<<viewing_report_output,Viewing Report Output>>.\r
+\r
+To set up a monthly recurring report follow the procedure in <<generating_reports,\r
+Generating Reports from Templates>> but make the changes described below.\r
+\r
+. Select the Recurring Report check-box and set the recurrence interval to 1 month.\r
+. Do not select Run ASAP. Instead schedule the report to run early on the first \r
+day of the next month. Enter the date in _YYYY-MM-DD_ format.\r
+. Ensure there is an email address to receive completion emails. You will \r
+receive an email completion notice each month when the output is ready.\r
+. Select a folder for the report’s output.\r
+. Click Save Report.\r
+. You will get a confirmation dialogue box that the Action Succeeded. Click OK.\r
+\r
+You will get an email on the 1st of each month with a link to the report output. \r
+By clicking this link it will open the output in a web browser. It is still \r
+possible to login to the staff client and access the output in Output folder.\r
+\r
+*How to stop or make changes to an existing recurring report?* Sometimes you may \r
+wish to stop or make changes to a recurring report, e.g. the recurrence interval, \r
+generation date, email address to receive completion email, output format/folder \r
+or even filter values (such as the number of days overdue). You will need to \r
+delete the current report from the report folder, then use the above procedure \r
+to set up a new recurring report with the desired changes. Please note that \r
+deleting a report also deletes all output associated with it.\r
+\r
+TIP: Once you have been on Evergreen for a year, you could set up your recurring \r
+monthly reports to show comparative data from one year ago. To do this select \r
+relative dates of 1 month ago and 13 months ago.\r
+\r
--- /dev/null
+Template Terminology\r
+--------------------\r
+\r
+Data Types\r
+~~~~~~~~~~\r
+\r
+indexterm:[reports, data types]\r
+\r
+The central column of the _Database Source Browser_ lists _Field Name_ and _Data \r
+Type_ for the selected database table.\r
+\r
++\r
+image::media/view-output-2.png[view-output-2]\r
++\r
+\r
+Each data type has its own characteristics and uses:\r
+\r
+[options="header,footer"]\r
+|====================================\r
+|Data Type |Description |Notes\r
+|id |Unique number assigned by the database to identify a \r
+record |A number that is a meaningful reference for the database but not \r
+of much use to a human user. Use in displayed fields when counting records or \r
+in filters.\r
+|text |Text field |Usually uses the Raw Data transform.\r
+|timestamp |Exact date and time |Select appropriate date/time transform. \r
+Raw Data includes second and timezone information, usually more than is required \r
+for a report.\r
+|bool |True or False |Commonly used to filter out deleted item or patron records.\r
+|org_unit |A number representing a library, library system, or \r
+federation |When you want to filter on a library, make sure that the field \r
+name is on an org_unit or id data type.\r
+|link |A link to another database table |Link outputs a number that is a \r
+meaningful reference for the database but not of much use to a human user. You \r
+will usually want to drill further down the tree in the Sources pane and select \r
+fields from the linked table. However, in some instances you might want to use \r
+a link field. For example, to count the number of patrons who borrowed items you \r
+could do a count on the Patron link data.\r
+|int |Integer \r
+|money |Number (in dollars) \r
+|=====================================\r
+\r
+Field Transforms\r
+~~~~~~~~~~~~~~~~\r
+\r
+indexterm:[reports, field transforms]\r
+\r
+A _Field Transform_ tells the reporter how to process a field for output. \r
+Different data types have different transform options.\r
+\r
+indexterm:[reports, field transforms, raw data]\r
+\r
+*Raw Data*. To display a field exactly as it appears in the database use the \r
+_Raw Data_ transform, available for all data types.\r
+\r
+indexterm:[reports, field transforms, count]\r
+\r
+indexterm:[reports, field transforms, raw distinct]\r
+\r
+*Count and Count Distinct*. These transforms apply to the _id_ data type and \r
+are used to count database records (e.g. for circulation statistics). Use Count \r
+to tally the total number of records. Use _Count Distinct_ to count the number \r
+of unique records, removing duplicates.\r
+\r
+To demonstrate the difference between _Count_ and _Count Distinct_, consider an \r
+example where you want to know the number of active patrons in a given month, \r
+where ``active" means they borrowed at least one item. Each circulation is linked \r
+to a _Patron ID_, a number identifying the patron who borrowed the item. If we use \r
+the _Count Distinct_ transform for Patron IDs we will know the number of unique \r
+patrons who circulated at least one book (2 patrons in the table below). If \r
+instead, we use _Count_, we will know how many books were circulated, since every \r
+circulation is linked to a _patron ID_ and duplicate values are also counted. To \r
+identify the number of active patrons in this example the _Count Distinct_ \r
+transform should be used.\r
+\r
+[options="header,footer"]\r
+|====================================\r
+|Title |Patron ID |Patron Name\r
+|Harry Potter and the Chamber of Secrets |001 |John Doe\r
+|Northern Lights |001 |John Doe\r
+|Harry Potter and the Philosopher’s Stone |222 |Jane Doe\r
+|====================================\r
+\r
+indexterm:[reports, field transforms, output type]\r
+\r
+*Output Type*. Note that each transform has either an _Aggregate_ or \r
+_Non-Aggregate_ output type.\r
+\r
+indexterm:[reports, field transforms, output type, non-aggregate]\r
+\r
+indexterm:[reports, field transforms, output type, aggregate]\r
+\r
+Selecting a _Non-Aggregate_ output type will return one row of output in your \r
+report for each row in the database. Selecting an Aggregate output type will \r
+group together several rows of the database and return just one row of output \r
+with, say, the average value or the total count for that group. Other common \r
+aggregate types include minimum, maximum, and sum.\r
+\r
+When used as filters, non-aggregate and aggregate types correspond to _Base_ and \r
+_Aggregate_ filters respectively. To see the difference between a base filter and \r
+an aggregate filter, imagine that you are creating a report to count the number \r
+of circulations in January. This would require a base filter to specify the \r
+month of interest because the month is a non-aggregate output type. Now imagine \r
+that you wish to list all items with more than 25 holds. This would require an \r
+aggregate filter on the number of holds per item because you must use an \r
+aggregate output type to count the holds.\r
+\r
--- /dev/null
+[[viewing_report_output]]\r
+Viewing Report Output\r
+---------------------\r
+\r
+indexterm:[reports, output]\r
+\r
+indexterm:[reports, output, tabular]\r
+\r
+indexterm:[reports, output, Excel]\r
+\r
+indexterm:[reports, output, spreadsheet]\r
+\r
+When a report runs Evergreen sends an email with a link to the output to the \r
+address defined in the report. Output is also stored in the specified Output \r
+folder and will remain there until manually deleted.\r
+\r
+. To view report output in the staff client, open the reports interface from \r
+_Admin (-) --> Local Administration --> Reports_\r
+. Click on Output to expand the folder. Select _Circulation_ (where you just \r
+saved the circulation report output).\r
++\r
+image::media/view-output-1.png[view-output-1]\r
++\r
+. View report output is the default selection in the dropdown menu. Select \r
+_Recurring Monthly Circ by Location_ by clicking the checkbox and click _Submit_.\r
++\r
+image::media/view-output-2.png[view-output-2]\r
++\r
+. A new tab will open for the report output. Select either _Tabular Output_ or \r
+_Excel Output_. If Bar Charts was selected during report definition the chart \r
+will also appear.\r
+. Tabular output looks like this:\r
++\r
+image::media/view-output-4.png[view-output-4]\r
++\r
+. If you want to manipulate, filter or graph this data, Excel output would be \r
+more useful. Excel output looks like this in Excel:\r
++\r
+image::media/view-output-5.png[view-output-5]\r
+\r
+\r
Learn how to create and use reports in Evergreen.
+include::reports/reporter_daemon.txt[]
+
+include::reports/reporter_folder.txt[]
+
+include::reports/reporter_create_templates.txt[]
+
+include::reports/reporter_generating_reports.txt[]
+
+include::reports/reporter_view_output.txt[]
+
+include::reports/reporter_cloning_shared_templates.txt[]
+
+include::reports/reporter_add_data_source.txt[]
+
+include::reports/running_recurring_reports.txt[]
+
+include::reports/reporter_template_termionology.txt[]
+
+include::reports/reporter_export_usingpgAdmin.txt[]
+
Using the Public Access Catalog
===============================
projects / evergreen / tadl.git / commitdiff