<!-- 
/*
Copyright 2017 apHarmony

This file is part of jsHarmony.

jsHarmony is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jsHarmony is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this package.  If not, see <http://www.gnu.org/licenses/>.
*/
-->
<script type="text/x-tutorial-info">
{
  "ID": "model_actions",
  "Title": "Actions / Roles",
  "Menu": ["Models","Models Overview"]
}
</script>


<h3>Introduction</h3>
Permissions ensure that users can't access restricted data, and can only change data that they have access to in the system.<br/>
<br/>
The <b>"actions"</b> property defines whether the model can be used for <b>BIUD</b> - Browse, Insert, Update, or Delete.<br/>
<br/>
The <b>"roles"</b> property further restricts the capabilities of the model per user.

<h3>Actions / Roles Example</h3>
<pre>
{
  "table":"cust",
  "layout":"grid",
  "title":"All Customers",
  "caption":["Customer","Customers"],
  "actions":"BI",
  "roles": {
    "main": { "*":"B" },
    "client": { "C_B":"B","C_X":"*" },
  }
}
</pre>

<h3>Actions</h3>
The <b>"actions"</b> parameter defines what operations the model can perform.  Actions can be any combination of the following characters.
<ul>
  <li><b>B</b> - Browse</li>
  <li><b>I</b> - Insert</li>
  <li><b>U</b> - Update</li>
  <li><b>D</b> - Delete</li>
</ul>
<pre>
{
  "actions":"BIUD"
}
</pre>

<h4>Automatic model.actions</h4>
If model.actions is not defined, it will be defaulted based on the model layout and properties.<br/>
<br/>
If you come across a situation where the automatic action is incorrect, and could be improved by adjusting the default model.actions algorithm, please submit a suggested rule change via a support ticket on jsHarmony's GitHub page.

<h3>Roles</h3>
The <b>"roles"</b> parameter is used to restrict actions by user role and site.  Roles can be defined as follows:
<ul>
  <li><b>B</b> - Browse</li>
  <li><b>I</b> - Insert</li>
  <li><b>U</b> - Update</li>
  <li><b>D</b> - Delete</li>
  <li><b>*</b> - All roles - equivalent to BIUD</li>
</ul>
<pre>
{
  "roles":{
    "SITE1": { "ROLE":"PERM", "ROLE":"PERM" },
    "SITE2": { "ROLE":"PERM", "ROLE":"PERM" }
  }
}
</pre>
Alternatively, when roles are defined without the site, permissions are applied to the "main" site:
<pre>
{
  "roles":{ "ROLE":"PERM", "ROLE":"PERM" }
}
</pre>
The role ID can be set to "*" to signify all users in that site:
<pre>
{
  "roles":{ "*":"B" }
}
</pre>
By default, only the SYSADMIN and DEV roles have access to a model.  Permissions for users who are not SYSADMINs or DEVs must be explicity defined using the "role" parameter.<br/>
<br/>
In order for a model to be visible on a site, the model must have roles assigned for that site.  If a model definition has no roles defined, the model will only be accessible on the "main" site to SYSADMIN and DEV users.

<h4>Effective Permissions</h4>
Role permissions are added to each other, however they can never exceed the "actions" parameter.  For example:
<pre>
"actions":"BIU",
"roles":{ 
  "SYSADMIN":"*",
  "EDITOR":"BU",
  "READER":"B" 
}
</pre>
Will result in the following permissions:<br/>
 &nbsp; A user with only the "READER" role will have <b>"B"</b> access<br/>
 &nbsp; A user with "EDITOR" and "READER" roles will have <b>"BU"</b> access<br/>
 &nbsp; A user with "SYSADMIN", "EDITOR" and "READER" roles will have <b>"BIU"</b> access
