A custom role is a named set of permissions you build yourself and assign to as many users as you like. Use one when none of the five system roles grants the right combination of modules for a job.
Custom roles are built on the Roles tab under Main menu → Manage Users & Roles, using a grid of Read, Create, Update and Delete checkboxes grouped by module. You also choose which organizations a role is offered for, and that choice also limits which organizations its users can reach. This guide is for admins.
Important: The Roles tab and the role builder are available to the Admin role only. Managers can add and edit users on the Users tab, but cannot create or change roles.
Prerequisites
The Admin role.
A clear idea of which modules the role needs, and for each one whether the role should only view it, or also add, edit or remove things in it.
For a role that needs the Trading Party tab of a configuration module, read access on Trading Parties, because that tab depends on it.
Steps
Creating a role
1. Go to Manage Users & Roles in the main menu and open the Roles tab. The tab lists the five system roles and any custom roles already in your tenant.
2. Click Add New Role.
3. Enter a name for the role. Choose something a colleague would recognize on the Users tab, such as "AP Team Lead" rather than "Custom 2".
4. Optionally add a description explaining who the role is for. It shows next to the role on the Users tab role picker.
5. Optionally pick the organizations the role is meant for in the role's Organization field. Leave it empty to make the role visible to every organization. See Choosing which organizations can see the role below.
6. Work down the permission grid and set access module by module. Each module has four checkboxes, and each one is granted on its own:
Read lets the role open the module and see what is in it.
Create lets the role add new items, for example Add New, copying a trading party, generating API credentials, or adding a new rule or instruction to an existing group or build.
Update lets the role change existing items, for example Edit, activation switches, reordering, and saving changes to settings.
Delete lets the role remove items, including removing a saved rule or instruction from inside a group or build being edited.
Turning on Create, Update or Delete automatically checks Read and locks it, because you cannot act on something you cannot see. A level a module has nothing to offer for is shown greyed with the tooltip "Not available for this module", for example Delete on Data Export Templates and on the System Settings sections such as Data Retention and Rejection Email Notification, and Create on the Global row of Instruction Builds, where saving replaces the whole set. A few rows, such as Priority Queue, offer Update only. Under Auto Review, Base Settings offers Read, Update and Delete, and the Trust ledger row offers Create, Update and Delete for adding, editing and removing trust ledger values, including trusting a pair from a document. The Trust ledger row stays greyed until the role has read access on Auto Review.
The Document actions group works differently. Delete, Download, Reprocess, Review and Validate each have a single Grant checkbox, because they act on documents that already exist. Review covers approving and rejecting, and Validate is shown only when the validator feature is on for your workspace.
Note: Some workspaces show Read and Write columns instead of Create, Update and Delete. There, Write lets the role add, edit and remove together, and turning it on checks Read in the same way.
7. Save the role.
Choosing which organizations can see the role
The role's Organization field sits beside the role name and lists your organizations and sub-organizations. It decides two things: which users the role can be given to, and which organizations those users reach.
Tick the organizations the role is meant for. Ticking a parent organization as a whole covers all of its sub-organizations, including ones added to it later. Ticking only some sub-organizations covers just those. A role that covers a parent organization as a whole can be given to a user in any of its sub-organizations, and a role for one sub-organization can be given to a user who holds its parent as a whole.
Leave it empty and the role is visible to every organization, including ones created later, the same as a system role. When you view such a role, the field reads All organizations.
System roles are always visible to every organization. Their Organization field is read-only and reads All organizations.
What a user on the role can reach depends on the organizations picked for the user on the Users tab:
User's organizations | Role with organizations ticked | Role with Organization left empty |
None selected | Every organization the role can see, including ones added to the role later | Every organization except self-service ones |
Some selected | Only the selected organizations the role can also see | The selected organizations |
When a user on a role creates an organization, it is added to that role's Organization field, unless the role already covers it. Every user on that role with no organizations selected then reaches the new organization. Users with their own organizations selected reach it only once it is ticked for them.
Setting access on the four configuration modules
Instruction Builds, Transformations, Rejections and Customize Captured Fields each expand into four rows rather than one, matching the tabs inside the module:
Row | What it controls |
Organization | The Organization tab of that module |
Trading Party | The Trading Party tab of that module |
Country | The Country tab of that module |
Global | The Global tab of that module |
Each row carries its own Read, Create, Update and Delete checkboxes, so you can, for example, let a role edit organization-level transformations without being able to delete them, while leaving country-level ones view-only.
Two constraints apply as you fill these rows in:
The Trading Party row stays greyed out, with an info note explaining why, until the role has read access on Trading Parties. Grant that first, and the row becomes available.
Country and Global rows offer Read only. Their Create, Update and Delete boxes are greyed with the tooltip "Can only be edited by admins", because Country and Global configuration can only be changed by an admin. (On the Global row of Instruction Builds, Create shows "Not available for this module" instead, because that row has no Create level at all.)
Note: Billing & Payments cannot be granted to a custom role at all. It stays with the Admin role.
Starting from an existing role
Rather than building a grid from scratch, duplicate a role that is already close to what you want:
On the Roles tab, find the role you want to start from. This can be a system role or another custom role.
Duplicate it. The new role opens with the same grants already selected.
Rename it, adjust the description, and trim or extend the grid.
Save.
Duplicating is also how you work from a system role, since system roles are read-only templates and cannot be edited in place.
Duplicating a custom role copies its Organization field. Duplicating a system role starts with that field empty, so the copy is visible to every organization, like the system role it came from.
Viewing, editing and deleting
View role opens a role and shows its grants. Use it on a system role to see exactly what that role covers before assigning it.
To change a custom role, open it, adjust the grid, and save. The change applies to every user holding that role.
Changing the role's Organization field also changes what the role's users reach, from their next action, with no change to the users themselves. A role cannot be narrowed away from organizations its users still need: if any user holding it has organizations selected and none of them would remain, saving is refused with "This role is held by 3 users outside the selected organizations. Change their role first."
To remove a custom role, delete it from the Roles tab. A role that is currently assigned to users cannot be deleted. Move those users to another role first, then delete it.
Assigning the role to users
Open the Users tab.
Add a new user, or edit an existing one.
Pick your custom role from the role list, alongside the system roles.
Optionally pick the user's organizations under Organization. Once a role is picked, the list shows only the organizations that role can see, and any already ticked that it cannot see are removed. Leave it empty for the user to follow the role.
Save.
A role can be given to a user only when it is visible to at least one of the user's organizations. Otherwise saving is refused with "This role is not available to the selected organizations." A user with no organizations selected can be given any role.
When you edit a user whose saved role is no longer visible to their organizations, the role field opens empty with the note "This user's role is no longer available to their organizations. Choose another role."
Expected Outcome
The role appears on the Roles tab and in the role list on the Users tab, ready to assign.
Users holding it see only the modules their role can at least read. Inside those modules, anything the role cannot do is greyed out with the tooltip "You do not have the required permissions to do this action", so they can see what the module does without being able to act on it. Because each level is separate, a user can, for example, see Edit available while Add New or Delete is greyed.
Common Issues
Issue | Cause | Resolution |
The Roles tab is not there | The Roles tab is available to the Admin role only | Ask an admin to create or change the role. Managers can still add and edit users on the Users tab |
The Trading Party row is greyed out | The role does not yet have read access on Trading Parties, which that row depends on | Grant read on Trading Parties, and the row becomes available |
Create, Update or Delete cannot be turned on for a Country or Global row | Country and Global configuration can only be changed by an admin, so those levels are never grantable on those rows | Grant Read for visibility. If the person needs to change those tabs, they need the Admin role |
A checkbox shows "Not available for this module" | The module has nothing to offer at that level, for example nothing to delete | No action needed. The level does not apply to that module |
Read cannot be unchecked | Create, Update or Delete is on, and each of them implies read | Turn those off first, then read becomes editable again |
A user can edit but Add New is greyed, or can add but Delete is greyed | The role holds some levels on that module but not the others | Grant the missing level on that module's row |
Billing & Payments is not in the grid | Billing & Payments cannot be granted to a custom role | Give the person the Admin role if they genuinely need billing access |
A role cannot be deleted | The role is assigned to at least one user | Reassign those users to another role, then delete it |
A role is missing from the role list on the Users tab | The role is not visible to any of the user's organizations | Tick one of the user's organizations in the role's Organization field, or pick another role |
Saving a user fails with "This role is not available to the selected organizations." | The role is not visible to any of the organizations picked for the user | Pick a role visible to one of them, or add one of them to the role's Organization field |
Saving a role fails with "This role is held by 3 users outside the selected organizations. Change their role first." | Narrowing the role's Organization field would leave users holding the role with none of their organizations | Move those users to another role, or keep one of their organizations ticked |
A user on a role cannot reach an organization they could before | The organization was removed from the role's Organization field, or the user has their own organizations selected and that one is not among them | Tick the organization in the role's Organization field, or select it for the user |
An organization cannot be deleted | A custom role is visible to it, or to one of its sub-organizations | Remove the organization from those roles first. The error names the roles |
A user still cannot reach a module after the role was widened | The user signed in before the role was changed | Ask them to sign out and sign back in |
A system role cannot be edited | System roles are read-only templates | Duplicate it and edit the copy |
Notes
Create, Update and Delete each imply read. Turning any of them on auto-checks read and locks it, so a role can never act on something it cannot see.
The four configuration modules expand into four rows each, one per tab, and each row carries independent Read, Create, Update and Delete.
Inside an edit, levels still apply separately: adding a new rule or instruction to an existing group or build needs Create, and removing a saved one needs Delete.
Document actions use a single Grant box each instead of the four levels.
Country and Global configuration is view-only for custom roles. Only admins can add to, change or remove it.
Billing & Payments is outside the custom role grid entirely.
A role in use cannot be deleted, which keeps users from silently losing access.
Editing a role changes access for every user holding it, so check who holds a role before widening or narrowing it.
Give roles names and descriptions that describe the job, not the person. A role is meant to outlive the individual it was first created for.
A role's Organization field left empty means every organization, including ones created later. Unticking the last organization therefore widens a role to every organization rather than hiding it.
A user with no organizations selected follows the role: whatever the role can see, they reach, including organizations added to it later. Organizations added to a role because one of its users created them reach all of the role's followers too.
While a custom role is visible to an organization, that organization cannot be deleted. This stops a role from being left limited to organizations that no longer exist.
Related Articles
Types of Users and Their Roles - the five system roles and what each one covers
Legacy Custom Roles - per-user custom permissions carried over as named roles
Filtering Users by Organization and Role - narrowing the Users tab by role