Skip to content

Tracker CSV Import

The admin panel provides functionality to import trackers in bulk using CSV files. This guide explains how to use this feature.

Accessing the Import Feature

  1. Navigate to the Trackers page in the admin panel
  2. Click the "Import CSV" button in the top-right corner
  3. A modal dialog will appear with instructions and options

CSV File Format

The CSV file should include the following columns:

  • ID - The tracker name/identifier (required)
  • Private key - The tracker's private key (required)
  • Advertisement key - The tracker's advertisement key (required)
  • Hashed adv key - The hashed advertisement key (required)
  • MAC Address - The tracker's MAC address (optional)

Column names are case-insensitive and can include spaces or underscores. For example, "MAC Address", "mac_address", or "MacAddress" are all valid.

Example CSV Content

ID,Private key,Advertisement key,Hashed adv key,MAC Address
c50Rvpu,G1IQn4WJUS3nrnmzHtHxFcT2oSdOtbdPCk4I8g==,5PlhQdK0WF3humRVEEmMOXGI+eqMxTc2NhWrJQ==,c50RvpugKZ3UM5AcYasM8XijrdrcMzZFt4S13LsGs4Y=,00:1A:2B:3C:4D:5E
NZ3gb4m,UUwgh+xbaOuXCxd2Pht7GpnPUSoIMH3M83DXFA==,GHifc87f2FPmuk/IL6fDkfWtnI5zs+KtFFdXhA==,NZ3gb4mv2lhAn0mIV6X1nnLPOO0cF4XTvNB2aACjVX8=,00:1A:2B:3C:4D:5F

Import Process

  1. Select a production run from the dropdown menu
  2. Upload your CSV file by clicking "Upload a file" or by dragging and dropping the file
  3. Click the "Import" button to start the import process
  4. The system will validate the CSV file and import the trackers
  5. You'll receive a notification with the results of the import

Validation Rules

The import process includes several validation checks:

  • All required fields (ID, Private key, Advertisement key, Hashed adv key) must be present
  • Trackers with duplicate hashed advertisement keys will be skipped
  • The MAC Address field is optional and can be left blank

Downloading a Template

You can download a sample CSV template by clicking the "Download sample CSV template" link in the import dialog. This template includes the correct column headers and example data to help you format your CSV file correctly.

Troubleshooting

If you encounter issues during the import process:

  • Ensure your CSV file has the correct column headers
  • Check that all required fields have values
  • Verify that the CSV file is properly formatted (UTF-8 encoding is recommended)
  • Look for any error messages displayed in the import dialog

Command Line Import

For advanced users or automated processes, you can also import trackers using the command line script:

python scripts/import_trackers.py <production_run_id> --csv-path path/to/your/file.csv

This script is located in the scripts directory and requires a production run ID and the path to your CSV file.

Cache Invalidation

When trackers are imported, the system automatically invalidates the Redis cache for:

  • The specific production run
  • All production run lists
  • All tracker lists related to the production run

This ensures that newly imported trackers appear immediately in the admin panel and frontend without requiring a manual cache flush. The cache invalidation is handled automatically by both the web interface and the command line import script.

If you're experiencing issues where newly imported trackers don't appear, please refer to the Caching System documentation for troubleshooting steps.