]> git.evergreen-ils.org Git - working/Evergreen.git/blob - docs/reports/reporter_create_templates.txt
Documentation: Migrate reports documentation from 2.1
[working/Evergreen.git] / docs / reports / reporter_create_templates.txt
1 [[reporter_creating_templates]]\r
2 Creating Templates\r
3 ------------------\r
4 \r
5 indexterm:[reports, creating templates]\r
6 \r
7 Once you have created a folder, the next step in building a report is to create \r
8 or clone a template. Templates allow you to run a report more than once without \r
9 building it anew every time, by changing definitions to suit current \r
10 requirements. For example, you can create a shared template that reports on \r
11 circulation at a given library. Then, other libraries can use your template and \r
12 simply select their own library when they run the report.\r
13 \r
14 It may take several tries to refine a report to give the output that you want. \r
15 It can be useful to plan out your report on paper before getting started with \r
16 the reporting tool. Group together related fields and try to identify the key \r
17 fields that will help you select the correct source.\r
18 \r
19 It may be useful to create complex queries in several steps. For example, first \r
20 add all fields from the table at the highest source level. Run a report and check \r
21 to see that you get results that seem reasonable. Then clone the report, add any \r
22 filters on fields at that level and run another report. Then drill down to the \r
23 next table and add any required fields. Run another report. Add any filters at \r
24 that level. Run another report. Continue until you’ve drilled down to all the \r
25 fields you need and added all the filters. This might seem time consuming and \r
26 you will end up cloning your initial report several times. However, it will help \r
27 you to check the correctness of your results, and will help to debug if you run \r
28 into problems because you will know exactly what changes caused the problem. \r
29 Also consider adding extra fields in the intermediate steps to help you check \r
30 your results for correctness.\r
31 \r
32 This example illustrates creating a template for circulation statistics. This is \r
33 an example of the most basic template that you can create. The steps required to \r
34 create a template are the same every time, but the tables chosen, how the data \r
35 is transformed and displayed, and the filters used will vary depending on your \r
36 needs.\r
37 \r
38 Choosing Report Fields\r
39 ~~~~~~~~~~~~~~~~~~~~~~\r
40 \r
41 indexterm:[reports, creating templates, choosing reports fields]\r
42 \r
43 . Click on the My Folder template folder where you want the template to be saved.\r
44 +\r
45 image::media/create-template-1.png[create-template-1]\r
46 +\r
47 . Click on Create a new Template for this folder.\r
48 +\r
49 image::media/create-template-2.png[create-template-2]\r
50 +\r
51 . You can now see the template creating interface. The upper half of the screen \r
52 is the _Database Source Browser_. The top left hand pane contains the database \r
53 _Sources_ drop-down list. This is the list of tables available as a starting point \r
54 for your report. Commonly used sources are _Circulation_ (for circ stats and \r
55 overdue reports), _ILS User_ (for patron reports), and _Item_ (for reports on a \r
56 library's holdings).\r
57 +\r
58 image::media/create-template-3.png[create-template-3]\r
59 +\r
60 The Enable source nullability checkbox below the sources list is for advanced \r
61 reporting and should be left unchecked by default.\r
62 +\r
63 . Select _Circulation_ in the _Sources_ dropdown menu. Note that the _Core \r
64 Sources_ for reporting are listed first, however it is possible to access all \r
65 available sources at the bottom of this dropdown menu. You may only specify one \r
66 source per template.\r
67 +\r
68 image::media/create-template-4.png[create-template-4]\r
69 +\r
70 . Click on _Circulation_ to retrieve all the field names in the Field Name pane. \r
71 Note that the _Source_ Specifier (above the middle and right panes) shows the \r
72 path that you took to get to the specific field.\r
73 +\r
74 image::media/create-template-5.png[create-template-5]\r
75 +\r
76 . Select _Circ ID_ in the middle _Field Name_ pane, and _Count Distinct_ from the \r
77 right _Field Transform_ pane. The _Field Transform_ pane is where you choose how \r
78 to manipulate the data from the selected fields. You are counting the number of \r
79 circulations.\r
80 +\r
81 indexterm:[reports, field transform]\r
82 +\r
83 image::media/create-template-6.png[create-template-6]\r
84 +\r
85 _Field Transforms_ have either an _Aggregate_ or _Non-Aggregate_ output type. \r
86 See the section called <<field_transforms,Field Transforms>> for more about \r
87 _Count, _Count Distinct_, and other transform options.\r
88 +\r
89 . Click _Add Selected Fields_ underneath the _Field Transform_ pane to add this \r
90 field to your report output. Note that _Circ ID_ now shows up in the bottom left \r
91 hand pane under the _Displayed Fields_ tab.\r
92 +\r
93 image::media/create-template-7.png[create-template-7]\r
94 +\r
95 . _Circ ID_ will be the column header in the report output. You can rename \r
96 default display names to something more meaningful. To do so in this example, \r
97 select the _Circ ID_ row and click _Alter Display Header_.\r
98 +\r
99 image::media/create-template-8.png[create-template-8]\r
100 +\r
101 Double-clicking on the displayed field name is a shortcut to altering the \r
102 display header.\r
103 +\r
104 . Type in the new column header name, for example _Circ count_ and click _OK_.\r
105 +\r
106 image::media/create-template-9.png[create-template-9]\r
107 +\r
108 . Add other data to your report by going back to the _Sources_ pane and selecting \r
109 the desired fields. In this example, we are going to add _Circulating Item --> \r
110 Shelving Location_ to further refine the circulation report.\r
111 +\r
112 In the top left hand _Sources_ pane, expand _Circulation_. Depending on your \r
113 computer you will either click on the _+_ sign or on an arrow to expand the tree.\r
114 +\r
115 image::media/create-template-10.png[create-template-10]\r
116 +\r
117 Click on the _+_ or arrow to expand _Circulating Item_. Select \r
118 _Shelving Location_.\r
119 +\r
120 image::media/create-template-11.png[create-template-11]\r
121 +\r
122 When you are creating a template take the shortest path to the field you need in \r
123 the left hand Sources pane. Sometimes it is possible to find the same field name \r
124 further in the file structure, but the shortest path is the most efficient.\r
125 +\r
126 In the Field Name pane select Name.\r
127 +\r
128 image::media/create-template-12.png[create-template-12]\r
129 +\r
130 In the upper right _Field Transform_ pane, select _Raw Data_ and click _Add Selected_ \r
131 Fields. Use _Raw Data_ when you do not wish to transform field data in any manner.\r
132 +\r
133 image::media/create-template-13.png[create-template-13]\r
134 +\r
135 Name will appear in the bottom left pane. Select the Name row and click _Alter \r
136 Display Header_.\r
137 +\r
138 image::media/create-template-15.png[create-template-15]\r
139 +\r
140 . Enter a new, more descriptive column header, for example, _Shelving location_. \r
141 Click _OK_.\r
142 +\r
143 image::media/create-template-16.png[create-template-16]\r
144 +\r
145 . Note that the order of rows (top to bottom) will correspond to the order of \r
146 columns (left to right) on the final report. Select _Shelving location_ and click \r
147 on _Move Up_ to move _Shelving location_ before _Circ count_.\r
148 +\r
149 image::media/create-template-17.png[create-template-17]\r
150 +\r
151 . Return to the _Sources_ pane to add more fields to your template. Under \r
152 _Sources_ click _Circulation_, then select _Check Out Date/Time_ from the middle \r
153 _Field Name_ pane.\r
154 +\r
155 image::media/create-template-19.png[create-template-19]\r
156 +\r
157 . Select _Year + Month_ in the right hand _Field Transform_ pane and click _Add \r
158 Selected Fields_\r
159 +\r
160 image::media/create-template-20.png[create-template-20]\r
161 +\r
162 . _Check Out Date/Time_ will appear in the _Displayed Fields_ pane. In the report \r
163 it will appear as a year and month _(YYYY-MM)_ corresponding to the selected tranform.\r
164 +\r
165 image::media/create-template-21.png[create-template-21]\r
166 +\r
167 . Select the _Check Out Date/Time_ row. Click _Alter Display Header_ and change \r
168 the column header to _Check out month_.\r
169 +\r
170 image::media/create-template-22.png[create-template-22]\r
171 +\r
172 . Move _Check out month_ to the top of the list using the _Move Up_ button, so \r
173 that it will be the first column in an MS Excel spreadsheet or in a chart. \r
174 Report output will sort by the first column.\r
175 \r
176 image::media/create-template-23.png[create-template-23]\r
177 \r
178 [NOTE]\r
179 ======\r
180 Note the _Change Transform_ button in the bottom left hand pane. It has the same \r
181 function as the upper right _Field Transform_ pane for fields that have already \r
182 been added.\r
183 \r
184 image::media/create-template-24.png[create-template-24]\r
185 ======\r
186 \r
187 \r
188 Applying Filters\r
189 ~~~~~~~~~~~~~~~~\r
190 \r
191 indexterm:[reports, applying filters]\r
192 \r
193 Evergreen reports access the entire database, so to limit report output to a \r
194 single library or library system you need to apply filters.\r
195 \r
196 After following the steps in the previous section you will see three fields in \r
197 the bottom left hand _Template Configuration_ pane. There are three tabs in this \r
198 pane: _Displayed Fields_ (covered in the previous section), _Base Filters_ and \r
199 _Aggregate Filters_. A filter allows you to return only the results that meet \r
200 the criteria you set.\r
201 \r
202 indexterm:[reports, applying filters, base filter]\r
203 \r
204 indexterm:[reports, applying filters, aggregate filters]\r
205 \r
206 _Base Filters_ apply to non-aggregate output types, while _Aggregate Filters_ are \r
207 used for aggregate types. In most reports you will be using the _Base Filters_ tab. \r
208 For more information on aggregate and non-aggregate types see the section called \r
209 “Field Transforms”.\r
210 \r
211 There are many available operators when using filters. Some examples are _Equals_, \r
212 _In list_, is _NULL_, _Between_, _Greater than_ or _equal to_, and so on. _In list_ \r
213 is the most flexible operator, and in this case will allow you flexibility when \r
214 running a report from this template. For example, it would be possible to run a \r
215 report on a list of timestamps (in this case will be trimmed to year and month \r
216 only), run a report on a single month, or run a report comparing two months. It \r
217 is also possible to set up recurring reports to run at the end of each month.\r
218 \r
219 In this example we are going to use a Base Filter to filter out one library’s \r
220 circulations for a specified time frame. The time frame in the template will be \r
221 configured so that you can change it each time you run the report.\r
222 \r
223 Using Base Filters\r
224 ^^^^^^^^^^^^^^^^^^\r
225 \r
226 indexterm:[reports, applying filters, base filter]\r
227 \r
228 . Select the _Base Filters_ tab in the bottom _Template Configuration_ pane.\r
229 \r
230 . For this circulation statistics example, select _Circulation --> Check Out \r
231 Date/Time --> Year + Month_ and click on _Add Selected Fields_. You are going to \r
232 filter on the time period.\r
233 +\r
234 image::media/create-template-25.png[create-template-25]\r
235 +\r
236 . Select _Check Out Date/Time_. Click on _Change Operator_ and select _In list_ \r
237 from the dropdown menu. \r
238 +\r
239 image::media/create-template-26.png[create-template-26]\r
240 +\r
241 . To filter on the location of the circulation select \r
242 _Circulation --> Circulating library --> Raw Data_ and click on _Add Selected Fields_.\r
243 +\r
244 image::media/create-template-27.png[create-template-276]\r
245 +\r
246 . Select _Circulating Library_ and click on _Change Operator_ and select _Equals_. \r
247 Note that this is a template, so the value for _Equals_ will be filled out when \r
248 you run the report.\r
249 +\r
250 image::media/create-template-28.png[create-template-28]\r
251 +\r
252 For multi-branch libraries, you would select _Circulating Library_ with _In list_ \r
253 as the operator, so you could specify the branch(es) when you run the report. This \r
254 leaves the template configurable to current requirements. In comparison, sometimes \r
255 you will want to hardcode true/false values into a template. For example, deleted \r
256 bibliographic records remain in the database, so perhaps you want to hardcode \r
257 _deleted=false_, so that deleted records don’t show up in the results. You might \r
258 want to use _deleted=true_, for a template for a report on deleted items in the \r
259 last month.\r
260 +\r
261 . Once you have configured your template, you must name and save it. Name this \r
262 template _Circulations by month for one library_. You can also add a description. \r
263 In this example, the title is descriptive enough, so a description is not necessary. \r
264 Click _Save_.\r
265 +\r
266 image::media/create-template-29.png[create-template-29]\r
267 +\r
268 . Click _OK_.\r
269 +\r
270 image::media/create-template-30.png[create-template-30]\r
271 +\r
272 . You will get a confirmation dialogue box that the template was successfully \r
273 saved. Click OK.\r
274 +\r
275 image::media/create-template-31.png[create-template-31]\r
276 +\r
277 After saving it is not possible to edit a template. To make changes you will \r
278 need to clone it and edit the clone\r
279 \r
280 [NOTE]\r
281 ==========\r
282 The bottom right hand pane is also a source specifier. By selecting one of these \r
283 rows you will limit the fields that are visible to the sources you have specified. \r
284 This may be helpful when reviewing templates with many fields. Use *Ctrl+Click* to \r
285 select or deselect items.\r
286 \r
287 image::media/create-template-32.png[create-template-32]\r
288 ==========\r
289 \r
290 \r
291 \r