Role guide: tenant administrator

This guide is for the person who runs xMatix for everyone else in the organization. Your day is people coming and going (accounts, profiles, seats), questions about who can see what, settings that shape how each module behaves, data that needs loading or extracting, and the monitoring screens that show problems before users report them. You do almost all of it in Setup. Module owners bring you their requests, and the ones that need a new field, rule or script go to whoever builds your customizations.

Overview

Three layers decide what a person can do in xMatix, and most of your work is keeping them right:

• Security profiles grant operations: which apps a person opens, which entities and fields they read or change, which actions they run, and which Setup screens they reach (capabilities).
• Record security decides which records they see: each entity's policy, record ownership, the role hierarchy, teams, shares and rules. Roles, teams and business units never grant an operation; they only widen or narrow which records a profile's grants apply to.
• Licences and seats are the commercial layer. A product, feature or package your organization has not enabled stays hidden whatever the profile says. Where seats are enforced, a person also needs a seat.

When something goes wrong, check these layers in order rather than widening a profile. Troubleshooting: a user can't see something is the checklist.

Where you work

Setup opens from the gear menu at the right of the top bar (choose Setup). It opens in a new browser tab. The gear menu shows Setup only to someone who holds at least one Setup capability. The Setup sidebar has six areas: Design Studio, Process Studio, Platform, Sense AI Studio, Access control and Feature Hub. A tenant administrator lives in three of them:

Design Studio and Process Studio build the data model, layouts and automation. You decide when a request needs them; the developer role guide covers the work itself.

Some records that administrators keep are business records, so they live in the apps rather than in Setup: branches, resources, postal codes and holidays.

Your path

1. xMatix administration guide — where every administration screen lives, and which capability each one needs.
2. Invite a user and User accounts — the account, sign-in provisioning and the first profile.
3. How the xMatix security model works — the model everything else builds on.
4. Security profiles and the grant matrix — what a user may do, entity by entity, plus fields, apps, actions and capabilities.
5. Roles, teams and business units and Record-level security and sharing — which records each person sees.
6. Licensing: products, features and seats — what your organization has enabled, and who holds a seat.
7. Offboard or suspend a user — the leaver checklist.
8. Import data and Export data — bulk data in and out.
9. Troubleshooting background work — the Jobs screen and the other run histories.
10. Sandboxes and promoting changes — test a change before it reaches everyone.
11. The customization ladder — which tool fits which request, from a setting to a script.

Prerequisites

• A security profile that grants the Setup capabilities for your tasks. The built-in SystemAdmin profile is given every capability when your organization is created. A narrower administrator profile needs the keys listed under Permissions, including the two area gates.
• Your organization's licences enabled for the modules you administer. Module groups in Feature Hub appear only for enabled products.
• For changes you want to try out first, a sandbox, if your organization uses them.

Procedure

Step 1 — Open Setup and check what you can reach

Select the gear icon in the top bar, then Setup. Setup opens in a new tab on its home page. The home page shows Needs attention (failed integration runs from the last 24 hours, approvals waiting on you), Recently opened, and a card for each Setup area.

If an area you expect is missing, a capability or an area gate is missing from your profile: Access control needs setup.security.manage and Feature Hub needs setup.licensing.admin, even when you hold a screen's own capability.

Step 2 — Add a person and give them access

1. Go to Setup → Access control → Users and search for the person's email first. Each email can belong to only one account.
2. Select New, fill in the New User dialog (Username, names, Email, Audience Internal or External, Active) and select Create. The Sign-in column shows Pending and then Ready when the sign-in identity is provisioned, and the person receives an email.
3. Open the account and add at least one profile on the Profile Assignments tab. A new account has no profile, and a person with no active profile signs in to an empty workspace. The profile's audience must match the account's audience.
4. Add the person to roles and teams on Role Assignments and Team Assignments, and give seats on License Allocations where your licences need them. In an organization with several companies, give them access to the companies they work with.
5. Check the result on the Access Diagnostics tab. It shows the person's effective profiles, roles, teams, business units, licences and capabilities, and what their profiles need that they don't hold yet.

To switch on several prepared accounts at once, select their rows in the Users list and choose Activate (n). The dialog can give a security profile to users who have none, and add teams. The full procedure is in Invite a user.

Step 3 — Help someone who can't see or do something

1. Open the person's account and read the Access Diagnostics tab.
2. Work through the layers in order: licence and seat, profile grant (app, entity, field, action), company access, record security (ownership, hierarchy, teams, shares), then the view's filters. Troubleshooting: a user can't see something has the checks.
3. If you still can't see the cause, select Log in as user on the account. Enter a Reason and a Session length, then select Open session in new window. A new window opens signed in as that person, with their access and nothing more. Security setup, user management, credentials, API keys and integrations stay blocked for the whole session, and every action is recorded against both of you.
4. Fix the grant or the record access, not the symptom. Prefer moving the person to a better-fitting profile over widening a profile that others share.

Step 4 — Change how the organization or a module behaves

• Organization-wide settings: Setup → Feature Hub → Administration → Org settings. The General tab holds the organization's defaults, Custom settings holds named settings (a namespace, a key and a value), Companies lists your companies, and Company access decides who works in which company. Select Save to apply your changes, or Discard to drop them.
• A module's behaviour: Setup → Feature Hub → <module> → Settings. Every module with settings has an Enable master switch there. Read the module's configuration page before you change an option. For example, see procurement, warehouse, inventory, service, support or payroll.
• Document numbers, templates and messages: see Document numbering and Email templates and document numbering.

Step 5 — Load or extract data

Use Setup → Platform → Data → Import to load records in bulk, with a history of each row, and Export to take data out. Try a large import in a sandbox first. See Import data and Export data.

Step 6 — Watch background work and changes

Open Setup → Platform → Monitoring on a regular schedule:

• Jobs lists scheduled and on-demand platform jobs. Filter by status (Queued, Scheduled, Processing, Completed and so on) and retry or reschedule from there. See Troubleshooting background work.
• Message Log lists every outbound message, with its status and last error.
• Sync Monitor shows the health of integration sync profiles. See Sync health, conflicts and failed runs. The field team's own sync failures are a separate list in the Field Sales app; see Monitoring mobile sync failures.
• Audit Trail shows who changed what, filtered by entity, action, user and partner. Choose Login-as sessions in the entity filter to review log-in-as sessions. The Acting as column shows when a change was made during one.

Step 7 — Offboard a leaver

Hand over the person's open work and approvals, revoke their seats on License Allocations, then select Edit on the account, clear Active and save. From their next request, the organization refuses them with Your user account is inactive in this workspace. Contact your administrator. Activate brings them back. Use Delete only when your policy requires the account to leave the Users list. Neither action moves work or frees seats. See Offboard or suspend a user.

Step 8 — Delegate part of the job

To let someone else administer users or settings without full SystemAdmin rights:

1. In Setup → Access control → Profiles, create a profile (or Clone an existing one) for the delegated role.
2. On its Entitlements tab, grant only the capabilities the role needs, plus the area gate for each area those screens sit in.
3. Assign the profile on the person's Profile Assignments tab, and check their Access Diagnostics.

Example

A distributor is taking on six sales staff for a new region, and a regional office manager will look after their accounts.

1. The administrator prepares the six accounts in Setup → Access control → Users with Active cleared, so no sign-in emails go out yet. They add the sales profile, the region's role and team, and a product seat for each person.
2. On the start date, they select all six rows and choose Activate (6). Provisioning runs, and each person receives a set-password email. Within a few minutes the Sign-in column shows Ready.
3. One person reports an empty Orders list. The administrator opens Access Diagnostics, sees that the person has no company access for the region's company, grants it under Org settings → Company access, and asks the person to reload.
4. For the office manager, the administrator clones a profile, grants setup.security.manage and setup.security.users.manage on its Entitlements tab and nothing else, and assigns it. The manager can now invite and offboard staff but cannot reach Feature Hub or Platform.
5. At the end of the month, the administrator reviews Jobs and Message Log and finds no failed runs.

Training

Practice exercise

In a sandbox:

1. Create a test user with an email you control and Active cleared. Give it one profile on Profile Assignments.
2. Select Activate on the account and confirm. Expected result: Status changes to Active, and Sign-in reaches Ready within a few minutes.
3. Select Log in as user, enter a reason, keep the default session length and select Open session in new window. Expected result: a new window shows the workspace with only the test user's apps. Opening Setup's user management in that window is refused.
4. End the session, then open Setup → Platform → Monitoring → Audit Trail and choose Login-as sessions. Expected result: your session appears, with your reason.
5. Clear Active on the test user. Expected result: the test user's next request is refused with the inactive-account message.

Quick reference

• Setup opens from the gear menu in the top bar, in a new tab.
• Access control needs setup.security.manage; Feature Hub needs setup.licensing.admin. Both are on top of each screen's own capability.
• A new account has no profile. Assign one, or the person sees an empty workspace.
• Profiles grant operations; record security decides which records; licences decide which products.
• Start an access question on the person's Access Diagnostics tab.
• Log in as user is time-limited, audited, and can't touch security setup.
• Clearing Active blocks a person from their next request. Hand over their work and revoke their seats yourself.
• SystemAdmin always keeps the four core security capabilities. Every other capability can be removed from it.

Permissions

Capabilities are granted on a security profile's Entitlements tab. A capability also needs your organization's licence to include the feature it belongs to.

Four capabilities can never be removed from the built-in SystemAdmin profile: setup.security.manage, setup.security.users.manage, setup.security.audit.view and setup.security.users.loginAs. SystemAdmin and StandardUser cannot be renamed or deleted. Nothing assigns StandardUser automatically. As shipped it is broad (every operation on almost every entity), so give narrower profiles to people whose duties must be separated. The role guides overview summarizes the shipped profiles.

Configuration

Log in as user

Log in as user is on for any holder of setup.security.users.loginAs unless you switch it off. Set these in Setup → Feature Hub → Administration → Org settings → Custom settings, namespace security:

Other settings you own

• Company access: Org settings → Company access decides which companies each person works in. A person without access to a company doesn't see its company-scoped records.
• Themes and Branding: Feature Hub → Administration → Themes and Branding set the look of the workspace.
• Module master switches: each module's Settings has an Enable switch. Read the module's configuration page before you switch it off.
• Sandboxes: when they are enabled for your organization, Platform → Sandboxes & DeltaPacks creates sandboxes and promotes tested changes. See Sandboxes and promoting changes.

Common problems

The Setup option is missing from the gear menu

The gear menu shows Setup only to a person who holds at least one Setup capability. Grant the capability for the task on one of their profiles.

I was given user management but can't find Users

Users sits in the Access control area, and that area needs setup.security.manage as well as setup.security.users.manage. Grant both, or keep user administration with a full security administrator.

Feature Hub or a module's Settings is missing

The whole Feature Hub area needs setup.licensing.admin, and a module's group appears only when your organization's licence for that product is enabled. Check Feature Hub → Administration → Licenses.

A new user signs in to an empty workspace

The account has no active profile. Add one on Profile Assignments, then check Access Diagnostics.

There's no Log in as user on the account

The action needs setup.security.users.loginAs. It isn't offered for an inactive account or a built-in system account. If it is missing for every account, check that loginAs.enabled is not set to false under Custom settings. Starting a session when the feature is switched off fails with Login as user is switched off for this organization.

I deactivated someone, but their seats are still in use

Clearing Active or deleting an account doesn't revoke seats. Revoke them on the person's License Allocations tab.

Common questions

A user says they can't see a record — where do I start?

Start on the person's Access Diagnostics tab, then follow the layers in order: licence and seat, profile grant, company access, record security, view filters. Troubleshooting: a user can't see something walks each one. Most cases are a missing profile grant or a record the person neither owns nor reaches through the hierarchy, a team or a share. If the cause still isn't clear, Log in as user shows you exactly what they see, and the session is recorded in the Audit Trail. Fix the cause rather than adding a broad profile.

How do I set up access for a new team or region?

Copy a working pattern. Worked security scenarios shows complete setups for territory scoping, manager roll-ups and sharing between teams, which you can adapt. Build the profile by cloning the closest shipped one and trimming it, place people in roles so the hierarchy gives managers their team's records, and add teams where people outside the hierarchy need access. The role guides for sales managers, warehouse operators, buyers and support agents list what each profile needs.

Someone is asking for a change — is it a setting, configuration or a developer job?

Start at the bottom of the ladder. If a module's Settings or Org settings already has the option, change the setting. If the request needs a new field, layout, view, business rule or workflow, it is configuration in Design Studio or Process Studio. Only behaviour that configuration can't express needs a script or code. The customization ladder explains each step, and Customizing xMatix is the section to hand over.

Can I lock myself out of Setup?

Not completely. Managing profiles, managing users, viewing the audit trail and logging in as another user can never be removed from the SystemAdmin profile. Any SystemAdmin holder can therefore restore a capability you removed by mistake. Keep at least one active account that holds SystemAdmin, and don't clear Active on your own account: your next request would be refused.

Related topics

• xMatix administration guide
• Role guides
• Setup Copilot — describe a configuration change and let it draft it.
• AI Studio — the administrator's controls over AI features.
• Configuring the mobile app
• Troubleshooting access and sign-in
• Role guide: developer