Skip to main content

Data roles

A data resource role is a file, jcm/roles/<code>.yml, named after its code (jcm-security, RoleFiles.KIND, bean jcm_RolesKind). Like the model it is fixed when the application is built: it is read only from the classpath, and no override folder can replace, add or remove one (<file>:1: role files are fixed when the application is built and cannot be replaced or removed by an override folder; change the application's file and rebuild); change the file and rebuild, or stage the change in the studio where its folder is the source (Configuration studio, "Staged editing"). Roles that need view, menu or specific policies (the template's UiMinimalRole, FullAccessRole) stay in Java. A new app's starter role is a file, which jcm new writes as jcm/roles/case-worker.yml (with the screen starter, which brings jcm-security):

code: case-worker
name: Case worker
description: Works Request cases on the case screen and in case search
includes: [ui-minimal, jcm-case-screen-user, jcm-case-search-user, jcm-tasks-user] # jcm-tasks-user with tasks
entities:
Request: {actions: [all], modify: "*"}
code: demo-officer
name: Hearing officer # required
description: Decides hearings # optional
includes: [demo-worker, ui-minimal] # other role files, or roles the framework or a component defines, by code
entities:
Decision: {actions: [create, read, update], modify: "*"}
Appeal: {actions: [update]}
User: {actions: [read], view: [username, firstName, lastName]}
  • Keys: code, name, description, includes, entities; under an entity actions, view, modify. Any other key is refused (unknown key 'colour'; allowed keys are [...]).

  • actions are among create, read, update, delete, all (Jmix's entity actions); one or a list. Another is refused: roles/x.yml:5: role 'x': action 'approve' is not one of create, read, update, delete, all.

  • view and modify are "*" for every attribute of the entity or a list of attributes; "*" in a list with others, an attribute listed twice, or any other single value is refused. An entity with none of the three is refused (Appeal grants nothing; give it actions, view or modify, or leave it out); so is a key written empty.

  • A file grants only what it writes: no entity it does not name, no attribute beyond its list. It names each entity it grants: "*" as an entity is refused ('*' is no entity; a role file names each entity it grants); a role over every entity stays in Java, as the template's full-access role does.

  • RoleFiles (bean jcm_RoleFiles) reads the files once at startup; all() gives each as a RoleFile(code, name, description, includes, entities, source, line, includesLine), by code, each grant an EntityGrant(entity, actions, view, modify, line).

  • The role. jcm_FileResourceRoleProvider makes one Jmix resource role per file: its code, name and description, source roles/<code>.yml, the includes as child roles, scope UI. Each action is an entity policy on the entity, each attribute an attribute policy on <entity>.<attribute> (<entity>.* for "*") with action view or modify; nothing else. The role repository adds the included roles' policies, as for any role. A file role cannot be deleted through the admin screens. Assign it like any resource role, and name it in a job role's resource-roles.

  • The checks. Before the application starts, jcm_RoleFileCheck holds the files against the application and stops startup with every problem at once, one sentence each:

    • roles/demo-officer.yml:6: no entity is named 'Decison'
    • roles/demo-worker.yml:14: User has no attribute 'usrname'
    • roles/demo-officer.yml:3: includes 'demo-wroker', which is no role here: an include names a role file, or a role the framework, a component or the app defines (ui-minimal, jcm-inbox-user).
    • roles/a.yml:3: includes b, which includes a; a role cannot include itself
    • roles/x.yml:3: includes system-full-access, which grants every right there is; a role file grants data rights only, so assign system-full-access to the user directly instead. The complete include graph is checked, including external Java/component roles: indirect full access and cycles are refused too. Database-defined includes are refused directly and transitively because their policies can change after the file role is built. Ordinary immutable includes bring their view, menu and specific policies too, as a child role does in Java.
    • roles/demo-officer.yml:1: the code demo-officer also names a role written in Java; one code names one role: the slip of moving a role from Java to a file and leaving the class. A role of that code kept in the database (made by a role import, the REST API or a database write; the role admin screen already refuses a code a file role has) gives ... also names a role defined in the database; ... at the next startup. Until that restart Jmix takes whichever role provider comes first, so the file role's users may get the database role's rights instead: remove the database role.

    RoleFileCheck.problems(files, attributesOf, definedElsewhere, includedRole) gives the same sentences from plain functions; definedElsewhere says where another role of a code is (RoleFileCheck.JAVA, RoleFileCheck.DATABASE), empty when nowhere. includedRole gives an optional JCM IncludedRole(database, includes) description of an external role, without exposing framework types.

  • In the studio's role matrix a file role is one of the app's roles (not a framework one), its source its file (roles/demo-officer.yml).