Docs: Fixing broken link
[Evergreen.git] / docs / reports / reporter_add_data_source.adoc
1 Adding Data Sources to Reporter
2 -------------------------------
3
4 indexterm:[reports, adding data sources]
5
6 You can further customize your Evergreen reporting environment by adding 
7 additional data sources.
8
9 The Evergreen reporter module does not build and execute SQL queries directly, 
10 but instead uses a data abstraction layer called *Fieldmapper* to mediate queries 
11 on the Evergreen database.Fieldmapper is also used by other core Evergreen DAO 
12 services, including cstore and permacrud. The configuration file _fm_IDL.xml_ 
13 contains the mapping between _Fieldmapper_ class definitions and the database. 
14 The _fm_IDL.xml_ file is located in the _/openils/conf_ directory.
15
16 indexterm:[fm_IDL.xml]
17
18 There are 3 basic steps to adding a new data source. Each step will be discussed 
19 in more detail in the
20
21 . Create a PostgreSQL query, view, or table that will provide the data for your 
22 data source.
23 . Add a new class to _fm_IDL.xml_ for your data source.
24 . Restart the affected services to see the new data source in Reporter.
25
26 There are two possible sources for new data sources:
27
28 indexterm:[PostgreSQL]
29
30 indexterm:[SQL]
31
32 * An SQL query built directly into the class definition in _fm_IDL.xml_. You can 
33 use this method if you are only going to access this data source through the 
34 Evergreen reporter and/or cstore code that you write.
35 * A new table or view in the Evergreen PostgreSQL database on which a class 
36 definition in _fm_IDL.xml_. You can use this method if you want to be able to 
37 access this data source through directly through SQL or using other reporting tool.
38
39 Create a PostgreSQL query, view, or table for your data source
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41
42 indexterm:[PostgreSQL]
43
44 You need to decide whether you will create your data source as a query, a view, 
45 or a table.
46
47 . Create a query if you are planning to access this data source only through the 
48 Evergreen reporter and/or cstore code that you write. You will use this query to 
49 create an IDL only view.
50 . Create a view if you are planning to access this data source through other 
51 methods in addition to the Evergreen reporter, or if you may need to do 
52 performance tuning to optimize your query.
53 . You may also need to use an additional table as part of your data source if 
54 you have additional data that's not included in the base Evergreen, or if you 
55 need to use a table to store the results of a query for performance reasons.
56
57 To develop and test queries, views, and tables, you will need
58
59 * Access to the Evergreen PostgreSQL database at the command line. This is 
60 normally the psql application. You 
61 can access the Postgres documentation at the 
62 https://www.postgresql.org/docs/[Official Postgres documentation] for 
63 more information about PostgreSQL.
64 * Knowledge of the Evergreen database structure for the data that you want to 
65 access. You can find this information by looking at the Evergreen schema
66 http://docs.evergreen-ils.org/2.2/schema/[Evergreen schema] 
67
68 indexterm:[database schema]
69
70 If the views that you are creating are purely local in usage and are not intended 
71 for contribution to the core Evergreen code, create the Views and Tables in the 
72 extend_reporter schema. This schema is intended to be used for local 
73 customizations and will not be modified during upgrades to the Evergreen system.
74
75 You should make sure that you have an appropriate version control process for the SQL 
76 used to create your data sources.
77
78 Here's an example of a view created to incorporate some locally defined user 
79 statistical categories:
80
81 .example view for reports
82 ----------
83 create view extend_reporter.patronstats as
84 select u.id, 
85 grp.name as "ptype",
86 rl.stat_cat_entry as "reg_lib",
87 gr.stat_cat_entry as "gender",
88 ag.stat_cat_entry as "age_group",
89 EXTRACT(YEAR FROM age(u.dob)) as "age",
90 hl.id as "home_lib",
91 u.create_date,
92 u.expire_date,
93 ms_balance_owed
94 from actor.usr u
95 join permission.grp_tree grp 
96     on (u.profile = grp.id and (grp.parent = 2 or grp.name = 'patron')) 
97 join actor.org_unit hl on (u.home_ou = hl.id)
98 left join money.open_usr_summary ms 
99     on (ms.usr = u.id) 
100 left join actor.stat_cat_entry_usr_map rl 
101     on (u.id = rl.target_usr and rl.stat_cat = 4) 
102 left join actor.stat_cat_entry_usr_map bt 
103     on (u.id = bt.target_usr and bt.stat_cat = 3) 
104 left join actor.stat_cat_entry_usr_map gr 
105     on (u.id = gr.target_usr and gr.stat_cat = 2) 
106 left join actor.stat_cat_entry_usr_map gr 
107     on (u.id = gr.target_usr and gr.stat_cat = 2) 
108 left join actor.stat_cat_entry_usr_map ag 
109     on (u.id = ag.target_usr and ag.stat_cat = 1) 
110 where u.active = 't' and u.deleted <> 't';
111 -----------
112
113 Add a new class to fm_IDL.xml for your data source
114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116 Once you have your data source, the next step is to add that data source as a 
117 new class in _fm_IDL.xml_.
118
119 indexterm:[fm_IDL.xml]
120 indexterm:[fieldmapper]
121 indexterm:[report sources]
122
123 You will need to add the following attributes for the class definition:
124
125 * *id*. You should follow a consistent naming convention for your class names 
126 that won't create conflicts in the future with any standard classes added in 
127 future upgrades. Evergreen normally names each class with the first letter of 
128 each word in the schema and table names. You may want to add a local prefix or 
129 suffix to your local class names.
130 * *controller=”open-ils.cstore”*
131 * *oils_obj:fieldmapper=”extend_reporter::long_name_of_view”*
132 * *oils_persist.readonly=”true”*
133 * *reporter:core=”true”* (if you want this to show up as a “core” reporting source)
134 * *reporter:label*. This is the name that will appear on the data source list in 
135 the Evergreen reporter.
136 * *oils_persist:source_definition*. If this is an IDL-only view, add the SQL query 
137 here. You don't need this attribute if your class is based on a PostgreSQL view 
138 or table.
139 * *oils_persist:tablename="schemaname.viewname or tablename"* If this class is 
140 based on a PostgreSQL view or table, add the table name here. You don't need 
141 this attribute is your class is an IDL-only view.
142
143 For each column in the view or query output, add field element and set the 
144 following attributes. The fields should be wrapped with _<field> </field>_:
145
146 * *reporter:label*. This is the name that appears in the Evergreen reporter.
147 * *name*. This should match the column name in the view or query output.
148 * *reporter:datatype* (which can be id, bool, money, org_unit, int, number, 
149 interval, float, text, timestamp, or link)
150
151 For each linking field, add a link element with the following attributes. The 
152 elements should be wrapped with _<link> </link>_:
153
154 * *field* (should match field.name)
155 * *reltype* (“has_a”, “might_have”, or “has_many”)
156 * *map* (“”)
157 * *key* (name of the linking field in the foreign table)
158 * *class* (ID of the IDL class of the table that is to be linked to)
159
160 The following example is a class definition for the example view that was created 
161 in the previous section.
162
163 .example class definition for reports
164 ----------
165 <class id="erpstats" controller="open-ils.reporter-store" 
166 oils_obj:fieldmapper="extend_reporter::patronstats" 
167 oils_persist:tablename="extend_reporter.patronstats" oils_persist:readonly="true" 
168 reporter:label="Patron Statistics" reporter:core="true">
169   <fields oils_persist:primary="id">
170   <field reporter:label="Patron ID" name="id" reporter:datatype="link" />
171   <field reporter:label="Patron Type" name="ptype" reporter:datatype="text" />
172   <field reporter:label="Reg Lib" name="reg_lib" reporter:datatype="text" />
173   <field reporter:label="Boro/Twp" name="boro_twp" reporter:datatype="text" />
174   <field reporter:label="Gender" name="gender" reporter:datatype="text" />
175   <field reporter:label="Age Group" name="age_group" reporter:datatype="text" />
176   <field reporter:label="Age" name="age" reporter:datatype="int" />
177   <field reporter:label="Home Lib ID" name="home_lib_id" 
178     reporter:datatype="link" />
179   <field reporter:label="Home Lib Code" name="home_lib_code" 
180     reporter:datatype="text" />
181   <field reporter:label="Home Lib" name="home_lib" reporter:datatype="text" />
182   <field reporter:label="Create Date" name="create_date" 
183     reporter:datatype="timestamp" />
184   <field reporter:label="Expire Date" name="expire_date" 
185     reporter:datatype="timestamp" />
186   <field reporter:label="Balance Owed" name="balance_owed" 
187     reporter:datatype="money" />
188 </fields>
189 <links>
190   <link field="id" reltype="has_a" key="id" map="" class="au"/>
191   <link field="home_lib_id" reltype="has_a" key="id" map="" class="aou"/>
192 </links>
193 </class>
194 ---------
195
196 NOTE: _fm_IDL.xml_ is used by other core Evergreen DAO services, including cstore 
197 and permacrud. So changes to this file can affect the entire Evergreen 
198 application, not just reporter. After making changes fm_IDL.xml, it is a good 
199 idea to ensure that it is valid XML by using a utility such as *xmllint* – a 
200 syntax error can render much of Evergreen nonfunctional. Set up a good change 
201 control system for any changes to fm_IDL.xml. You will need to keep a separate 
202 copy of you local class definitions so that you can reapply the changes to 
203 _fm_IDL.xml_ after Evergreen upgrades.
204
205 Restart the affected services to see the new data source in the reporter
206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207
208 The following steps are needed to for Evergreen to recognize the changes to 
209 _fm_IDL.xml_
210
211 . Copy the updated _fm_IDL.xml_ into place:
212 +
213 -------------
214 cp fm_IDL.xml /openils/conf/.
215 -------------
216 +
217 . (Optional) Make the reporter version of fm_IDL.xml match the core version.
218 Evergreen systems supporting only one interface language will normally find
219 that _/openils/var/web/reports/fm_IDL.xml_ is a symbolic link pointing to
220 _/openils/conf/fm_IDL.xml_, so no action will be required. However, systems
221 supporting multiple interfaces will have a different version of _fm_IDL.xml_ in
222 the _/openils/var/web/reports_ directory. The _right_ way to update this is to
223 go through the Evergreen internationalization build process to create the
224 entity form of _fm_IDL.xml_ and the updated _fm_IDL.dtd_ files for each
225 supported language. However, that is outside the scope of this document. If you
226 can accept the reporter interface supporting only one language, then you can
227 simply copy your updated version of _fm_IDL.xml_ into the
228 _/openils/var/web/reports_ directory:
229 +
230 -------------
231 cp /openils/conf/fm_IDL.xml /openils/var/web/reports/.
232 -------------
233 +
234 . As the *opensrf* user, run Autogen to to update the Javascript versions of
235 the fieldmapper definitions.
236 +
237 -------------
238 /openils/bin/autogen.sh
239 -------------
240 +    
241 . As the *opensrf* user, restart services:
242 +
243 -------------
244 osrf_control --localhost --restart-services
245 -------------
246 +
247 . As the *root* user, restart the Apache web server:
248 +
249 -------------
250 service apache2 restart
251 -------------
252 +
253 . As the *opensrf* user, restart the Evergreen reporter. You may need to modify
254 this command depending on your system configuration and PID path:
255 +
256 ------------
257 opensrf-perl.pl -l -action restart -service open-ils.reporter \
258 -config /openils/conf/opensrf_core.xml -pid-dir /openils/var/run
259 ------------
260 +
261 . Restart the Evergreen staff client, or use *Admin --> For Developers -->
262   Clear Cache*
263