Admin Handbook

You're a Tenant Admin, Platform Admin, or Super Admin. This handbook covers tenant setup, user and role management, escalation configuration, integrations, notifications, and audit.

Roles covered here

• Tenant Admin — full control within your tenant organization
• Platform Admin — settings, user management, integrations (organization scope)
• Super Admin — multi-tenant platform administration

Everyone else should use their role-specific handbook and ignore most of this page.

Your sidebar

• Dashboard
• Admin — Admin Dashboard, Tenants (Super Admin only), Users, Roles, Settings, Audit Logs
• All operational modules (you have access to everything)

Tenant bootstrapping

First time standing up a tenant? Follow this sequence:

1. Tenant creation (Super Admin only) — Sidebar > Admin > Tenants > New Tenant. Name, subdomain, plan (Free / Starter / Professional / Enterprise), max quotas.
2. General settings — Sidebar > Admin > Settings > General:
   • Organization name, logo, primary contact
   • Default currency (AED / SAR / QAR / USD)
   • Default timezone
   • Default locale (en / ar)
3. Security settings — Settings > Security:
   • MFA enforcement (optional / required for admins / required for all)
   • Password policy (minimum length, complexity)
   • Session limit (concurrent sessions per user)
   • Lockout threshold (failed attempts → lockout, lockout duration)
4. Notifications settings — Settings > Notifications:
   • Default channels enabled
   • SMTP configuration (for email)
   • SMS gateway (if using SMS)
   • Push notification configuration
5. First users — see below.
6. First building — create the first property and building so there's somewhere to invite residents and assign work orders.

Users

Creating a user

1. Sidebar > Admin > Users > Create User.
2. Fill in: name, email, initial role.
3. Choose invitation method:
   • Self-register — they get an email with a link to set their password.
   • Admin-set — you set an initial password and hand it over securely.
4. Optionally assign building scopes now or later (see ABAC below).
5. Save. The user receives the invitation.

Editing a user

On the user list, click a row. From the detail page:

• Change name, email, active status (active / suspended / deactivated)
• Add or remove roles
• Add or remove building-scoped assignments
• Reset password (sends a reset link to their email)
• Unlock account (if locked due to failed attempts)
• Force sign-out from all sessions
• View activity log (audit trail scoped to this user)

Bulk import

For large user loads, Users > Import CSV. Download the template, fill rows, upload. Validation shows errors before commit. Once clean, commit the import.

Roles and permissions

Built-in roles

ArkanPM ships with 11 built-in roles:

Creating a custom role

1. Sidebar > Admin > Roles > Create Role.
2. Name it and add a description.
3. Work through the permission matrix:
   • For each module (Work Orders, Leases, Assets, etc.), tick the allowed actions: View, Create, Update, Delete, Approve, Close, etc.
   • Some modules have fine-grained controls (e.g., View Financials separate from View Operational).
4. Save. The role is available to assign to users.

Attribute-based access (ABAC)

On top of a role, you can scope a user to specific buildings, floors, or units:

1. On the user detail page, click Add Scope.
2. Pick the scope type (Building / Floor / Unit).
3. Pick specific records they should access.
4. Optionally set a time window — the scope is only active during that window (e.g., a temp worker with access only for Q2).
5. Save.

When a user with a scope signs in, their sidebar, lists, and dashboards only show records matching the scope. ABAC also controls financial masking — you can mark a role to have specific financial fields hidden (e.g., Building Manager sees occupancy but not rent amounts).

Escalation rules

Default escalation levels (tenant-wide, adjustable):

• Level 1 — assigned technician and a backup tech
• Level 2 — Building Manager
• Level 3 — Facility Manager leadership

Configuring rules

1. Sidebar > Admin > Settings > Escalation Rules > New Rule.
2. Trigger — pick one:
   • SLA breach — when response or resolution timer runs out
   • No response — no acknowledgement within N minutes of assignment
   • Stale — in progress for longer than N hours without a status update
3. Scope — applies to all, or filtered by priority, category, building.
4. Timing — how soon after trigger does each level fire (e.g., Level 1 at trigger, Level 2 at +15 min, Level 3 at +30 min).
5. Recipients — either a role, a specific user, or "assigned+backup".
6. Channels — in-app, email, SMS, push.
7. Save.

Rules run continuously. You can pause a rule without deleting it.

Integrations

Overview page at Sidebar > Admin > Settings > Integrations.

Six integration types:

Registering an integration

1. Click Add Integration.
2. Pick the type.
3. Fill in: name, endpoint URL, credentials (API key or OAuth), sync frequency.
4. Test the connection.
5. Enable.

Each integration has a log tab showing every call with status, response time, and error details (if any). This is your first stop when a sync looks off.

Arkan Handover integration

Special-purpose integration for receiving handover records from the Arkan construction platform:

1. Settings > Integrations > Arkan Handover > Configure.
2. Paste the shared secret from the construction platform.
3. Choose which data flows in: defects, snagging items, warranty records.
4. Map: which building receives data, which asset categories auto-create, which work-order type spawns for defects.
5. Enable.

Once enabled, handover records stream into ArkanPM as they're created on the construction side. Each record is an auditable line in the integration log.

See the Integrations Reference for the full integration catalog.

Webhooks

Outbound events — ArkanPM notifies an external system when something happens.

Registering a webhook

1. Sidebar > Admin > Settings > Webhooks > New Webhook.
2. Configure:
   • Name (e.g., "Slack notifications for emergencies")
   • Target URL (the external endpoint)
   • Events subscribed to — pick from the catalog: work_order.created, work_order.completed, lease.activated, inspection.failed, etc.
   • Authentication secret — ArkanPM uses it to sign payloads; your endpoint verifies the signature
   • Custom headers (optional)
   • Timeout (default 30 seconds)
   • Retry policy (max retries, backoff strategy)
3. Save. The webhook is live.

Webhook logs

Every delivery attempt is logged with: timestamp, HTTP status, response body, duration, attempt number. Failed deliveries retry on the schedule until the retry budget is exhausted — then alert.

See Integrations Reference for the event catalog and payload shapes.

Notification templates

ArkanPM ships with templates for every notification type. You can edit them.

1. Sidebar > Admin > Settings > Notification Templates.
2. Pick a template (e.g., "Work Order Assigned").
3. Edit the subject and body. Use variables like {{work_order.number}}, {{assigned_to.name}}, {{building.name}}. Template preview on the right shows a rendered example.
4. Separate templates per channel (in-app / email / SMS) and per language (en / ar).
5. Save.

Audit logs

Every create / update / delete / login / logout is logged.

1. Sidebar > Admin > Audit Logs.
2. Filter by user, entity type (work order, lease, user, etc.), action, date range.
3. Click a row to see the change diff — old vs. new values side-by-side (JSON format).
4. Export filtered results as CSV.

Point-in-time recovery: for any entity, you can reconstruct its state at any past timestamp by replaying the audit log. Support can help you pull this if needed.

Data retention

Settings > Data Retention:

• Per-entity retention policies (work orders, leases, documents, etc.)
• Soft-delete preservation duration
• Archive thresholds (when data moves to cold storage)

Be careful — these settings affect how long data is recoverable. Changes to retention should be coordinated with compliance and legal.

Tenant lifecycle (Super Admin)

Suspending a tenant

A suspended tenant's users are locked out at the authentication layer. Data is preserved. Useful for non-payment or security events.

1. Sidebar > Admin > Tenants > [tenant] > Suspend.
2. Enter a reason.
3. Confirm. All users are signed out immediately.

Terminating a tenant

Final state. Data retention policy takes over — data is archived per your policy window, then purged.

1. Tenants > [tenant] > Terminate.
2. Strong confirmation required.
3. Tenant moves to Terminated. Data is marked for archival / eventual deletion.

Monitoring background jobs

Seven background processors run continuously:

Sidebar > Admin > Settings > Background Jobs shows each processor's status, last run, next scheduled run, and recent errors. Restart or pause a processor if you have to — but coordinate with support first.

Day-to-day admin checklist

Weekly:

• Review audit logs for anomalies (unusual user activity, bulk deletes)
• Check integration logs for failures
• Review pending user invitations — nudge anyone who hasn't accepted

Monthly:

• Review role assignments — any temps or contractors who left?
• Review webhook failure rates — any endpoints consistently failing?
• Review escalation history — are rules firing too often? Too rarely?

Quarterly:

• Full user audit — active users vs. licensed seats
• Permission review — any custom roles drifting from original intent?
• Retention policy review — anything that should be extended or shortened?

Related handbooks:

• Integrations Reference → — full integration catalog and event list
• Security & Audit → — deep dive on auth, sessions, audit, retention
• Troubleshooting & FAQ →