Defining Roles

Step 1 — Roles Matrix

The Roles Matrix is the foundation of your project configuration. Here you define a three-level hierarchy that describes the organisations, functions, and disciplines participating in your project. Every valid combination of these three levels becomes a distinct ACC role.

Want to try this first? The interactive demo comes pre-populated with a UK infrastructure project so you can explore all features without signing up.

The three levels

The wizard displays three columns, one per level. You add values independently to each column:

The combination of all three levels produces ACC role names. For example, with the values above you would get roles like Employer - General - Civil or Contractor - Checker - Structural.

Adding and editing values

Each column has a text input at the top. Type a value and press Enter (or click Add) to add it. Values are automatically capitalised. To edit an existing value, click the pencil icon next to it — this opens an inline editor where you can change the name or its description.

Descriptions

Each value can have an optional description. Toggle the eye icon at the top of a column to show or hide description fields. You can write descriptions manually or use the Generate Descriptions button to have the AI write them for all values at once.

Validation

Values are validated in real-time as you type:

• Names cannot contain \ : * ? " < > | or backticks — these are invalid in ACC folder names.
• Duplicate values (case-insensitive) are not allowed within the same level.
• All three levels must have at least one value before you can proceed to the next step.

CSV import

Click Import from CSV to open the import dialog. You can select from existing CSVs already in Foreman, or upload a new ACC admin roles CSV directly (exported from Account Admin → Roles in ACC). The importer reads the roles and decomposes three-segment ACC role names (e.g., Employer - General - Civil) back into their L1, L2, and L3 parts, populating the three columns automatically.

AI-assisted role restructuring

Roles that don't follow the 3-level Party - Function - Discipline format aren't lost — they're listed as non-standard roles with an option to restructure them using AI.

1. After loading a CSV, expand the Non-Standard Roles section.
2. Select the roles you want to restructure (Ctrl+click to toggle, Shift+click for ranges, or use Select all). Up to 100 roles can be processed at once.
3. Click AI: Restructure — Foreman sends the role names to AI along with your existing L1/L2/L3 values for context.
4. Review the suggestions in an editable table. Each row shows the original name, suggested Party/Function/Discipline, and a confidence indicator (High/Medium/Low). Edit any value inline before accepting.
5. New values that don't exist in your current matrix are highlighted with a new badge.
6. Click Apply Selected to merge the restructured roles into your matrix.

AI suggestions

The Suggest Values button opens a dialog where you describe your project (sector, scale, type). The AI generates a tailored set of L1, L2, and L3 values. You can review each suggestion and choose which ones to accept.