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.

  1. Create the roles in your app’s Peran aplikasi (app roles) catalog in the console, for example siswa and pengajar.
  2. Give the Sentra admin your app’s App ID (app_…) and the role keys.
  3. 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 name and one of username or email.
  • At most 2,000 data rows and 2 MB. Blank lines are skipped.
  • An unknown or repeated column rejects the whole file.
ColumnRequiredContent
usernameUsername or email3–64 characters: lowercase letters, digits, dot, underscore or hyphen. Digits only is allowed. Uppercase becomes lowercase.
emailUsername or emailOptional when there’s a username. Without a username, one is generated from the email, the same way as at sign-up.
nameYesFull name, at most 120 characters.
app_idWith roleYour app’s App ID.
roleWith app_idA role key from that app’s catalog.
user_typeNoThe 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.

SituationCreateUpdate
No account yetNewNew
Account exists, made by an admin or an importBlockedUpdated
Account exists, registered by its ownerBlockedBlocked
Invalid row, or the email belongs to another accountFailedFailed
  • 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

  1. Upload. Sentra checks every row without changing any account, then shows a summary of new, updated, blocked and failed accounts with the reasons.
  2. 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.
ColumnContent
usernameThe account’s username, including one generated from the email.
email, nameFrom the file.
sentra_idThe account ID for new and updated accounts. Empty for blocked and failed ones.
outcomenew, updated, blocked or failed.
initial_passwordThe initial password of a new account.
noteThe reason for a blocked or failed account (in Indonesian).
Initial passwords exist only in the first download, right after confirming. Sentra doesn’t store them and can’t show them again. They’re valid for 7 days and must be changed at the user’s first sign-in. If one is lost, the admin resets that account’s password.

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.

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.csv

From then on your app looks users up by sentra_id only, as in User data.