Skip to main content

Permissions

To decide whether an element should be displayed on a form element, permissions are decided by 3 factors.

  1. Rule Engine
  2. User Roles
  3. Form Permission

There are 4 permissions that an element can have:

  1. INHERIT - element must use the permission of its parent, default permission
  2. DELETE - element is hidden
  3. EDIT - element is editable and must be sent to backed on POST calls
  4. VIEW - element is readonly
  5. VIEW

Rule Engine​

Rule Engine calculates the permission of an element by php rules defined on the backend

{
    "name": [
        "action",
        "save_progress"
    ],
    "label": "Save Progress",
    "value": "Save Progress",
    "__value": "Save Progress",
    "is_web_compatible": "1",
    "is_mobile_compatible": "1",
    "rules_grid": "1",
    "rules": [
        {
        "_is_active": "0",
        "is_active": "1",
        "if_condition": "\\kernel\\request::getInstance()->action==\"add\"",
        "permission": "1"
        }
    ],
    "roles_grid": "1",
    "helper": "\\kernel\\form",
    "method": "submit",
    "allow_copy_to_clipboard": "0",
    "allow_user_to_specify_user_level_default": "0",
    "business_key": "65dcdcab-a60c-4090-a2f5-4930ac69033c",
    "template": "submit",
    "packaged_with_module": "crm",
    "mw": false
}

On this element the element has the permission 1 if the if_condition is met and is_active is 1.

if_condition: "\\kernel\\request::getInstance()->action==\"add\""

On javascript frontends, we will need to transform this request to a javascript equivalent function.

In this documentation is rule-engine.js, a javascript function that takes in request data and an element and calculates the permission based on the inputs

public/rule-engine.js
 function initRuleEngine(
    user, // data.users
    d, // { model: data.[controller], [controller]: data.[controller] }
    module, // module (crm)
    controller, // controller (peoples)
    action, // action (edit)
    object, // record topLevel
    node, // element
    permissions, // menuPermissions mapped to an obj
    additionalTopLevel, // // record topLevel fields
  ) {
    return new RuleEngine(
      user,
      d,
      module,
      controller,
      action,
      object,
      node,
      permissions,
      additionalTopLevel,
    );
  }

By passing the above paramaters to the RuleEngine, you are able to translate backend php rules to javascript and execute them on the client.

If you are planning on using this file in your code, you must place it in the public assets folder as if it is included in your compiled build the code will be deobfuscated and not work as intended.

These permissions come from the actions/menu's that the user has permission to and can be fetched by calling the following API.

https://v2.crm.immigrate.fiyge.com/development_base/menus/index.json?q={"fields":["url_key"],"group":["url_key"],"method":"find"}&limit=0

This will fetch all the permissions have access to, you must then map this to an object.

{
    [url_key]: url_key
}

This can then be passed onto the rule engine to calculate the php rules that require menu permission.

User Roles​

The next step in calculating permissions is by checking their assigned user roles.

When calling the login function on a user, the user data record is also returned under data.users, inside this object is a key called assigned_roles.

{
    data: {
        users: {
            assigned_roles: [
                "645933bd-7ae0-4464-ac01-41cbac69033c",
                "635af8c6-9dd0-4908-b5f0-4861ac69033c",
                "6359895c-1660-429d-8fd1-481bac69033c"
            ],
        }
    }
}

On a form element there may be a a field called roles, whcih is an array of roles with a given permission. You must loop over and cross check a users assigned roles and the roles on the form element to calculate the permission. You must loop in order of the keys 1...N, and use the last matching permission is the current permission.

{
    "name": [
        "Workflow"
    ],
    "label": "Workflow",
    "is_web_compatible": "1",
    "is_mobile_compatible": "1",
    "roles": {
        "1": {
        "role_id": "63c7d2ef-9784-493a-9ee0-4417ac69033c",
        "role_id_model": "Access Controls",
        "__role_id": "System Portal User",
        "_is_active": "0",
        "is_active": "1",
        "permission": "1"
        }
    },
    "helper": "\\kernel\\form",
    "method": "collection",
    "field_collection": "0",
    "allow_copy_to_clipboard": "0",
    "allow_user_to_specify_user_level_default": "0",
    "business_key": "65022b11-ecc0-4296-ae14-4492ac69033c",
    "template": "collection",
    "packaged_with_module": "crm",
    "mw": false,
}

Form Permissions.​

Finally inside the data record there is a key called permissions. This contains a static permission of elements. The children of this object are elements' names with the corresponding permission.

  "permissions": {
    "peoples": {
      "relationship_id": 4,
      "related_to_person_id": 1,
      "will_accompany_the_primary_applicant": 1,
      "allow_portal_access": 0,
      "family_size": 1
    }
  },

Permission Execution Order​

A single element may qualify for all 3 permission handlers. To calculate the correct one you must try and execute all of them in the order below and always take the last executed permission.

  1. Rule Engine
  2. User Roles
  3. Form Permission