User import
A Sentra admin can create or update many accounts at once from a CSV file, including roles in your app. This page is for app owners who prepare the file together with a Sentra admin.
Before you start
Only a Sentra admin can run an import. As the app owner, you prepare the file and receive the result.
- Create the roles in your app’s Peran aplikasi (app roles) catalog in the console, for example
siswaandpengajar. - Give the Sentra admin your app’s App ID (
app_…) and the role keys. - Prepare a CSV file in the format below, or start from the template.
File format
- CSV encoded as UTF-8. A BOM is fine.
- Separated by commas or semicolons. Sentra picks the separator from the header row.
- The first row holds the column names. Columns can come in any order, and unused ones can be left out, except
nameand one ofusernameoremail. - At most 2,000 data rows and 2 MB. Blank lines are skipped.
- An unknown or repeated column rejects the whole file.
| Column | Required | Content |
|---|---|---|
username | Username or email | 3–64 characters: lowercase letters, digits, dot, underscore or hyphen. Digits only is allowed. Uppercase becomes lowercase. |
email | Username or email | Optional when there’s a username. Without a username, one is generated from the email, the same way as at sign-up. |
name | Yes | Full name, at most 120 characters. |
app_id | With role | Your app’s App ID. |
role | With app_id | A role key from that app’s catalog. |
user_type | No | The key of an active user type. New accounts without one get the default type (usually umum). |
A person with several roles takes several rows, one per role. Rows with the same username (or the same email when there’s no username) count as one account, so their name and email must match across those rows.
username,email,name,app_id,role,user_type
2024001,,Budi Santoso,app_9fk2mq7xlr4tzw8nb3vh5cyd,siswa,
2024001,,Budi Santoso,app_9fk2mq7xlr4tzw8nb3vh5cyd,asisten,
,rina.putri@contoh.id,Rina Putri,,,
nur.aini,nur.aini@contoh.id,Nur Aini,app_9fk2mq7xlr4tzw8nb3vh5cyd,pengajar,Create and Update modes
The admin picks a mode when uploading (Buat or Perbarui in the admin screen). Accounts are matched by username when given, otherwise by email.
| Situation | Create | Update |
|---|---|---|
| No account yet | New | New |
| Account exists, made by an admin or an import | Blocked | Updated |
| Account exists, registered by its owner | Blocked | Blocked |
| Invalid row, or the email belongs to another account | Failed | Failed |
- New: the account is created with a random initial password, the type from the file or the default type, and the app roles from the file.
- Updated: the name comes from the file, and so does the email when it’s filled in; app roles and user types are added, never removed. The password isn’t changed.
- Blocked: the account isn’t changed. In Create mode, run again in Update mode if you do want to change it. Accounts their owners registered themselves are never changed by an import.
- Failed: the row has a problem, such as an invalid username or email, an empty name, an unknown
app_id, a role that isn’t in the catalog, or an unknown user type. The reason is given per account.
Preview, then confirm
- Upload. Sentra checks every row without changing any account, then shows a summary of new, updated, blocked and failed accounts with the reasons.
- Confirm. The admin reads the summary and confirms. A preview lasts 30 minutes; after that the file must be uploaded again.
At confirmation every account is checked again, because data may have changed since the preview. Accounts whose outcome changed are marked in the result.
The result
After confirming, the admin downloads the result as a CSV, one row per account:
username,email,name,sentra_id,outcome,initial_password,note
2024001,,Budi Santoso,8f3a1c52-7d0e-4b6a-9c21-5e7f0a3d9b14,new,Hq7m-Pk4r-T9zw,
rina.putri,rina.putri@contoh.id,Rina Putri,,blocked,,Akun sudah ada. Jalankan ulang dengan mode Perbarui untuk mengubahnya.| Column | Content |
|---|---|
username | The account’s username, including one generated from the email. |
email, name | From the file. |
sentra_id | The account ID for new and updated accounts. Empty for blocked and failed ones. |
outcome | new, updated, blocked or failed. |
initial_password | The initial password of a new account. |
note | The reason for a blocked or failed account (in Indonesian). |
Later, the admin can download the Sentra ID list (daftar Sentra ID) from that import’s page at any time: the same columns, without initial_password. That’s the file you use in your app. Don’t keep the file with passwords in your app.
Need the sentra_id of accounts blocked in Create mode? Run the same file in Update mode: every account found that an admin or import created shows as updated, with its sentra_id. Accounts their owners registered themselves stay blocked; link those when the user signs in.
Link your existing users
Store the sentra_id from the Sentra ID list on your local users, so they’re recognised on their first sign-in. Match rows to local users on data you wrote into the import file yourself, such as the username. An Artisan command example:
// routes/console.php
use App\Models\User;
use Illuminate\Support\Facades\Artisan;
Artisan::command('sentra:link {file}', function (string $file) {
$csv = new SplFileObject($file);
$csv->setFlags(SplFileObject::READ_CSV | SplFileObject::SKIP_EMPTY | SplFileObject::READ_AHEAD);
$header = null;
$linked = 0;
foreach ($csv as $row) {
if ($header === null) {
$header = array_map(fn ($h) => trim($h, "\u{FEFF} "), $row);
continue;
}
$r = array_combine($header, $row);
if ($r['sentra_id'] === '') {
continue;
}
$linked += User::where('username', $r['username'])
->whereNull('sentra_id')
->update(['sentra_id' => $r['sentra_id']]);
}
$this->info("{$linked} users linked.");
});php artisan sentra:link storage/app/import-sentra-id.csvFrom then on your app looks users up by sentra_id only, as in User data.