Frequently Asked Questions

What do I do if the app shows "Offline" and I cannot check in?

You can still check in normally — all visit data is stored locally on your device. When you regain connectivity, your data syncs automatically in the background. No manual action is required. You will see a sync confirmation notification once the upload completes.

Why is my route for today showing "No route available"?

Your manager has not yet approved a route plan for today. Route plans are generated and approved by your manager before they become visible on your device. Contact your manager to review and approve the route. Once approved, pull down to refresh the app and the route will appear.

Can I check in if I'm not physically near the HCP's location?

The system requires GPS proximity confirmation for standard check-in. If you are at the correct location but the system indicates you are out of range — which can happen in dense urban areas or with building signal interference — tap "Override". The visit will be logged normally but flagged with a proximity override note for audit purposes. This flag is visible to your manager and compliance team.

How do I change the app language?

Go to the mobile menu (hamburger icon, top-left) → Profile → Language. Select English or French. The change applies immediately across all screens — no restart is needed.

Can I add an HCP visit that is not on my planned route?

Ad-hoc visits outside of your approved route are not supported through the mobile app. This is a compliance design decision — unplanned visits cannot be GPS-verified and check-in confirmed in the same way as planned visits. If you need to visit an HCP not on your route, contact your manager, who can update or re-optimise your route to include the additional stop. The updated route is pushed to your device within seconds of approval.

What does the proximity override flag on my visit record mean?

The standard GPS check-in requires you to be within 200 metres of the HCP's registered address. If the system detects that you are outside this 200 m radius — which can happen in dense urban areas with poor satellite signal, inside large hospital buildings, or when an HCP's address is slightly inaccurate — you can tap "Override" to complete the check-in. The override creates an audit flag on the visit record that is visible to your manager and the compliance team. It is not a penalty and does not affect your visit count or compliance metrics — it simply records that the check-in was performed outside the standard proximity radius, allowing the compliance team to distinguish genuine field visits from potential data quality issues.

Why was a route not generated for one of my representatives?

Route generation requires two conditions to be met: (1) the representative must have an approved territory assignment, and (2) there must be at least one eligible HCP in the territory — meaning an HCP who has not been visited more recently than the configured minimum visit interval. Check the representative's territory assignment in Settings → Users → [Rep] and review the HCP visit history for the territory to confirm eligibility.

How do I change the workday hours for route optimization?

Navigate to Territories → [Territory name] → Settings → Scheduling. From this screen you can configure workday start and end times, lunch break duration, and travel speed assumptions for the territory. Changes apply to the next route generation cycle. Previously approved routes are not retroactively affected.

A representative's route is already ACTIVE — can I still change it?

Yes. Click the route in the Routes view → Re-optimize. The system recomputes the remaining stops using the current position of the representative as the new starting point. Completed visits are preserved in full. The updated route is pushed to the representative's device within seconds of approval. This is useful if a visit was cancelled or if an urgent HCP needs to be added.

How is the equity score calculated?

The equity score measures workload balance across territories using a weighted combination of HCP count and strategic value (tier weighting). A score of 90 or above indicates excellent balance — no immediate action is needed. Scores between 75 and 89 are acceptable but worth monitoring quarterly. Scores below 75 indicate a rebalancing session is beneficial. Scores below 60 indicate critical imbalance requiring prompt attention. The score is recalculated automatically whenever territory assignments or HCP records are modified.

How do I approve multiple routes at once?

From the Routes section, switch to the Calendar view. Select multiple DRAFT routes by clicking the checkbox next to each route card. Once your selection is complete, click "Approve Selected" in the action bar that appears at the bottom of the screen. All selected routes are approved simultaneously and pushed to the corresponding representatives' devices.

What does a HCP's Visit Impact Score data quality grade (A/B/C/D/FAIL) mean?

The Visit Impact Score data quality grade reflects how statistically reliable the ROI score is for a given HCP. Grade A means the score is based on strong evidence — 10 or more visits with a full matched control group and product seasonality data — and can be used with confidence for targeting and routing decisions. Grade B (6–9 visits, partial data) is directionally reliable for planning purposes. Grade C (3–5 visits) provides a signal but should not be the sole basis for major targeting changes. Grade D (1–2 visits) is preliminary — treat with significant caution. Grade FAIL means no statistically valid score could be computed — this HCP has no measurable sell-out correlation yet. Grades improve automatically as more visit and sell-out data accumulates over time; a newly onboarded territory typically reaches Grade B within 2–3 months of active sell-out ingestion.

How do HCP access constraints affect route generation for a territory?

HCP access constraints are enforced as hard constraints during route generation. If an HCP has consultation hours configured — for example, available only Monday 09:00–12:00 and Wednesday 14:00–17:00 — the route optimizer will only include that HCP's stop on days and within time slots that fall within those windows. Stops that cannot fit within any available window on the requested date are deferred and flagged in the generation report. If an HCP is marked as requiring an appointment with a minimum lead time (e.g. 48 hours), the optimizer will not schedule them unless the planning date provides sufficient lead time. To configure access constraints for an HCP: open the HCP record → Access Constraints tab → add day-of-week rules with time windows, appointment requirements, and lead hours. Changes take effect at the next route generation cycle for that territory.

A user was deactivated by mistake — how do I reactivate them?

Navigate to Settings → Users, find the user using the search field, open their profile, and toggle the "Active" switch to On. The account is restored immediately — the user can log in again without any additional steps. If the user's session token has expired, they will simply need to log in again with their existing credentials.

How long is visit data retained?

The default retention window is 36 months from the visit date. Records outside the retention window are automatically purged during the nightly maintenance cycle. The retention window can be adjusted in Settings → Compliance → Data Retention. Note that GDPR legal holds override the purge cycle — records under legal hold are not purged regardless of the retention window setting.

How do I run a GDPR erasure?

Navigate to Administration → Compliance → GDPR Erasure. Submit the erasure request by entering the HCP identifier and the legal basis for the erasure. A second authorized administrator must then approve the request. A third authorized user executes the final erasure. All three steps generate immutable audit records with timestamps and user identities. If the HCP is under a legal hold, the erasure request will be blocked until the hold is explicitly released by an administrator.

Can I export the audit log?

Yes. Navigate to Administration → Audit Log. Use the filters to narrow the export by date range, user, and action type. Click Export and select CSV or XLSX. The exported file contains all matching audit events with timestamps, user identities, affected record identifiers, and action descriptions. Audit log exports are themselves logged as audit events.

How do I onboard a new sales representative?

Follow these steps: (1) Navigate to Settings → Users → Invite User. Enter the email address, select the REP role, and assign the territory. (2) Click Send Invitation — the representative receives an email with a temporary password link. (3) The representative installs the mobile Progressive Web App (PWA) by opening the platform URL in their mobile browser and following the browser's "Add to Home Screen" prompt. (4) After first login, the representative can immediately begin receiving route plans and checking in to visits.

What outbound network connections does the on-premises installation require?

Exactly one: HTTPS (port 443) outbound to engine.fieldorchestrator.symbiowave.com. This is the FieldOrchestrator Engine API endpoint. No inbound connections from SymbioWave are required. All data transfer is initiated by the on-premises installation. Your firewall policy only needs to permit this single outbound HTTPS destination.

How are software updates applied?

Run ./update.sh from the installation directory. The script performs the following steps automatically: pulls the latest Docker image from the SymbioWave registry, applies any pending database schema migrations, and performs a rolling restart of the application containers to achieve zero downtime. Always run ./backup.sh before updating to ensure you have a recovery point. Automated update scheduling is planned for version 1.1.

What credentials does the on-premises installation need?

Only the FIELDORCHESTRATOR_ENGINE_API_KEY, provided by SymbioWave during on-boarding. No cloud provider accounts, AI service API keys, mapping service credentials, or other external service accounts are required. This single key grants access to all engine capabilities (route optimization, AI intelligence, analytics processing) through the FieldOrchestrator Engine API.

How is data backed up?

Run ./backup.sh to create a timestamped database dump in your configured backup directory. The script can be scheduled via cron for automated daily backups. For off-site backup, you can configure a cloud storage bucket destination in your installation's environment configuration file. Consult your on-premises installation package for the full backup configuration reference.

What is the minimum hardware specification?

For deployments serving up to 50 concurrent users: 4 vCPU, 8 GB RAM, and 100 GB SSD storage (NVMe recommended). For larger deployments — more than 50 users, multiple territories, or high-frequency sell-out data imports — consult your SymbioWave implementation engineer for a sized recommendation. Full specifications are documented in HARDWARE_REQUIREMENTS.md included in your on-premises installation package.

What is Visit Impact Score and how does it measure the impact of a visit?

Visit Impact Score — Closed-Loop Prescription Intelligence — quantifies the incremental prescribing lift attributable to a representative's visit by applying Difference-in-Differences (DiD) econometrics, a method widely used in academic and policy research to isolate causal effects in non-experimental settings (Ashenfelter & Card, 1985; Card & Krueger, 1994). For each HCP, the platform compares their brick-level sell-out trajectory before and after a visit (the treated group) against a matched control group of HCPs in the same urbanisation class who received no visit during the same window. The difference between the two trajectories isolates the visit's contribution from underlying market trends. Raw percentage lifts are then log-compressed (Box & Cox, 1964) to prevent extreme outliers from distorting rankings, and a diminishing-returns frequency decay is applied — reflecting the well-documented concave relationship between call frequency and prescribing response (Szilagyi, 1991; Nair, Manchanda & Bhatia, 2010). The resulting Visit Impact Score Score (0–100) represents the HCP's relative commercial responsiveness to field visits.

What is Priority Score and how does it rank HCPs for a representative?

Priority Score — the Engagement Scoring Engine — is a multi-dimensional HCP prioritisation model that estimates the expected commercial value of investing a visit with each physician. It is grounded in the physician targeting and resource allocation literature developed by Zoltners, Sinha & Lorimer ("Building a Winning Sales Force", 2009) and the pharmaceutical SFE frameworks published by IQVIA (formerly IMS Health). The score aggregates seven weighted components: (1) Rx Volume Potential — the HCP's prescribing volume relative to territory peers, derived from IMS universe data or market-share indices; (2) Visit Receptivity Quality — historical completion rate, product detailing depth, and follow-up scheduling behaviour; (3) Sales Lift Correlation — the Visit Impact Score-measured link between past visits and downstream sell-out, sourced directly from the Visit Impact Score module; (4) Adoption Stage Multiplier — where the HCP sits on the innovation diffusion curve (Rogers, 1962), from Unaware through to Champion; (5) Coverage Gap Urgency — visit frequency deficit relative to target, ensuring high-priority HCPs do not go uncovered; (6) Recency Decay — exponential penalty for elapsed time since last contact, calibrated by tier; and (7) Strategic Bonus — KOL status, CNAM convention, and IMS brick weight relative to territory average. The final score (0–100) drives both route prioritisation and the daily representative task list.

How does automated route generation work? What algorithm is used?

Route generation solves a variant of the Vehicle Routing Problem with Time Windows (VRPTW) — a class of combinatorial optimisation problems first formalised by Dantzig & Ramser (1959) and extended to time-constrained variants by Solomon (1987). The platform feeds each representative's HCP priority list (ordered by Priority Score), their territory geography, visit time-window constraints, workday hours, and historical travel-time data into a two-phase solver. Phase 1 constructs an initial feasible solution using a Clark-Wright savings algorithm (Clarke & Wright, 1964). Phase 2 applies local-search metaheuristics to improve the solution within the available time budget. Real-world road travel times are computed using the Open Source Routing Machine (OSRM), which applies a Contraction Hierarchies algorithm on OpenStreetMap data for sub-second routing (Luxen & Vetter, 2011). Route quality is expressed as a Plan Score (0–100) combining visit compliance (40%), HCP coverage (35%), and visit frequency regularity (25%). The system targets the optimal balance between commercial priority (Priority Score-ranked HCPs) and operational feasibility (time, distance, workload).

What is seasonality adjustment and why does Visit Impact Score apply it?

Pharmaceutical prescribing demand is not uniform across months — respiratory products peak in January–February due to flu season, while some chronic therapy categories follow back-to-school and pre-winter patterns (IQVIA Q-MAT seasonal benchmarks). Without controlling for these patterns, a visit made in January would appear to generate more lift than an identical visit in July simply because overall market demand is higher in winter — which would be a false attribution. Visit Impact Score applies a seasonality normalisation factor derived from the SeasonalityPattern database (product and brick-specific where available, otherwise based on pharmaceutical industry benchmarks) to the control group's lift before computing the DiD estimate. This ensures the counterfactual reflects "what market-level growth would have looked like in the same month as the treatment visit" rather than in whatever month the control data was collected. This methodology mirrors the seasonal adjustment techniques used in econometrics for macroeconomic time series (X-12-ARIMA, STL decomposition) adapted to individual HCP-level data.

What is a Data Protection Officer (DPO) and is one required for FieldOrchestrator deployments?

Under the EU General Data Protection Regulation (GDPR, Regulation 2016/679), Article 37 mandates the appointment of a Data Protection Officer (DPO) for organisations whose core activities involve large-scale systematic monitoring of individuals or large-scale processing of special categories of data. Pharmaceutical companies processing HCP data — particularly prescribing behaviour, visit history, and patient interaction records — typically meet this threshold and are required to designate a DPO. The DPO must be notified to the relevant national supervisory authority (e.g. the CNIL in France, the INPDP in Tunisia). FieldOrchestrator is designed to support your DPO's obligations: all personal data processing activities are logged in the AuditLog, data subject erasure requests follow a dual-control workflow (GDPR Article 17), data retention periods are configurable and enforced automatically, and the platform generates compliance evidence suitable for GDPR Article 30 Records of Processing Activities (RoPA). If you have not yet appointed a DPO, consult your legal counsel — most pharmaceutical industry legal teams or external DPO-as-a-service providers can guide the appointment process.

How is the Visit Impact Score data quality grade determined, and when should I trust a score?

Every Visit Impact Score value carries a data quality grade (A through FAIL) that reflects the statistical reliability of the underlying DiD estimate. This follows the data confidence framework used by commercial analytics providers such as IQVIA in their physician-level reporting. Grade A (high confidence) requires at least six treatment observations — individual visits with measurable sell-out windows — and at least three matched control peers. Grade B (medium confidence) requires three or more observations and at least one peer control. Grade C (low confidence, directional) has at least one observation but sparse data. Grade D means no control group was available, making the lift estimate uncontrolled and unreliable. Grade FAIL means no valid observations exist — do not act on this score. In practice, Grades A and B are suitable for territory planning and resource allocation decisions. Grade C scores should be treated as directional signals that improve over time as more visit and sell-out data accumulates. Never override a high-Priority Score HCP deprioritisation based solely on a FAIL or D-grade Visit Impact Score.