Skip to main content

ParkPow Auto File Import Tool

The ParkPow Auto File Import Tool is a utility that helps you automatically import vehicle data from text files (like CSV, TXT, etc.) into your ParkPow account. You can use it to add or remove vehicles in bulk by simply placing files in a designated folder.

How It Works​

The tool runs on a scheduled cron job. Each time the cron executes, it checks the upload folder for new files. If a file is found, the tool reads the data, performs initial processing (including duplicate removal), transforms it according to your settings, and sends it to your ParkPow account. It's designed to be a "set it and forget it" solution for data import.

Mass Vehicle Management with TAGs​

Important: This tool works as a mass vehicle management system that creates vehicles in ParkPow using a predefined TAG from your upload file. When you define a TAG (e.g., "BLOCKED"), all vehicles from your upload file are created in ParkPow with this TAG. This allows you to instantly identify vehicle categories when they visit your location.

How the TAG-based system works:

  • You define a TAG in your configuration (e.g., "BLOCKED", "BLACKLIST", "VIP", etc.)
  • The tool processes your upload file and creates/updates vehicles in ParkPow with this TAG
  • When a vehicle visits your location, ParkPow will show the assigned TAG, allowing immediate identification

Practical Example:

Configuration: You set Vehicle Tags = BLOCKED in your config file

Upload file contains:

plate
ABC-1234
XYZ-5678
DEF-9012

Result: Three vehicles are created in ParkPow, each with the "BLOCKED" tag

When ABC-1234 visits: ParkPow will immediately show this vehicle has the "BLOCKED" tag, alerting you that this is a blocked vehicle

Use Cases:

  • Security blacklists: Tag vehicles as "BLOCKED" to immediately identify restricted vehicles
  • VIP management: Tag vehicles as "VIP" for special treatment
  • Employee tracking: Tag vehicles as "EMPLOYEE" for access control
  • Fleet management: Tag vehicles as "COMPANY" for inventory control

File Format Requirements:

  • Header Row: The first line of your file is treated as a header and is automatically ignored during processing
  • Data Rows: Actual vehicle data should start from the second line onwards

Supported File Formats​

While this guide often refers to CSV files, the auto-import tool is designed to be flexible, accepting any plain text file that contains delimited data. The tool automatically detects the delimiter type used in your file.

Compatible File Formats:

  • CSV (Comma-Separated Values): This is the most common and recommended format. The application automatically identifies the comma (,) as the data separator.
  • TXT (Plain Text): Plain text files are also supported. The application can process .txt files that use commas, spaces, or tabs as delimiters.
  • DAT and other text files: Any other file (like .dat) containing data in a plain text format, with values separated by supported delimiters, will also be compatible.

Supported Delimiters: The tool automatically detects and supports the following delimiters:

  • Comma (,) – Most common for CSV files (e.g., name,age,email)
  • Space ( ) – For space-delimited text files (e.g., name age email)
  • Tab (\t) – Common in TSV (Tab-Separated Values) files (e.g., name age email)

Essential File Requirements:

  1. Plain Text Format: The file must be a text file. It cannot be a binary file like an image (.jpg), a Word document (.doc), or an Excel spreadsheet (.xls).
  2. Delimiter: The data in each row must be separated by one of the supported delimiters mentioned above.
  3. Structure: Each line in the file must represent a new record (for example, a new vehicle license plate).
  4. Header: The first line of your file is treated as a header and is automatically ignored during processing.

Examples of Valid File Formats:

CSV file (comma-delimited) - Note the header row:

License Plate,City,State,Category
ABC-1234,São Paulo,SP,Resident
XYZ-5678,Rio de Janeiro,RJ,Visitor
DEF-9012,Belo Horizonte,MG,Employee

TSV file (tab-delimited) - Note the header row:

License Plate	City	State	Category
ABC-1234	São Paulo	SP	Resident
XYZ-5678	Rio de Janeiro	RJ	Visitor
DEF-9012	Belo Horizonte	MG	Employee

Space-delimited text file - Note the header row:

License_Plate City State Category
ABC-1234 "São Paulo" SP Resident
XYZ-5678 "Rio de Janeiro" RJ Visitor
DEF-9012 "Belo Horizonte" MG Employee
important

In all examples above, the first line (header row) is automatically ignored during processing. The actual vehicle data starts from the second line.

Unsupported Formats:

  • Binary files (e.g., .jpg, .png, .doc, .xls)
  • Files with complex structures (e.g., .json, .xml)

How to Get Started​

Prerequisites​

  • You need to have Docker installed and running on your system.

Step 1: Create a data folder and config.ini file​

First, you need to create a data folder on your computer. This folder will store your configuration, logs, and data files. The tool will automatically create the following subfolder structure:

data/
├── config.ini          # Your configuration file
├── upload/             # Place files here for processing (auto-created)
├── processed/          # Successfully processed files (auto-created)
├── error/              # Files with processing errors (auto-created)
└── logs/               # Log files (auto-created)

Create the main data folder:

mkdir -p data

Inside this data folder, create a file named config.ini. This is where you will configure the tool. Copy and paste the example below into your file and then edit the values to match your setup.

Example config.ini

[CRON]
CRON_SCHEDULE = */2 * * * *

[API]
BASE_API_URL = http://YOUR_PARKPOW_IP:8000
AUTH_TOKEN = YOUR_PARKPOW_TOKEN

[COLUMN_MAPPING]
source_col0 = license_plate
source_col1 = description
source_col2 = state
source_col3 = vehicle_tags

[EXTRA_COLUMNS]
Vehicle Tags = Block

Step 2: Configure the Tool​

Here's what each section in the config.ini file does:

  • [CRON]

    • CRON_SCHEDULE: This determines how often the tool checks for new files. For example, */2 * * * * means it will run every 2 minutes. You can adjust this expression to fit your needs. To easily build and test your own cron schedule, you can use crontab.guru.

  • [API]

    • BASE_API_URL: The URL of your ParkPow instance. For On-Premise, it's typically http://<your_ip>:8000. For ParkPow Cloud, use https://app.parkpow.com.
    • AUTH_TOKEN: Your ParkPow API token. You can find this in your ParkPow account settings.

  • [COLUMN_MAPPING]

    • This section maps the columns from your file to the fields in ParkPow. Column indexes start from 0 (zero-based indexing):
      • source_col0 = First column (index 0)
      • source_col1 = Second column (index 1)
      • source_col2 = Third column (index 2)
      • And so on...

    Example: If your CSV file looks like this:

    ABC-1234,Company Vehicle,Employee
    XYZ-5678,Personal Car,Visitor

    Then your mapping must follow the ParkPow template:

    source_col0 = license_plate    # ABC-1234, XYZ-5678
    info

    The license_plate field is a required field and must always be mapped. When mapping additional fields, ensure they follow the formats supported by ParkPow. You can verify the accepted formats in our API documentation

  • [EXTRA_COLUMNS]

    • This section is crucial as it defines the TAG that will be assigned to all vehicles created from your upload file. For example, Vehicle Tags = BLOCKED will assign the "BLOCKED" tag to every vehicle. When these vehicles visit your location, ParkPow will immediately display this tag for instant identification.
    • You can use any descriptive tag name: "BLOCKED", "VIP", "EMPLOYEE", "BLACKLIST", "AUTHORIZED", etc.
    • Purpose: This tag allows immediate visual identification of vehicle categories when they arrive at your location, enabling appropriate security or access control responses.

Step 3: Run the Docker Container​

Open your terminal and run the following command. This will download and start the tool in a Docker container. Note: You must replace /path/to/your/data with the absolute path to the data folder you created in Step 1.

docker run -d --name parkpow-auto-file-import-tool -v /path/to/your/data:/app/data platerecognizer/parkpow-auto-import

This command links the data folder you created on your computer to the data folder inside the container. This way, your configuration and files are preserved even if you stop or restart the container.

Step 4: Add Files for Import​

Now, simply place your data files into the data/upload folder. The tool will pick them up on its next scheduled run.

Processing Flow:

  1. File Detection: When the cron runs, the system checks for files in the upload folder.
  2. No Files Found: If no files are present, the system logs that no files were found for processing.
  3. File Processing: If files are found, the system:
    • Automatically ignores the header row (first line)
    • Removes duplicate entries from the source file (starting from the second line)
    • Compares the entire file content with the state of the last update performed
    • Calculates differences (delta): Determines which vehicles need to be added or removed
    • Reports the number of unique plates that will be added or removed
    • Processes only the differential changes according to your configuration
    • Sends the changes to ParkPow
  4. Task Verification: The system checks whether the tasks generated by the API were completed successfully or if there were errors.
    • The log will provide details, and in case of errors, it will indicate why the records were not included.
    • Files with errors will be moved to the error folder.

Mirror/Sync Behavior Examples:

Scenario 1 - Creating vehicles with TAG:

  • Upload file: 1,000 new vehicle license plates
  • Configuration: Vehicle Tags = BLOCKED
  • Action: 1,000 vehicles are created in ParkPow, each with the "BLOCKED" tag

Scenario 2 - Adding more vehicles to existing TAG:

  • Current ParkPow: 1,000 vehicles with "BLOCKED" tag
  • New upload file: 1,050 vehicles (includes previous 1,000 + 50 new)
  • Action: Only the 50 new vehicles are created with the "BLOCKED" tag

Scenario 3 - Removing vehicles from TAG:

  • Current ParkPow: 1,000 vehicles with "BLOCKED" tag
  • New upload file: 950 vehicles (50 vehicles removed from the list)
  • Action: The 50 vehicles with "BLOCKED" tag that are no longer in the file are removed from ParkPow
warning

It is important to note that the example above assumes all imports are being performed through the ParkPow Auto File Import Tool, as the tool has exclusive control over the changes made via import. Modifications made directly in ParkPow or through the API are not monitored.

After Processing:

  • Successful files are moved to the data/processed folder
  • Files with errors are moved to the data/error folder for review

Monitoring and Logs​

You can check the status of the tool by viewing its logs:

  • Live logs: To see what the tool is doing in real-time, run: 
    docker logs -f parkpow-auto-file-import-tool
  • Log files: The tool also saves logs to files in the data/logs folder for later review.

Error Handling and Troubleshooting​

When files fail to process, they are moved to the data/error folder. Common types of errors include:

  • API Errors: Issues with authentication, network connectivity, or API responses from ParkPow
  • File Format Errors: Problems with delimiter detection, file encoding, or structure
  • Data Validation Errors: Invalid license plate formats or missing required fields

To troubleshoot errors:

  1. Check the log files in data/logs for detailed error messages
  2. Review the API response codes and messages in the logs
  3. Verify that your file format matches the supported delimiters
  4. Ensure your config.ini file has the correct column mappings
  5. Check that your ParkPow API token is valid and has the necessary permissions

Complete Example​

Here's a complete example to help you get started:

Sample CSV file (vehicles.csv) - with header row:

License Plate,Description,State,Category,Make,Model,Color,Year
ABC-1234,Company Vehicle,SP,Employee,Toyota,Camry,Blue,2020
XYZ-5678,Personal Car,RJ,Visitor,Honda,Civic,Red,2019
DEF-9012,Fleet Vehicle,MG,Contractor,Ford,Focus,White,2021

Important Notes:

  • The first line (License Plate,Description,State,Category,Make,Model,Color,Year) is the header and will be automatically ignored
  • The actual vehicle data starts from line 2
  • When you update this file later (add or remove vehicles), the system will only process the differences

Corresponding config.ini:

[CRON]
CRON_SCHEDULE = */5 * * * *

[API]
BASE_API_URL = http://192.168.1.100:8000
AUTH_TOKEN = your_actual_api_token_here

[COLUMN_MAPPING]
source_col0 = license_plate

[EXTRA_COLUMNS]
Vehicle Tags = ImportedVehicle

This configuration will:

  • Check for new files every 5 minutes
  • Map 1 column from your CSV to ParkPow fields
  • Add an additional "ImportedVehicle" tag to all imported vehicles
  • Process the file and move it to the appropriate folder based on success or failure

Performance Benchmark​

The following results illustrate the tool's performance. All tests were conducted on ParkPow On-Premise using a computer with an Intel(R) Core(TM) i5-9300H processor and 16 GB of RAM. The measurements cover the entire cycle, from file processing to monitoring the completion of the last task. The table shows the time required to process different numbers of records.

Record VolumeOperationNo. of TasksRead & Compare TimeFile Generation TimeUpload TimeMonitoring TimeTotal Cycle Time
10,000Inclusion1~0.1s~0.1s~1.2s~14.1s~15.6 seconds
10,000Exclusion1~0.1s~0.1s~1.2s~14.0s~15.3 seconds
50,000Inclusion2~0.5s~0.2s~2.4s~43.0s~46.2 seconds
50,000Exclusion2~0.1s~0.2s~2.4s~58.5s~1 min 1 sec
100,000Inclusion3~0.5s~0.3s~3.6s~56.7s~1 min 1 sec
100,000Exclusion3~0.2s~0.4s~3.7s~57.9s~1 min 2 sec
500,000Inclusion12~3.4s~1.4s~15.1s~3 min 12s~3 min 33 sec
500,000Exclusion12~0.4s~2.1s~15.0s~3 min 29s~3 min 46 sec
1,000,000Inclusion23~6.9s~2.7s~30.0s~6 min 11s~6 min 54 sec
1,000,000Exclusion23~0.9s~5.6s~28.4s~5 min 59s~6 min 34 sec
Floating button icon
CTRL + .