Skip to main content

Roles and permissions

A role is a named set of permissions. Everything a person can see and do in ITS comes from the roles on their account. What a role grants takes effect for everybody who holds it, immediately.

The Roles tab lists every role, shows what each one grants, lets the operator and the Secretariat change what a built-in role grants, and lets them build roles of their own when the built-in ones do not fit.

Who can open this screen​

System admin, the operator who runs the deployment, and Secretariat admin.

What you see depends on who you are
You are signed in asWhat you see
The operator (System admin)Users & roles has a Roles tab, with New role and every role for people.
The Secretariat adminThe same.
A State Party or REC administratorNo Roles tab. Typing its address shows You do not have access to this area and "Ask the Secretariat to check the role on your ITS account."

The Roles address opened by Uganda's administrator: You do not have access to this area

To know what a role grants without this screen, read What each role can do.

Before you start​

  • You need System admin or Secretariat admin.
  • Know which job you are describing. Most people need one of the built-in roles; a custom role is for a job none of them fits.

How to open it​

  1. Select Users & roles in the header.
  2. Select the Roles tab.

The list shows the roles for people, including Localization admin, which lets a person correct ITS's translations in the localization service and grants nothing in ITS itself. Roles that belong to systems (partner systems, publishers, reconcilers, service accounts) are left out: nobody gives them to a person here. Use the role descriptions and What each role can do to confirm a role's purpose.

Under the table, "Member counts include only people in this organisation." The operator and the Secretariat admin both belong to the Secretariat, so Members counts the Secretariat's people only.

On the page​

On the pageWhat it is for
New roleBuild a custom role.
Search roles…Narrows the page of roles you are looking at by name or description. When the roles fill more than one page, a line under the table says how many on this page match and which page the search covers.
StatusActive only or Including inactive.
Clear filtersShown while a search or Including inactive is in effect. It empties the search box and puts Status back to Active only.
RoleThe name, a System or Custom badge, and the description. A padlock marks the one role nobody can change, System admin; every other role has a shield.
PermissionsHow many permissions the role grants.
MembersHow many people in this organisation hold it.
StatusActive or Inactive.
⋮ (Role actions)View, Duplicate, Edit and Deactivate (or Activate); Delete on a custom role only. System admin offers only View and Duplicate.

Select a row, or View in its menu, to open the role's panel.

The row menu on the Customs officer system role: View, Duplicate, Edit and Deactivate

System roles and custom roles​

System rolesCustom roles
Where they come fromPart of the deploymentBuilt on this screen
BadgeSystemCustom
What you can doView, Duplicate, Edit, Deactivate or Activate. Never DeleteView, Duplicate, Edit, Deactivate or Activate, Delete
Its machine nameFixedFixed once the role is created

System admin is the exception: it is the operator's recovery account, so no edit, deactivation or deletion reaches it. Its panel says "A system role ships with the deployment. It is read-only — the backend refuses every write against it."

The roles for people and the roles for systems are described in What each role can do. Only the roles for people appear on this screen and on Users.

Look inside a role​

  1. Select the role's row, or select View in its ⋮ menu. A panel opens on the right.

    The Organisation admin role opened with View: machine name, members, permission count, description, and the permissions by area

  2. Read the panel:

    Panel sectionWhat it shows
    HeaderThe role's name, System or Custom, and Active or Inactive.
    RoleMachine name (the role's fixed internal name, for example organisation-admin), Members in this organisation, Permissions (the count) and the description, with Edit and Duplicate.
    PermissionsOne line per area, with the actions granted on it: for example customs-office with activate create deactivate export import read update. No permissions. Anyone holding this role can sign in but do nothing. when it grants none.

The panel writes the areas with their internal names. The ones you will meet most, with the name the editor gives them:

AreaIn the editorWhat it covers
etdTransit declarationsDeclarations: read, and for systems issue (lodge), endorse (stamp), amend, attach, cancel, acknowledge.
its-analytics, its-register, its-integration, its-workforceAnalytics reports, Register reports, Integration reports, Workforce reportsThe Reports areas: Transit volumes and Time & delays; Register; Integration; Workforce.
customs-officeCustoms officesThe customs office register.
governanceGovernance datasetsGovernance, and changing the rules and limits on Settings.
intake-limit, transit-rule, operations-settingIntake limits, Transit rules, Operations settingsReading the three sections of Settings: Declarations, Transit rules and Operations.
user, user-stationUsers, Duty stationsUsers (including reset-second-factor), and duty-station postings.
authz-roleRolesThis screen.
notificationNotificationsNotifications and the bell.
onboarding, onboarding-selfOrganisation onboarding, Self-service onboardingThe System integration area: every organisation's record, and an organisation's own.
ledgerLedgerThe Consortium ledger.
audit-trailAudit trailThe Audit trail.

The role editor​

New role, Duplicate and Edit all open the same window.

The Edit role window for the Customs officer system role: Role name, the sentence naming its fixed API key, Description, and the permissions grouped by area with the actions granted shown in green

In the windowWhat it is for
Role nameThe name people see, for example "Regional auditor". Required.
DescriptionWho the role is for (What this role is for…).
Permissions"Click a permission to grant it — click again to remove. Click an area name to grant or remove all of it."
Search permissions…Narrows the list to areas and actions whose name matches.
n of n grantedHow many of all the permissions the role grants, with a bar.
Select shownGrants every permission the search has left on screen: the whole list when nothing is typed.
Clear allRemoves every permission.

The permissions are grouped by area: Transit, Onboarding, Reference data, Reports, Administration, Audit & ledger. Each area's band shows how many of its permissions are granted; select that count to grant or remove the whole area. Under it, each line is one part of ITS, such as Customs offices, with its actions as small tags, green when granted:

  • Select a tag, such as Read, to grant or remove that one action.
  • Select the line's icon or name to grant or remove all its actions.

The window keeps the save button greyed out until the role has a name and the whole list of permissions has loaded. If the list could not be read in full, the window says "The catalogue is larger than this screen loaded. Saving now would drop the permissions that were not read — reload before editing." Do what it says.

Closing the window with unsaved changes asks you first whether to discard them.

Change what a built-in role grants​

Everybody who holds the role is affected at once

A change to a built-in role, such as Customs officer, applies to every person who holds it as soon as you save. If only some people need different permissions, build a custom role instead.

  1. In the role's ⋮ menu, select Edit, or select Edit in its panel.
  2. The window Edit role says "Built-in roles keep their key; their permissions can be changed." Under Role name, "Referred to in the API as" names the role's machine name, "which cannot change".
  3. Change the name, the description or the permissions.
  4. Select Save changes, or Cancel.

Role updated confirms it. Editing a custom role works the same way; its window says "Update this role's details and permissions."

Deactivate, activate or delete a role​

  • Deactivate in the ⋮ menu marks a role Inactive. Role deactivated confirms it. To see inactive roles, set Status to Including inactive; Activate brings one back.
  • Delete is offered on custom roles only. Delete this role? warns: "Name is removed for good — unlike a user, a role really is deleted. Anybody holding it loses what it granted. Deactivate it instead if you may want it back." Role deleted confirms it.

Build a custom role​

The quickest way is to start from the closest existing role.

  1. In that role's ⋮ menu, select Duplicate. The Duplicate role window says it "Starts from what" that role grants: "Nothing is created until you name it and press Create — and the original is not touched." The name is left empty.
  2. Or select New role to start from nothing.
  3. Give the role a Role name people will recognise, and a Description saying who it is for.
  4. Choose the permissions in the role editor.
  5. Select Create copy (or Create role), or Cancel to keep nothing.

Role created confirms it, with the role's name. ITS makes the role's machine name from the name you typed; it cannot change afterwards. Open the role's panel to read it.

A role with no permissions can be created. Anyone holding it can sign in but do nothing.

Nobody can give a custom role to people on Users yet. The roles each kind of organisation may give are a fixed list set by the ITS team in ITS's configuration: for the Secretariat, Secretariat admin, Organisation admin, Customs officer, Departure authority and Partner; for a State Party, Customs officer and Departure authority; for a REC, Customs officer. A custom role is in none of them. To make one grantable, ask the ITS team to add it to the list for that kind of organisation. That is a configuration change, not a new release.