Administration Guide
Complete reference for platform administrators: user management, roles, API keys, data operations, GDPR compliance, and system health monitoring.
User Management
All user accounts are managed from Settings → Users. Administrators can invite new users, adjust account status, and assign roles and territories.
Inviting a New User
- 1Navigate to Settings → Users → Invite User.
- 2Enter the user's email address.
- 3Select a role: ADMIN, MANAGER, REP, or READONLY.
- 4For REPs, select the assigned territory.
- 5Click Send Invitation. The user receives an email with a temporary password link valid for 72 hours.
Account States
User can log in and use all features permitted by their role.
Invite sent but the user has not yet completed first login.
Account is blocked. The user cannot log in. No data is deleted.
Deactivating a user (Settings → Users → toggle Active to off) immediately blocks login access. All historical data created by the user is preserved and remains visible to managers and administrators.
Role Assignment
FieldOrchestrator uses four fixed roles. Roles determine which screens a user can access, what actions they can perform, and which data is visible to them.
Full platform access. Manage users, API keys, run GDPR operations, and access all territories. The only role permitted to perform compliance operations.
- Manage users and roles
- Create and revoke API keys
- Run GDPR erasure workflows
- Access all territories
- Configure system settings
Operational management access. View all territories in scope, generate and approve routes, manage HCPs, and access analytics. Cannot manage users or run compliance operations.
- View territories in assigned scope
- Generate and approve route plans
- Manage HCP records
- Access analytics and reports
- Configure territory scheduling
Mobile-only field access for assigned territory. Check in and out of visits, capture visit outcomes, and review personal visit history. No web dashboard or data mutation capabilities outside of visit capture.
- GPS-verified visit check-in and checkout
- Visit outcome and product capture
- Personal visit history
- Offline mode with automatic sync
Read-only access to the dashboard and reports. Suitable for medical directors, finance controllers, or compliance officers who need visibility without the ability to modify data.
- View dashboards and KPI tiles
- Access generated reports
- Export data for offline review
API Key Management
API keys enable system-to-system integrations — such as ERP sell-out feeds and automated data pipelines — without exposing user credentials. Each key is scoped to a single set of operations.
Creating a Key
- 1Navigate to Settings → API Keys → Create API Key.
- 2Give the key a descriptive name (e.g. "Sage X3 Sell-Out Nightly").
- 3Select a scope: INGEST_SALES, SYNC_VISITS, or WORKFLOW_LOG.
- 4Click Create. The key is displayed once — copy it and store it immediately in your secrets manager.
The API key value is shown only once at creation time. If you lose the key, you must rotate it to obtain a new one. The old key remains valid for 24 hours after rotation to allow a seamless handover in running systems.
Available Scopes
| Scope | Authorized Operations | Typical Use |
|---|---|---|
INGEST_SALES | Import sell-out data from ERP or pharmacy data pipelines | Automated nightly ERP export feed |
SYNC_VISITS | Upload offline visit records from mobile devices to the platform | Mobile app background sync agent |
WORKFLOW_LOG | Write workflow audit events from external compliance or automation systems | External LIMS or document management integration |
Rotate a Key
Open the key detail view → click Rotate. A new key is issued immediately. The previous key remains valid for 24 hours.
Revoke a Key
Open the key detail view → click Revoke. The key is invalidated immediately. Any system using the revoked key will receive HTTP 401 errors.
Product Catalog
The product catalog defines the portfolio available to field representatives during visit capture. Navigate to Products to manage the list.
Adding a Product
- Name (displayed to field reps)
- Product code (used in sell-out data matching)
- Therapeutic area
- Active ingredient
Deactivating a Product
- Toggle the product to Inactive in the product detail view
- Inactive products no longer appear in new visit forms
- All historical visit records referencing the product are preserved
- Sell-out data already imported for the product remains intact
Sell-Out Data Import
Sell-out data is the foundation of the Visit Impact Score scoring and pre-call intelligence modules. Navigate to Administration → Sales Data → Import for manual uploads.
Supported Formats
CSV and XLSX files are accepted.
Required Columns
| Column | Type | Description |
|---|---|---|
hcp_code | string | HCP identifier — must match an existing HCP code in the platform |
product_code | string | Product identifier — must match a product code in the catalog |
brick_code | string | Geographic brick code for the sales area |
period | YYYY-MM | Reporting month in ISO year-month format |
quantity | integer | Units sold during the period |
value_tnd | decimal | Revenue in local currency for the period |
The system validates data quality on upload. Any rows with missing required columns, unrecognised codes, or invalid formats are listed with their row numbers in the validation report — the valid rows are still imported. For automated imports, use the INGEST_SALES-scoped API key (see API Reference).
GDPR Operations
FieldOrchestrator includes a full GDPR compliance toolchain accessible from Administration → Compliance → GDPR. All operations generate immutable, hash-chained audit records.
Erasure Request
Submit a dual-control erasure request for an HCP. The workflow requires three authorized users: a first to submit the request, a second ADMIN to approve it, and a third to execute the erasure. All three steps are logged with timestamps and user identities. This three-party control prevents unauthorized or accidental erasure of medical data.
Legal Hold
Flag an HCP record as under legal hold. While on hold, any erasure request for that record is automatically blocked. The hold must be explicitly released by an ADMIN before erasure can proceed. Legal holds are logged and cannot be silently removed.
Audit Log
A full chronological record of all data access and mutation events across the platform. Filter by user, date range, and action type. Export to CSV or XLSX for external compliance reporting. The audit log itself is append-only and cannot be modified or deleted.
Cryptographic Evidence Chain
Every GDPR operation (erasure request, approval, execution, legal hold, and hold release) is appended to an immutable SHA-256 hash-chained Evidence Chain. Each record includes the previous record's hash, making any retrospective tampering detectable. The chain is stored independently of the main audit log and can be exported as a signed JSON file for regulatory submission. Legal holds automatically block all erasure attempts — an ADMIN must explicitly release the hold before the three-party erasure workflow can proceed.
Data Retention
Visit logs and associated data are retained according to your organisation's configured retention window. The default window is 36 months.
Default Window
36 months
Applies unless overridden in Settings → Compliance → Data Retention.
Purge Schedule
Nightly
Records outside the retention window are purged automatically during the nightly maintenance cycle.
Configuration
Settings → Compliance
Retention window can be extended or shortened by an ADMIN. Changes apply to future purge cycles.
System Health
Administration → System Health provides a real-time overview of all platform service components and recent operational events.
Service Status Indicators
- Database connectivity
- AI intelligence engine
- Route optimization engine
- Email delivery service
Operational Monitoring
- Last successful data sync timestamps per integration
- Failed background job alerts with error messages
- API rate limit consumption per key
- Nightly maintenance cycle status
Need assistance?
Our support team is available Monday–Friday, 08:00–18:00 CET.