orm_doc.js

@json

An ORM is an Object Relational Mapping that defines the relationship between object oriented type
definitions and relational tables or views in a database. This implementation is currently designed
to apply specifically to a PostgreSQL database, but theoretically could be applied to any database
for which an ORM API is defined to process these definitions.

In the xTuple PostgreSQL implmentation the installation of ORM files triggers views to be created
whose structures and rules conform to the definition of the ORM. The ORMs use camel and class case
conventions when referencing object attributes and snake case conventions when referencing database
attributes. Because ORMs generates views, these views can in turn be referenced by other ORMs to manage
a class hierachy. To determine the name of a view created by an ORM simply convert the name space
qualified type of the object to a snake case schema and view name like so:

Object Name Datbase Name
-------------- ----------------
XM.Contact xm.contact
XM.ToDo xm.to_do
XM.ToDoComment xm.to_do_comment

ORMs are specifically designed to be extensible so that a database table can be virtually expanded
without changing the original table definition, while presenting the new data through the ORM API
as though it were all one unit. This effectively ensures that "core" database definitions
and custom or 3rd party data extensions are effectively encapuslated from one another. In addition
ORMs can be activated and deactivated in the xt.orm table so extensions can be "turned off" at
any time.

The initial ORM is referred to as the "base" ORM. Additional ORMs can be defined against the
original base using the same name space and type but giving them a different context name and
setting the isExtension flag to true. Typically the table on an ORM extension should reside in a
different database schema where you would create a table with colums that contain data you want to
"add" to a table in the original schema. The new table should contain a column relation to associate
with the original (which may also be the primary key for it as well.) When you create an ORM
extension the new table will be left joined on the original. Any inserts, updates or delete
actions will propagate results to both the original and the new table automatically.

Extensions can be created as both completely independent ORM definitions or added to an
extension array on a base or extension ORM.

{

A container identifier that correlates with an object name space.

Required.

"nameSpace": "XM",

A specific type name that correlates with an object type.

Required.

"type": "ProjectTask",

Context is a sub container for name space that allows extending the same
name space and type in different contexts. The name space, type and context
must be unique. When you extend an ORM outside the original definition, you
should create a new context for each extension.

Required.

"context": "xtuple",

The source table or view from which you are drawing data. Schema qualifications
should be included when referencing views created by other ORMs. Only one table
may be defined per root ORM. Use extensions to relate additional tables.

Required.

"table": "prjtask",

Table name that specifies which table controls the versioning information
for records. If not specified, table will be the versioned table.
Useful if the table property actually references a view that can not, by
definition, be version controlled.

Optional.

"lockTable": "prjtask",

Indicates this ORM is an extension to another ORM. A join will be created between
the two tables to represent them as one in the corresponding view.

"isExtension": false,

This value only applies to extensions and indicates the query should perform a join
instead of a left join to improve performance. It should only be used in cases where
a related record on the extension's table is always guaranteed to exist.

"isChild": false,

The table sequence to use when generating the next unique record id. Necessary
for any objects for which new records can be created.

"idSequenceName": "prjtask_prjtask_id_seq",

Text describing the purpose of the ORM which will be appended to the associated
view.

"comment": "Project Task Map",

Designates that data for this type can only be accessed in the context of a parent. Any attempts
by a client to query or update this record directly, regardless of privilege settings, will fail.

"isNestedOnly": false,

Used to describe document access. If absent no access will be granted to this type.

Required.

"privileges": {

Describes privileges that allow a user to have access to all records of this
object type. The same privilege can be set to control multiple or all of the create, read,
update and delete (aka. crud) access methods. Privilege settings can be a boolean that indicates
universal access or lack thereof, or a string that refereces a specific privilege name that
allows access if the user has been granted the privilege.

Required.

"all": {

The create privilege for this object.

@type {String}

"create": "MaintainAllProjects",

The read privilege for this object.

@type {String}

"read": "ViewAllProjects",

The update privilege for this object. This
privilege also implicitly enables read access if
the privilege for read is not explicitly granted.

@type {String}

"update": "MaintainAllProjects",

The delete privilege for this object.

 @type {String}

"delete": "MaintainAllProjects"
},

Describes privileges that allow a user to have access only to specific records
of this object type as defined by a specific relationship between the user and the
record as determined by matching logged in user account name to the value of the
fields listed in the "properties" array.

"personal": {

The personal create privilege for this object.

@type {String}

"create": "MaintainPersonalProjects",

The personal read privilege for this object.

@type {String}

"read": "ViewPersonalProjects",

The personal update privilege for this object. This privilege also implicitly
enables read access if the privilege for read is not explicitly granted.

@type {String}

"update": "MaintainPersonalProjects",

The personal delete privilege for this object.

@type {String}

"delete": "MaintainPersonalProjects",

An array properties on the object on which to compare the logged in user
account name to determine access.

@type {Array}

"properties": [
    "owner",
    "assignedTo",
    "projectOwner",
    "projectAssignedTo"
   ]
},

Attribute level privileges. Each attribute that has privilege control should be listed
as a key/value pair where the key is a properties attribute name and the value is an object
that contains one or both of its own key/value pairs whose keys would either be view or edit.
The value in these pairs is a string with one or more space separated privilege listings.

"attribute": {
  "owner": {
    "edit": "editOwner"
  },
  "cost": {
    "view": "viewCosts maintainCosts"
  }
}
},

The array of client object properties that maps to table columns. Each hash listed
should have one and only one of the following properties: attr, toOne or toMany,
the purposes of which are described below.

Required.

"properties": [
{

The property name.

Required.

@type {String}

"name": "task",

Indicates this property is an attribute that maps directly to table column.

@type {Hash}

"attr": {

The expected type of the property. Should be any of the following:
String
Date
DueDate
EffectiveDate
ExpireDate
Boolean
Hours
Number
Money
Cost
SalesPrice
PurchasePrice
ExtendedPrice
Weight
Percent
Phone
Email
Url

@type {String}

"type": "Number",

The mapped database column associated with this property.

There is support for a special case where if the column name is obj_uuid and
it is not found to exist on the table, the ORM generator will add the column
with type uuid that generates it's own default value. This is usefull for adding
a naturalKey to a table that is normally a child table and doesn't have one good
attribute to serve as the natural key.

@type {String}

"column": "prjtask_id",

Indicates this column is the relation to be used qualifying updates and deletions
internally.

The current implementation requires one and only one property to be defined as
the primary key per map.

@type {Boolean}
@default false

"isPrimaryKey": true,

Indicates this column is the relation to be used qualifying updates and deletions
externally. This key will appear as the value on non-nested toOne relations.

@type {Boolean}
@default false

"isNaturalKey": true,

Use to indicate a mandatory property.

"isRequired": true,

Indicates a fixed value on which to filter all table reads and set as default on
new inserts. It can not be updated.

Useful for tables that store data of mixed types where one column holds
a source code string that designates the type as part of compound key. It forces
queries to return and affect only records with values that match the one
defined here.

@type {Any}
@default false

"value": "TA",

Flags whether the proprety should be visible on query results or not.

Useful when used in conjunction with "value" where there is no need to see the
fixed value in a result set.

@type {Boolean}
@default {true}

"isVisible": false,

Flags whether the property must be encrypted. When true, the data source must pass
an encryption key in with the payload to encrypte the data. If one is not found
the commit will fail.

@type {Boolean}
@default {true}

"isEncrypted": false

},

Indicates this property will return the entire row to which this column is related.

"toOne": {

The non-name space qualified type name of the object to which this property is
related. This ORM will be dependent on the definition of this object already existing
and will not install unless it does.

Required.

"type": "UserAccountInfo",

If true the returned value will contain the complete row for each matching record, otherwise
the value will return exactly like a regular attribute.

@type {Boolean}
@default false

"isNested": true,

The table column to map to. It should be a foreign key relation to the corresponding type.

Required.

@type {String}

"column": "prjtask_username",

The property relation of the type on which to join. Will accept camel case or snake case
mappings, but camel case is recommended.

Required.

@type {String}
@default guid

"inverse": "username",

If true a join will be performed on the table instead of a left join to improve performance.
This should only be done if this property is required and is always guaranteed to have
a value.

@type {Boolean}
@default false

"isChild": false,

A value to substitute if the client returns a null value.

@type {Boolean}
@default false

"nullValue": -1
},

Indicates this property will return an array of all records to which it is related.

"toMany": {

The type name of the objects to be included. Type name should be class case and not include
a name space qualification.

Note that the toMany relationship will be dependent on an ORM of this type in a matching
name space already existing. If it does not installation will fail.

Required.

@type {String}

"type": "ProjectTaskComment",

The table column to map to. If not specified all rows for the type will be returned.

@type {String}

"column": "prjtask_id",

The key that is the relation to the column. Ignored if no column specified.

@type {String}

"inverse": "project_task",

Indicate column is on the base table. Useful for extensions where a toMany relationship is keyed off the base table but the extension refers to another extending table.

@type {Boolean}

"isBase": false,

If true the returned array will contain the complete row for each matching record, otherwise
the array will contain only primary keys for matching records.

Nested records will be automatically deleted when the parent is deleted so long as their edit
rules allow it. See deleteDelegate for situations where the rules are in conflict.

@see deletDelegate
@type {Boolean}
@default false

"isNested": true
}
}
],

The extensions array allows you to define addtional tables on which to join to the table
of this ORM. The following keys apply to extensions in the exact same manner as the root
definition:

table
isChild
properties
order

Note that the name space should not be included in extension arrays. It will be assumed
to be the root name space. The isExension property will automatically be true on values
listed in the extensions array.

"extensions": [],

Indicates the ORM has been created as part of an extension package. Helps to differentiate
standard from custom ORMs created by users for local implementations.

"isSystem": false,

Dictates the sequence that extensions are processed in. Higher sequences will add columns to the
furthermost right of the ORM views.

"sequence": 0

}
Generated with dox-docco