Skip to content
roleALPHA Docs

Importing from CSV or Excel

Anyone moving an existing structure into roleALPHA does not want to type it in one record at a time. The importer takes over many records at once — entities (people, roles, projects …) as well as relationships between them.

How to get there

Section titled “How to get there”

On every module page, next to “New …”, sits the “Import” button. It brings the module along: the object type is already pre-selected in the wizard.

The button only appears for administrators — an import may create and change many records at once, and that is an admin task.

The four steps

Section titled “The four steps”
  1. Select — entities or relationships, object type, file (.csv, .xlsx). If an Excel file has several sheets, roleALPHA asks which one you mean.
  2. Map — which column of your file fills which field. What you do not map stays empty; required fields of the object type must be included.
  3. Check — roleALPHA reads the file through and shows what would be created and what would change, before anything happens. Faulty rows are named individually.
  4. Import — the records are created as drafts.

Recognising what exists instead of duplicating it

Section titled “Recognising what exists instead of duplicating it”

So that a second import does not create everything a second time, roleALPHA needs a marker by which it recognises a record:

  • Customer ID (recommended) — your own number from the source system.
  • UUID — roleALPHA’s internal identifier. Only useful if you exported it beforehand.

Rows with a known marker are changed, unknown ones are created. Choosing the wrong marker produces duplicates — which is why the choice sits in the first step and not at the end.

Importing relationships

Section titled “Importing relationships”

A relationship row names both ends and the relationship type. The ends are resolved via customer ID or UUID; roleALPHA checks whether the type is intended for that pair at all. If it does not fit, the row is named rather than silently linked differently.

What the import does NOT do

Section titled “What the import does NOT do”
  • It does not publish on its own. Everything is created as a draft and goes through approval like any other change.
  • It deletes nothing unless you switch that on explicitly.
  • It bypasses no permissions. If you lack write access in a module, the row fails — the import is not a side entrance.

Large files

Section titled “Large files”

The server processes 500 records per request; larger imports are split automatically, so you do not have to care. Progress is visible while it runs.

If you want to try a large import without consequences first, assign it to a scenario: the drafts then sit together and can be approved or discarded as a group.

Section titled “Related”