Defining a custom permission
There are five elements that define a permission:
This is the name of the permission, and it’s what you will see when selecting permissions in the Roles screen.
💡We recommend using a naming convention that starts with either Allow or Deny in accordance with what the permission is accomplishing. For example a permission that allows a person to see the Groups page in Charthop might be labeled “Allow Read Groups”.
This is a full description of what the permission accomplishes.
💡We recommend being as descriptive as possible, since this will help your team keep a better record of what each permission does, and helps ensure that any ChartHop administrators will give proper custom access to the often-sensitive data stored in ChartHop. Without detailed descriptions, mistakes can happen.
This allows you to toggle whether the specific permission is to Allow or Deny access to data, pages, or actions in question.
☝Please note that you cannot combine both Allow and Deny into one permission using the Permissions interface. If you have a need to have both, you should instead create two separate permissions on the same role, or you can use the Advanced Editor.
There are two menus present in a permission that are linked together. These choices are known as the permission’s entity action pair. Together, these define what the user is allowed to do (the action) on which part of the platform (the entity).
First select the Entity, or part of the platform you want to grant or deny access to. Then select the Action, or what behavior you want to allow or deny for the given entity.
☝Please note that the Action menu will change depending on the Entity so please select an Entity first.
There are 4 basic Actions that are present on most Entities:
- Create: Create controls the ability to create instances of the Entity.
- For example, for an ALLOW permission, if you select the entity Group and the action Create, then the permission would grant the ability to create new Groups – new Departments, Teams and Locations.
- Read: Read controls the ability to see that specific Entity.
- For example, for an ALLOW permission, if you select the entity App and the action Read, then the permission would grant the ability to see the list of Apps that are available to be installed.
- Update: Update controls the ability to edit an already existing Entity instance.
- For example, for an ALLOW permission, if you select the entity Person and the action Update, then the permission would grant the ability to edit or update the details of a Person that is already created, such as updating someone’s legal name or work email.
- Delete: Delete controls the ability to delete a specific instance of an Entity.
- For example, for an ALLOW permission, if you select the entity Comp Band and the action Delete, then the permission would grant the ability to delete a Comp Band that is already created, like deleting an outdated band.
When defining a permission, you might want to restrict the scope of access. We offer you three ways to restrict a permission’s scope:
- Field and Category restrictions
- Directions restrictions
- Carrot (CQL) filters
We’ll dive into how to use each restriction type.
Field and Category restrictions limit the permission to apply only to the specified Fields or Categories. Field and Category restrictions can be used on Person, Job, Business Unit, and Comp Band entities.
Some examples:
- ALLOW job:read fields:[“baseComp”] grants the ability to see the “baseComp” field for all jobs in the system, but not other job fields.
- ALLOW job:read categories:[“performance”] grants the ability to see all the fields in the “performance” category for all jobs in the system, but not other job fields.
- DENY person:read fields:[“birthDate”] denies the ability to see the “birthDate” field for all people in the system.
Keep in mind that every field in Charthop applies to a particular entity, either Person, Job, Business Unit, or Comp Band. Depending on the specific field you would like to allow or deny access to, you will need to check the “Applies to” option for that field on the Fields list page, and select the appropriate entity when configuring your permission.
Directions filters enable you to limit the permission according to the person’s position in the org chart. Direction filters can only be used with Job and Person entities.
There are four available directions:
- Self: limits the permission to apply to the user’s own person or job
- Under: limits the permission to apply to those “below” the user in the org tree. Think the person’s direct reports, grand reports, all the way down the tree.
- Over: limits the permission to apply to those “over” the user in the org tree. Think the user’s manager, grand-manager, all the way up the tree.
- Peer: limits the permission to apply to jobs outside of the person’s reporting line.
Some examples:
- ALLOW job:read directions:[“under, self”] grants the ability to see all the fields for the user’s own job and any jobs that report up into them.
- DENY person:read fields:[“baseComp”] directions:[“over”] denies the ability to see the “baseComp” field for anyone over the user in the management chain (their manager, their manager’s manager, etc.)
In the event that you need to filter your permission by even more complex logic, you can use the generic Carrot (CQL) filter. Using a Carrot filter on your permission will apply the permission only to Jobs and People matching that filter string.
Some examples:
- ALLOW job:read filter:”job.department=me.department” grants the ability to see all the fields for any jobs whose department matches the user’s department. (e.g. if the VP of Engineering had this permission, she could see the job details of all jobs in the Engineering department.)
- ALLOW person:read fields:[“address”] filter:”job.location=’remote’” grants the ability to see address fields for any job with a “remote” location.
To learn more about how to use query expressions, check out our Carrot Docs.
