Quickstart

Use the Dataload tab in Settings for bulk CSV imports. For advanced server-side tasks, use the Python-based Management CLI.

In-Depth

Servantium provides robust tools for moving data in and out of the system, whether you’re performing a one-time migration or regular bulk updates.

Dataloads (CSV Import)

The Dataload system is the primary way for administrators to import historical engagements, client lists, or resource pools.

Dynamic Formulas

You can transform or combine CSV column data during import using string interpolation formulas.

• Syntax: Use single braces for column substitution (e.g., {First Name} {Last Name}). You can also slice strings using slice notation (e.g., {Account ID[0:15]} to extract the first 15 characters).
• Fallbacks: Use the pipe character | to provide fallback expressions if a value is empty (e.g., {Primary Email}|{Secondary Email}|No Email). The system evaluates from left to right and returns the first non-empty result.
• External IDs: If you need to generate a unique composite ID to prevent duplicates, you can use formulas in the external ID mapping column.

Cascade Syncs

When importing data, you can configure your mapping to automatically trigger outbound integration syncs when specific fields change. By defining a cascades array in your mapping, the system monitors imported records for changes to the specified onFieldsChanged fields. If a change is detected, it automatically dispatches a targeted integration sync for that specific record to your external system (like Salesforce).

Error Reporting and Auditing

Every row in your import is tracked. Results and specific failure reasons are recorded in the dataload_results collection, allowing you to fix errors in your source file and re-import only the failed rows.

Parent Dependencies

If an imported record references a parent document that has not been created yet, the import will not fail. Instead, its status automatically changes to Pending Parent Document. Once the missing parent record is created or imported, the system detects it and automatically resumes processing for the waiting row.

Management CLI

For system operators and developers, the Management CLI (management_tasks/cli.py and other internal scripts) provides direct access to backend operations:

• analyze_session.py: Parse and analyze events from a fetched Vertex AI Reasoning Engine session JSON file to trace AI agent reasoning steps.
• backfill_approval_history_count.py: Recalculate and synchronize the approval_history_count on target entities from historical approval requests. Use --execute to apply changes to Firestore, and optionally filter by organization using --org-id.
• create_org.py: Provision new organizations and link administrative owners.
• delete_session.py: Cancel or delete a stuck AI agent session from Google Cloud Vertex AI. Use --session_id to target a specific session, and optionally --project to specify the environment.
• export_collection_to_csv.py: Export selected properties from a Firestore collection group to a CSV file. Use --collection_group, --org_id, and --properties to configure the output. By default, this connects to local emulators. To target a live database, use --project and the --prod flag.
• fetch_direct_session.py: Fetch the raw JSON transcript of an AI agent session directly from the Google Cloud Vertex AI Reasoning Engine. Accepts parameters for engine ID, session ID, output path, and target Google Cloud project environment.
• force_sync_collection.py: Force an outgoing integration sync on all documents in a specific collection, with an optional --since date filter. By default, this connects to local Firebase emulators. To target a live database, use --project to specify the Google Cloud environment and the --prod flag to explicitly authorize connecting to production.
• get_raw_transcript.py: Retrieve the raw JSON transcript of a specific Vertex AI agent session for deep debugging. Use <session_id> alongside optional [app_name] and [user_id].
• get_transcript.py: Fetch and parse a human-readable event transcript of an AI agent session (like the Engagement Template generator) to diagnose reasoning paths. The script automatically fetches credentials, searches across matching engines, and saves the output to a local .txt file.
• load_users.py: Bulk provision and invite user accounts from a CSV list.
• migrate_entity_closure.py: Export and import complete, schema-driven entity closures (like an engagement and all of its nested quotes and tasks) to or from a JSONL file. It automatically traverses your schema, sorts dependencies, and handles tenant isolation. Use export or import with --org_id and --user_id.
• migrate_project_plan_items_completed.py: Bulk update project plan items with 100% completion to the “Completed” status. Use --execute to apply changes, and optionally filter by --engagement-id or --plan-id.
• migrate_quotes.py: Perform structural data migrations across all quotes within an organization.
• reconcile_actuals.py: Wipe and re-fetch actual hours for specific out-of-sync projects from an external system. Use --external_ids to target project Salesforce IDs, alongside --org, --integration_id, and --mapping_id. The script automatically fetches Salesforce credentials directly from Google Cloud Secret Manager.
• reindex_algolia.py: Force a full synchronization of your Firestore data to the Algolia search index.
• run_agent_local.py: Run an ADK agent locally for testing and debugging against live Cloud Firestore. It enforces 4 mandatory parameters: agent path, organization ID (--org-id), target record ID (--template-id, --quote-id, --engagement-id, or --snippet-id), and instructions (--prompt). It features real-time task log monitoring, 5 Whys Root Cause Analysis support, and verifies post-run document writes across all template types (engagement, quote, document), data specs, and snippets. Use --project to explicitly target a specific Google Cloud project environment.
• update_algolia_security_tags.py: Backfill security tags for existing Algolia records to enforce Attribute-Based Access Control (ABAC) search filtering.
• zero_out_hours.py: Bulk zero out hours for specific Resource Plan assignments. Use --external_ids to target plans, and optionally filter by organization using the --org parameter.

Related

• Integrations
• Data Dictionaries