Setting Access

We have created some tables in the "Access Model", but we didn't restrict any access yet, meaning, that everybody can read and write data, add and delete records and export data.
In this chapter we will use the "Access Model" to apply a couple of restrictions.

Permissions And Process Types

The "Process Types" stand for the activities read data, write data, export date, see data history, add records, delete records and search for records. For each process type a permission can be defined. Open "Clients" node in the "Access Model". Right click on Permits and select "Add Permit". Open the "Permits/Permit 1/Permissions" node.
You get a list with the 7 process types:

• Read
  Values with read permission are displayed in the client dialog. Values without read permission are still loaded and available for validation and writing, by validations or other custom code. These values can also be included in exports.
• Write
  Values with read and write permission are displayed in editable controls. Of course a value, that has write permission only, but no read permission, can't be edited in an employ dialog. In this case the write permission setting can still be used by custom code, to decide to change a value or not.
• Export
  Values with export permission are included in exports.
• History
  If WriteHistory for a DataNode is checked, each field control can offer a small history dialog, showing value changes. For values with history permission this dialog can be opened.
• Add
  Add permission is needed to add records.
  NOTE: As you always add a whole record, this permission type is not defined for AccessField.
• Delete
  Delete permission is needed to delete records.
  NOTE: As you always delete a whole record, this permission type is not defined for AccessField.
• Search
  Search permission is needed to search for records.
  Without search permission you can still add new records or open records by custom code.
  NOTE: The search permission applies to AccessModelNode only.

NOTE: The behaviors described, refer to the standard "Tree Employ Component".
For custom components or code, it is up to the developer, if and how to apply the permission settings.

Setting Permissions

Permissions settings are inherited from parent items. The root element of this permission tree is the "Access Model".

Permission settings for "Access Model":

• Yes
  The permission is granted (default setting).
• No
  The permission is not granted.
• Roles
  By default the permission is granted, if user roles match at least one of the PermissionRoles, otherwise the permission is not granted.
  Uncheck PermissionOnRoleMatch to reverse this rule.

While the "Access Model" forces you to grant a permission or not, all child items (access nodes and fields) have the option to set the permission to None (default setting). Also default setting and options for Roles permissions are different.

Permission settings for AccessNode and AccessField:

• None
  The permission is inherited from parent item (default setting).
• Yes
  The permission is granted.
• No
  The permission is not granted.
• Roles
  If user roles match at least one of the PermissionRoles, PermissionTypeOnRoleMatch, otherwise PermissionTypeOnNoRoleMatch is applied.
  The values of PermissionTypeOnRoleMatch and PermissionTypeOnNoRoleMatch again can be Yes, No or None.

If the permission of an parent item is also None, the parent item will again check its parent item for an permission, going up the tree until a permission different than None is found.
Since the default settings of all access nodes and fields are None, by default the permissions defined in the "Access Model" are applied for all items.
So before you start to set permissions, you should decide, with which "Access Model" permission setting you want to start.

Conditions And Exclude Settings

For each permit, it can be defined, when this permit is applied and when not. This is done with conditions and exclude settings. While conditions define data specific rules (e.g. don't edit sales with a certain product), exclude settings refer on the status of the record (e.g. new record). With the option to define multiple permits, it gives you a very flexible way to set permissions. Also it is possible to use customized conditions.

To create the condition do the following steps:

• Create a field "BranchOffice" in the "Data Model" "Clients" node.
• Go back to the conditions, right click and select "Add Condition".
• Open the conditions and select "Undefined Condition".
• Select "..." in the ParameterDataField property.
• Choose the "Clients/BranchOffice" field from the selection dialog.
• Set the "Value" property to "MyOffice".

The permit and its conditions are only applied to clients with "Client.BranchOffice = 'MyOffice'".

Exclude settings are just a special types of conditions. So if we talk about conditions it usually means the exclude settings as well.

The following exclude settings are defined:

• "ExcludeNewRecords" (Permit does not apply to new created records)
• "ExcludeExistingRecords" (Permit does not apply to existing records)
• "ExcludeCurrentUserEditedRecords" (Permit does not apply to records last edited by current user)
• "ExcludeOtherUserEditedRecords" (Permit does not apply to records last edited by other than current user)

Permits are only applied, if all conditions are met.
By adding multiple permits with different conditions, you can separate records into groups, and define different permissions for each group.

If multiple permits are created for an access field or node, a record might meet the conditions of more than one permit. So more that one permit would apply to this record.
In this case, the first permit (in the order they appear in the Application Model), that meets the conditions, and that has a permission setting different than None, is applied.

The Permission Tree

The PermissionTree properties help you to find the place, where the permissions are defined, if permissions are inherited from parent items. Due to Conditions and Roles permissions, a parent item might return a permission on runtime or not.
For this reason, every PermissionTree property shows a list of permissions, until a permission is found, that will always return a "Yes" or "No".

As an example we look at the field "Amount" of the "Sales" node which is a child node of "Clients".

We have created the following permits to set the "Write" permission:

• "Amount" field:
  Permission: Yes
  Condition: ExcludeExistingRecords = Yes
  
• "Sales" node:
  Permission: Roles (1 Role Selected)
  Condition: Client.BranchOffice = 'MyTown'
  
• "Clients" node:
  Permission: Roles (1 Role Selected)
  PermissionTypeOnNoRoleMatch: None

For the "Amount" field you would see the following information in PermissionTree:

Access Permission

The "Access Permission" allows you to exclude access nodes and fields completely from the access model at runtime.
Excluded items are ignored by M4 Back Office. Nothing is added to an employ. All permission settings are overwritten by this option.

Again you can set the permission to:

• Yes
  The access model field or node is included (default setting).
• No
  The access model field or node is excluded.
• Roles
  For selected user roles the value of PermissionOnRoleMatch is applied.