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 Settings → Manage Users & Roles, using a grid of read and write checkboxes grouped by module. 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 whether each one should be view-only or editable.
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
Go to Settings → Manage Users & Roles and open the Roles tab. The tab lists the five system roles and any custom roles already in your tenant.
Click Add role.
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".
Optionally add a description explaining who the role is for. It shows next to the role on the Users tab role picker.
5. Work down the permission grid and set access module by module. Each module has a read checkbox and a write checkbox: - Read lets the role open the module and see what is in it. - Write lets the role change things. Turning on write automatically checks read and locks it, because you cannot edit something you cannot see. 6. Save the role.
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 and write checkboxes, so you can give a role write access to organization-level transformations 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 but not write. Country and Global configuration can only be changed by an admin, so a custom role can be given view access to those tabs and never edit access.
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.
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.
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.
Save.
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 don't have permission to perform this action", so they can see what the module does without being able to act on it.
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 |
Write cannot be turned on for a Country or Global row | Country and Global configuration can only be changed by an admin, so write is never grantable on those rows | Grant read for visibility. If the person needs to edit those tabs, they need the Admin role |
Read cannot be unchecked | Write is on, and write implies read | Turn off write first, then read becomes editable again |
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 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
Write implies read. Turning on write auto-checks read and locks it, so a role can never have edit access to something it cannot see.
The four configuration modules expand into four rows each, one per tab, and each row carries independent read and write.
Country and Global configuration is view-only for custom roles. Only admins can change 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.
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