====== Create a New Report Source ======

If you have a need for data that can only be retrieved via a query because the reporter can't construct it, or if you base numerous reports on a specific set of data that you don't want to have to rebuild every time you create a template, you can create a new class in the fieldmapper that can be used by the reporter going forward.

First, you will need to construct a SQL query that retrieves the data you wish to make available in your source. Once you are satisfied, then you have two options:

===== Option 1: Create a (faux) View in the Fieldmapper Only =====

This option adds the SQL directly to the Fieldmapper. This is the easiest approach to code and the reporter (and most other parts of Evergreen) will be able to make use of it, but it does have limitations. For example, it will not be available to a direct database query. Also, other fieldmapper classes cannot link to this class as they would be able to with option 2. 

Tasks:
  * Create new fieldmapper class (this will include the SQL query)

Example Code: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/mccanna/newdevs-sample-create-view-via-fieldmapper


===== Option 2: Create a Database View =====

This option creates a view on the database side which is then referenced by the fieldmapper as if it were a normal table. There are a few more steps to this than there are to option 1, but it is more flexible as well.

Tasks:
  * Create new database view.
    * Decide whether this should be added to an existing schema or if a new schema should be created. (In this example, a new schema is created.)
    * Create or modify the appropriate schema file under Open-ILS/src/sql/Pg/ (this will be used by new Evergreen installations)
    * Create an upgrade script under Open-ILS/src/sql/Pg/upgrade/ (this will be used by Evergreen upgrades)
  * Create new fieldmapper class (this will reference the new view as if it were a table)

Example Code: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/mccanna/newdevs-sample-create-view-in-db 

===== Making This a Core Report Source =====

If unspecified, the new source will be listed alphabetically in the long list of "other" report sources. If you wish to bump it up to the list of "core" sources, add this to the class tag in the fieldmapper: 

<code>reporter:core="true"</code>

For example: 
<code><class id="auj" controller="open-ils.cstore open-oils.pcrud"
oils_obj:fieldmapper="actor::activejuv" reporter:core="true"
reporter:label="ILS User - Active Juvenile Accounts"></code>

===== More Information =====

  * [[newdevs:db:fm|Fieldmapper]]
  * [[http://evergreen-ils.org/~denials/workshop.html#_evergreen_data_models_and_access|Evergreen Data Models]]
  * [[https://www.postgresql.org/docs/current/sql-createview.html|PostgreSQL - Create View]]
  * [[https://www.tutorialspoint.com/postgresql/postgresql_select_query.htm|PostgreSQL - SELECT Query]]