↑↓ Navigate ↵ Select Esc Close
CHAPTER
[04]

Keeping Your System Running Smoothly

System configuration and maintenance ensure your Kora instance operates reliably, accurately reflects your organisation's operational reality, and remains optimised for your specific animal management needs. This work ranges from configuring what animal types Kora recognises to performing routine database backups that protect your organisation's irreplaceable data.

Access System Tasks at /Admin/Tasks from the Admin Dashboard.

System Tasks Overview

System Configuration & Maintenance divides into three categories:

Configuration Management - Defining how Kora works for your organisation: animal types, permissions, validation rules, medication databases

System Maintenance - Operational tasks ensuring data quality, system health, and business continuity: location updates, backups, cleanup, diagnostics

Feature Configuration - Platform capabilities enabled for your instance (managed by Kora team, not directly configurable by SuperUsers)

Each task includes clear description of what it does, when to use it, and what happens when you run it. Confirmation dialogues prevent accidental execution, and audit logs record every task run.

Configuration Management

Animal Type Configurations

What It Is: Animal type configurations define how Kora handles different species in your operations. Each animal type has specific biological characteristics, breeding parameters, health considerations, regulatory requirements, and validation rules.

When to Use:

  • Adding new animal types (when your organisation starts managing new species)
  • Expanding operations (when acquiring facilities with different animals)
  • Diversification (when farm diversifies from cattle-only to cattle plus sheep)
  • Conservation work (when adding wildlife or exotic species)
  • Initial configuration (during Kora deployment setup)

What It Does: Loads or updates animal type configuration files defining species-specific parameters. These configurations affect what fields appear when creating animal records, validation rules for age/weight/breeding dates, default settings for observations and treatments, and species-specific health monitoring parameters.

Example Scenario: Your conservation organisation starts managing endangered bird species in addition to existing mammal programmes. You load bird-specific configurations so Kora recognises avian biology, breeding patterns, and specialised care requirements.

How to Run:

  1. Access System Tasks, Configuration Management
  2. Select "Load Animal Type Configs"
  3. Review which animal types will be loaded/updated
  4. Confirm operation
  5. System loads configuration files
  6. Verify animal types now available in animal creation workflows

Safety Considerations: Loading configurations doesn't delete existing animal records, updates existing type definitions if already present, adds new types if not present, audit logged with timestamp and SuperUser ID

Permission Management

What It Is: Permission configurations define what roles can do in your Kora instance. Permissions control access to specific features, data types, and operational capabilities beyond basic role definitions.

When to Use:

  • Role refinement (when default role permissions too broad or restrictive)
  • Compliance requirements (when regulatory obligations require specific access controls)
  • Organisational policy (when your organisation has unique access governance needs)
  • Security enhancement (when implementing stricter data protection measures)

What Permissions Control: Feature access, data access (read vs. write), cross-location access, export capabilities, administrative functions, clinical features

Example Scenario: Your organisation decides that only senior veterinarians should diagnose certain high-consequence diseases. You adjust permission configurations so standard veterinarian role can diagnose most diseases, but emergency diseases require senior veterinarian approval.

How to Run:

  1. Access System Tasks, Configuration Management
  2. Select "Manage Permissions"
  3. Review current permission configurations
  4. Select permission category to modify
  5. Adjust settings for specific roles
  6. Review changes carefully (affects all users with that role)
  7. Confirm changes
  8. Permissions apply immediately

Important Considerations: Permission changes affect all users with the impacted role, test with single user account first if unsure, document why permission changes were made, communicate changes to affected users, can be reversed if unintended consequences occur

Validation Rule Management

What It Is: Validation rules enforce data quality by defining acceptable values for animal records, observations, and operational data. Rules prevent impossible data entry (2,000 kg chickens, negative ages, future birth dates).

When to Use:

  • Data quality issues detected
  • Organisational standards changed
  • Species addition (when adding animal types requiring specific validation)
  • Regulatory compliance (when new regulations mandate data standards)

What Validation Rules Control: Weight ranges, age constraints, breeding parameters, date logic, required fields, format standards

Example Scenarios:

Scenario 1: Weight Validation - You notice several sheep recorded with 500 kg weights (impossible, should be 50-100 kg). You adjust validation rules to reject sheep weights outside 20-150 kg range, preventing future data entry errors.

Scenario 2: Breeding Age Validation - Your breeding programme policy changes: cattle must be at least 18 months old before breeding (previously 15 months). You update validation rules to enforce new minimum breeding age, ensuring compliance with updated policy.

How to Run:

  1. Access System Tasks, Configuration Management
  2. Select "Manage Validation Rules"
  3. Choose validation category
  4. Review current rules
  5. Modify rules as needed
  6. Test with sample data entry (if possible)
  7. Confirm changes
  8. Validation rules apply to new data entry

Impact: Affects future data entry only, existing records with values violating new rules remain unchanged, users see validation errors when attempting to enter invalid data, improves data quality prospectively

Medication Database Management

What It Is: Medication database defines pharmaceutical products, treatments, vaccines, and medical supplies used in your animal operations. This database powers treatment recording, medication inventory, withdrawal period tracking, and antimicrobial stewardship.

When to Use:

  • New medications approved
  • Expanded operations (when acquiring new facilities using different medications)
  • Veterinary protocol changes
  • Species diversification (when new animal types require specialised medications)
  • Regulatory updates (when medication classifications or withdrawal periods change)

What Medication Database Contains: Medication names, active ingredients, species applicability, administration routes, dosage information, withdrawal periods, antimicrobial classification, prescription requirements

Example Scenarios:

Scenario 1: New Antibiotic Approved - Regulatory authority approves new antibiotic for cattle respiratory disease. You add medication to database with correct withdrawal periods, dosage guidelines, and antimicrobial classification so veterinarians can prescribe it and farmers can record treatments compliantly.

Scenario 2: Withdrawal Period Update - Regulatory authority changes milk withdrawal period for common mastitis treatment from 48 hours to 72 hours. You update medication database so treatment records automatically apply correct withdrawal period for compliance.

How to Run:

  1. Access System Tasks, Configuration Management
  2. Select "Manage Medications"
  3. Choose operation: Add new medication, update existing medication, archive discontinued medication
  4. Enter or modify medication details
  5. Verify species applicability and withdrawal periods
  6. Confirm changes
  7. Medication immediately available in treatment recording workflows

Compliance Importance: Incorrect withdrawal periods risk regulatory violations, missing medications prevent accurate treatment documentation, antimicrobial classifications critical for stewardship monitoring (Chapter 19), medication database accuracy affects food safety and regulatory compliance

System Maintenance Tasks

Location Coordinate Updates

What It Is: Location coordinate updates synchronise geographic data (GPS coordinates, boundaries, subdivisions) when physical locations change or data quality issues are detected. Ensures map features (Chapter 9) accurately reflect your operational reality.

When to Use:

  • New facilities acquired (geographic data needs verification)
  • Subdivisions modified (paddocks re-fenced, enclosures relocated)
  • Map discrepancies (locations appear in wrong positions on maps)
  • GPS data corrupted (coordinates lost or invalid)
  • Operational changes (properties expanded, merged, or subdivided)

What It Does: Validates all location GPS coordinates, identifies missing or invalid coordinates, recalculates boundaries from GPS points, updates subdivision relationships, verifies location hierarchy integrity, flags locations requiring manual coordinate entry

Example Scenarios:

Scenario 1: Farm Expansion - You acquire adjacent property, merge two paddocks into one, and create three new subdivisions. After recording these changes, you run location coordinate update to recalculate boundaries and verify geographic data integrity.

Scenario 2: Data Migration - After importing locations from another system, you notice some locations appear in wrong geographic positions on maps. Location coordinate update identifies and flags locations with invalid or missing GPS data for correction.

How to Run:

  1. Access System Tasks, System Maintenance
  2. Select "Update Location Coordinates"
  3. System scans all locations in your instance
  4. Generates report
  5. Review report
  6. Manually correct flagged locations if needed
  7. Confirm update operation

Time Required: Varies by location count (minutes for small operations, longer for thousands of locations)

Impact: Map displays become more accurate, movement tracking reflects correct geography, location-based features work reliably

Database Backup

What It Is: Database backup creates complete copy of your organisation's Kora data for disaster recovery, compliance archiving, and operational continuity.

When to Use:

  • Regularly scheduled (weekly or daily backups)
  • Before major changes (before bulk data imports, system upgrades, large configuration changes)
  • Before deletions (before deleting large amounts of data, irreversible without backup)
  • Compliance requirements (when regulations mandate backup frequency)
  • Pre-audit (before regulatory audits to capture data state)

What Gets Backed Up: All animal records, all observations/treatments/movements, all locations and geographic data, all user accounts and permissions, all traceability events, all Knowledge API content (if locally managed), all system configurations, all audit logs

What's NOT Backed Up: Active user sessions, temporary cache data, system logs (backed up separately by IT infrastructure)

How to Run:

  1. Access System Tasks, System Maintenance
  2. Select "Database Backup"
  3. Choose backup type: Full Backup (complete database) or Incremental Backup (changes since last backup)
  4. Specify backup location
  5. Confirm backup operation
  6. Monitor backup progress
  7. Verify backup completion
  8. Test backup integrity (recommended quarterly)

Backup Best Practices:

Frequency:

  • Critical operations (regulatory compliance, high-value animals): Daily
  • Standard operations: Weekly
  • Small operations (minimal data changes): Monthly
  • Before major events: Always

Storage:

  • Multiple locations (on-site backup plus off-site backup)
  • Geographic separation (off-site backup in different location for disaster recovery)
  • Encrypted (backups contain sensitive data, encrypt at rest and in transit)
  • Tested regularly (verify backups can actually be restored, quarterly test)

Retention:

  • Recent backups: Keep all daily backups for 30 days
  • Monthly backups: Keep for 1 year
  • Annual backups: Keep for regulatory retention period
  • Compliance-driven: Follow organisational data retention policy

Example Scenarios:

Scenario 1: Pre-Audit Backup - Regulatory audit scheduled for next week. You create full backup capturing exact data state before audit begins, ensuring you can document precisely what was in the system at audit time.

Scenario 2: Disaster Recovery - Server failure corrupts database. You restore from last night's backup, losing only 18 hours of data (overnight period, minimal activity). Most recent day's work restored from backup, operations resume with minimal data loss.

Critical Importance: Your animal records, traceability data, and compliance documentation are irreplaceable. Hardware fails. Data corrupts. Disasters happen. Regular backups are the only protection against catastrophic data loss.

System Cleanup

What It Is: System cleanup removes obsolete data, optimises database performance, and frees storage space while maintaining data integrity and compliance with retention requirements.

When to Use:

  • Performance degradation (system slowing down due to data volume)
  • Storage limits (approaching storage capacity)
  • Data retention compliance (purging data older than required retention period)
  • Scheduled maintenance (quarterly or annual cleanup operations)
  • After bulk operations (cleaning up temporary data from imports or migrations)

What Gets Cleaned: Soft-deleted records (beyond retention period, permanently deleted), expired temporary data, orphaned records (data linked to deleted parent records), duplicate entries (identified and flagged for review), old audit logs (beyond retention requirement, archived or deleted per policy), unused media files (photos/documents no longer linked to records)

What's Protected: All active animal records, traceability events (never deleted, immutable for compliance), current observations and treatments, user accounts and audit logs within retention period, compliance-required data regardless of age

How to Run:

  1. Access System Tasks, System Maintenance
  2. Select "System Cleanup"
  3. Choose cleanup scope: Conservative, Standard, or Aggressive
  4. Review what will be deleted (preview before deletion)
  5. Create backup first (critical, cleanup operations irreversible)
  6. Confirm cleanup operation
  7. Monitor cleanup progress
  8. Review cleanup report

Safety Measures: Always backup before cleanup, start conservative (use aggressive cleanup only when necessary), review preview (check what will be deleted before confirming), compliance check (ensure cleanup doesn't violate data retention requirements), audit logged (complete record of what was cleaned up and when)

Example Scenarios:

Scenario 1: Annual Cleanup - After five years of operation, database contains significant historical data beyond retention requirements. You run standard cleanup, archiving old audit logs and deleting soft-deleted records from three-plus years ago, freeing 40% storage space and improving query performance.

Scenario 2: Post-Migration Cleanup - After migrating from legacy system, temporary import tables and duplicate detection data remain. You run conservative cleanup removing only temporary migration artifacts, maintaining all migrated operational data.

Health Check

What It Is: Health check runs comprehensive diagnostics on your Kora instance, identifying issues before they cause operational problems.

When to Use:

  • Regular monitoring (weekly or monthly health checks)
  • Performance concerns (when system seems slow or unresponsive)
  • After system changes (after configuration updates, major data imports, or infrastructure changes)
  • Pre-audit preparation (verify system health before regulatory inspections)
  • Troubleshooting (when investigating user-reported issues)

What Health Check Tests:

Database Health: Connection reliability, query performance, index integrity, data corruption detection, storage capacity

Data Integrity: Orphaned records, broken references, invalid relationships, data constraint violations

System Performance: Response times, resource utilisation, background service status, cache effectiveness

Security: User account anomalies, permission configuration issues, audit log integrity, authentication system health

Integration Status: Knowledge API connectivity, external service availability, email service functionality

How to Run:

  1. Access System Tasks, System Maintenance
  2. Select "Health Check"
  3. Choose diagnostic depth: Quick (2-5 minutes), Standard (10-20 minutes), or Deep (30-plus minutes)
  4. Run health check
  5. Review health report
  6. Address critical issues
  7. Document health check results
  8. Schedule follow-up if warnings detected

Health Report Interpretation:

All Green (Healthy): System operating normally, no action required, continue regular monitoring schedule

Warnings (Yellow): Minor issues detected, functionality intact but monitoring needed, plan maintenance to address warnings, increase monitoring frequency

Critical Issues (Red): Significant problems detected, operational impact likely, immediate investigation required, contact Kora support or technical team

Example Scenarios:

Scenario 1: Proactive Monitoring - Monthly health check detects database indexes degrading (warning level). You schedule maintenance window to rebuild indexes, preventing future performance degradation.

Scenario 2: User Reports - Users report system slowness. You run standard health check, identify database connection pool exhaustion (critical), and adjust configuration to resolve issue before more users affected.

Feature Configuration (Managed by Kora Team)

Understanding Feature Flags

What Feature Flags Are: Feature flags control which platform capabilities are enabled in your Kora instance. They act as on/off switches for entire feature modules, user types, integrations, and specialised workflows.

Examples of Feature-Flagged Capabilities: Veterinary professional features, regulatory oversight capabilities, wildlife management modules, Knowledge API integration, advanced analytics dashboards, CAHW workflows, beekeeping management features, sustainability tracking

Who Manages Feature Flags: Feature flags are configured by the Kora team during deployment and deployment updates, not by SuperUsers. This is intentional: feature enablement may require infrastructure configuration, licensing agreements may determine available features, performance optimisation depends on enabled feature set, security configurations vary by feature combination, support and maintenance affected by enabled features.

What SuperUsers See: Features enabled in your instance are simply available. No feature flag management interface for SuperUsers. If wildlife management features are enabled, wildlife management options appear. If regulatory oversight is enabled, regulatory roles are available.

When Feature Configuration Changes:

  • Initial deployment (Kora team configures features based on your organisational needs)
  • Licence changes (upgrading or changing licence may enable additional features)
  • Operational expansion (when you need new capabilities, request feature enablement)
  • New platform releases (new Kora features may be enabled during version updates)

How to Request Feature Changes:

  1. Contact Kora team or your account representative
  2. Explain which features you need and why
  3. Kora team evaluates request (licensing, infrastructure, compatibility)
  4. Schedule feature enablement (may require brief maintenance window)
  5. Kora team enables features and verifies functionality
  6. You receive notification when features are available
  7. You configure new features (create user accounts if new user types enabled)

You Don't Manage Feature Flags Yourself Because: Requires technical platform knowledge beyond SuperUser scope, may involve infrastructure changes or server configuration, licensing and commercial agreements involved, support implications (enabled features affect support workflows), quality assurance needed to ensure feature compatibility

SuperUser Role: You manage what happens within enabled features (user access, configurations, operational settings). Kora team manages which features are available in your instance.

Task Execution Safety

Confirmation Dialogues

Every system task shows confirmation dialogue before execution:

What Confirmation Shows: Task name and description, what will happen when you run the task, what data will be affected, estimated time to complete, reversibility (can this be undone?)

Why Confirmations Matter: Prevents accidental execution, ensures you understand impact, gives you chance to verify readiness (backup before cleanup), documents you intentionally ran the task (audit trail)

Task Output Terminal

When you run system tasks, Task Output Terminal displays real-time progress:

What You See: Task execution start timestamp, step-by-step progress, warnings or errors encountered, completion status (success, partial success, failure), summary results

Why Real-Time Output Matters: Monitor long-running tasks (backups, cleanup operations), identify issues during execution (not just after failure), understand what task is doing (educational), troubleshooting guidance if errors occur

Audit Logging for System Tasks

Every system task execution is logged:

What's Logged: Which task was run, when it was run (precise timestamp), which SuperUser ran it (accountability), task parameters (configuration details), execution results (success, failure, warnings), data affected (how many records, what changed)

Why Audit Logging Matters:

Troubleshooting: If system behaves unexpectedly after task execution, audit log shows exactly what happened.

Accountability: Every task traces to specific SuperUser account. No anonymous administrative actions.

Compliance: Regulatory audits may require documentation of system maintenance and configuration changes.

Security: Unauthorised task execution (if account compromised) is immediately visible in audit logs.

Common Configuration & Maintenance Workflows

Workflow 1: Adding New Animal Type to Operations

Scenario: Conservation organisation starts managing endangered amphibians in addition to existing mammal programmes.

Steps:

  1. Access System Tasks, Configuration Management
  2. Select "Load Animal Type Configs"
  3. System prompts: which animal types to load?
  4. Select "Amphibians" configuration
  5. Review what will be loaded
  6. Confirm operation
  7. Task output shows amphibian configuration loaded successfully
  8. Navigate to animal creation workflow
  9. Verify "Amphibian" now appears as animal type option
  10. Create test amphibian record to verify configuration working correctly

Time Required: 10 minutes

Workflow 2: Weekly Routine Maintenance

Scenario: Scheduled weekly maintenance for reliable operation.

Steps:

Monday morning (before operations start):

  • Access System Tasks, System Maintenance
  • Run "Health Check" (Standard depth)
  • Review results: All healthy
  • Document health check completion

Sunday night (during low-activity period):

  • Access System Tasks, System Maintenance
  • Run "Database Backup" (Full Backup)
  • Monitor backup progress
  • Verify backup integrity
  • Document backup completion

Time Required: 30 minutes per week

Workflow 3: Pre-Audit Preparation

Scenario: Regulatory audit scheduled for next month, prepare system for inspection.

Steps:

Three weeks before audit: Run deep health check, review health report, address warnings and critical items, document health check results

Two weeks before audit: Run system cleanup (conservative scope), remove obsolete data beyond retention requirements, optimise database performance, document cleanup operations

One week before audit: Create full database backup (capture exact data state), store backup securely, run final health check (verify optimal performance), document all maintenance performed

Audit preparation complete: System optimised and healthy, complete backup available, maintenance documented, ready for regulatory inspection

Time Required: 4-6 hours spread over three weeks

Workflow 4: Recovering from Performance Degradation

Scenario: Users report system slowness, need to diagnose and resolve.

Steps:

Immediate Diagnosis:

  • Access System Tasks, System Maintenance
  • Run "Health Check" (Standard)
  • Review results: Database indexes degraded (Warning), Query performance slow (Critical)

Initial Resolution:

  • Document current state
  • Contact Kora support or technical team with health check results
  • Technical team provides guidance: rebuild database indexes

Maintenance Window:

  • Notify users of brief maintenance window
  • Create backup before maintenance
  • Technical team rebuilds indexes
  • Run health check again: All green

Verification:

  • Test system responsiveness
  • Monitor user reports
  • Document resolution
  • Schedule increased monitoring frequency

Time Required: 2-4 hours (including diagnosis, maintenance window, verification)

Troubleshooting Configuration & Maintenance Issues

Issue: Task Execution Fails

Possible Causes: Insufficient permissions, database connection problems, disk space exhausted, concurrent operations conflicting

Resolution:

  1. Review task output terminal for specific error messages
  2. Check system health (database connectivity, storage capacity)
  3. Retry task if transient error
  4. Contact Kora support if persistent failure
  5. Provide exact error message from task output

Issue: Backup Takes Extremely Long

Possible Causes: Very large database, slow backup storage, database performance issues, concurrent operations during backup

Resolution:

  1. Check database size
  2. Consider incremental backups instead of full backups
  3. Schedule backups during low-activity periods
  4. Verify backup storage performance
  5. Consider optimising database before backup

Issue: Health Check Reports Critical Issues

Possible Causes: Actual system problems requiring immediate attention, false positives (diagnostic threshold too sensitive), recent system changes causing temporary inconsistencies

Resolution:

  1. Review critical issue details carefully
  2. Contact Kora support with health check report
  3. Don't ignore critical issues (assume they're real until proven otherwise)
  4. Document issue for tracking
  5. Follow support guidance for resolution

Issue: System Cleanup Deletes More Than Expected

Prevention (This Shouldn't Happen): Always review cleanup preview before confirming, start with conservative cleanup scope, create backup before cleanup operations, understand data retention policy

If It Occurs:

  1. Stop further cleanup operations
  2. Restore from most recent backup (created before cleanup)
  3. Review audit logs (what exactly was deleted?)
  4. Contact Kora support to report issue
  5. Investigate why cleanup scope was broader than expected
WORDS
[3,580]
READ TIME
[18m]