Evergreen DokuWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**New Developers Working Group**
====== The Fieldmapper ======

The fieldmapper (''fm_IDL.xml'') maps the fields! It defines objects’ fields, linked fields from other objects, and permissions needed to access various things. Most of the Evergreen code (including the reports engine) accesses the database content via the fieldmapper rather than accessing the database directly.

  * [[https://git.evergreen-ils.org/?p=Evergreen.git;a=blob;f=Open-ILS/examples/fm_IDL.xml;h=a4fb45b078c1f80ccfdcb82d9bc2a8ee40fc749a;hb=HEAD|fm_IDL.xml in Evergreen git repository]]

The fieldmapper is installed in two locations on your server: 
  * /openils/conf/fm_IDL.xml
  * /openils/var/web/reports/fm_IDL.xml

To view the current fieldmapper on your own site through a browser: 

  * <nowiki>https://[your domain].org/reports/fm_IDL.xml</nowiki>

Outline of fieldmapper classes:

  * [[evergreen-user:reporting_data_dictionary|Reporting data dictionary]]


===== Things to Add to This Page: =====
  * Information about the main fieldmapper classes
  * Example of how to navigate the fieldmapper
  * Relationship of the fieldmapper to reports 
  * Relationship of the fieldmapper to the PostgreSQL database schemas


===== Parts of the Fieldmapper =====
==== class header ====

=== class ===

This is the shortened term to describe this set of information. If your class will be accessible to pcrud, this is the term you'll use to reference this class in other places in the code.

=== controller ===

There are multiple values possible for this field. They include:
  * open-ils.cstore
  * open-ils.pcrud
  * open-ils.reporter-store

=== oils_obj:fieldmapper ===

=== oils_persist:cardinality ===

This is an estimate of how many records are expected in this class.  This is used by the UI in some cases to determine whether or not it's reasonable to pre-fetch all the records of this class.  There are three possible values:

  * low (less than 100 records)
  * high (100-1000 records)
  * unbounded (more than 1000 records)

=== oils_persist:tablename ===

=== oils_persist:virtual ===

This essentially means that the class or field is not "real" in the actual database table, only in the context of the IDL. It is often used for links to other classes: 

<code><field reporter:label="Hours of Operation" name="hours_of_operation"
 oils_persist:virtual="true" reporter:datatype="link"/></code>

It can also be used to indicate such things as a view that is defined by SQL in the IDL rather than in the database.
=== oils_persist:readonly ===

=== reporter:core ===
If set to true, this view will show up in the list of core report sources.

Only use this if the value is true. It should be written as <code>reporter:core="true"</code>
=== reporter:label ===
This will be the name of your view in list of available report sources in the reporter, so it should be in readable language.


==== fields ====
=== oils_persist:primary ===

=== oils_persist:sequence ===

=== field reporter:label ===

=== name ===

=== reporter:datatype ===
  * bool - true/false
  * text
  * int - a whole number
  * float - a decimal number
  * link - a reference to a different class.
  * id - a whole number. This class's links are other class's ids.
  * money - an amount of money
  * org_unit - a library/sublibrary etc.
  * interval - an amount of time shown as a number followed by a letter for the unit e.g. 20h for 20 hours or 7d for seven days
  * timestamp - an unchanging point in time
==== links ====
=== link field ===

=== reltype ===
These distinctions are to indicate key directionality. They are not to indicate nullability.

  * has_a 
  * has_many
  * might_have

=== key ===

=== map ===

=== class ===

==== permacrud ====
If you specified **open-ils.pcrud** in the controller, you need to have a section for permacrud. If you did __not__ specify **open-ils.pcrud** in the controller, do not include this section.

This section specifies whether users should have the ability to create, update, delete, or only retrieve data from this class and its associated table (if applicable).

=== permacrud xmlns ===
<code><permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"></code>
This should be the opening tag for your permacrud area.

=== actions ===
== options ==

  * **create** - Must correspond to a permission
  * **retrieve** - Can be used alone without the other create/update/delete actions. Can be used without a specific permission, if appropriate for how the class is to be used
  * **update** - Must correspond to a permission
  * **delete** - Must correspond to a permission

If using the create/update/delete actions, the class must also be mapped to an **[[newdevs:db:fm#oils_persist:tablename|oils_persist:tablename]].**

If you specify a permission, you must also include a ''global_required'' or ''context_field'' attribute or a ''context'' element.  Otherwise, you will get the error message "Invalid object or insufficient permissions".

== context_field == 

== context link ==

== field ==

== global_required ==

== owning_user ==