CSV Connector Setup

Overview

The CSV connector operates in two modes: source (reads CSV files as input) and target (writes pipeline output to CSV files). It is the most flexible connector in VersionForge -- useful for migrations from legacy systems, testing new sync profiles without touching a live target, one-off data loads, and exporting pipeline results for external review.

CSV Source Connector

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | basePath | Yes | The directory containing your CSV files. All file paths in the sync profile are resolved relative to this base. |

Configuration

| Option | Default | Description | |--------|---------|-------------| | filePath | workers.csv | Relative path to the CSV file within the base directory. | | idColumn | employee_id | Column used as the sourceRecordId for each record. Must be unique within the file. | | delimiter | , | CSV delimiter character. Supports ,, ;, \t, and \|. |

Setup Steps

1. Prepare Your CSV File

   Place your CSV file in a directory accessible to VersionForge. The file must have a header row as the first line. Ensure the ID column contains unique values for each row -- this is how VersionForge identifies and deduplicates records across sync runs.

   employee_id,first_name,last_name,department,salary
   100234,Jane,Doe,Engineering,120000
   100235,John,Smith,Sales,95000
   100236,Maria,Garcia,Marketing,88000
   

2. Create the Credential

   Go to Administration > Credentials > Add Credential. Select CSV File (Source) and enter the basePath:

   /data/imports/workforce
   

3. Configure the Sync Profile

   Set the source connector to CSV File and configure:

   {
     "filePath": "headcount-2026-q1.csv",
     "idColumn": "employee_id",
     "delimiter": ","
   }
   

Validating the Source

When you click Test Connection, VersionForge verifies:

• The base directory exists and is readable
• The specified CSV file exists within the base directory
• The file can be parsed with the configured delimiter
• A row count is returned for confirmation

CSV Target Connector

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | outputDir | Yes | Directory where output CSV files are written. Created automatically if it does not exist. |

Configuration

| Option | Default | Description | |--------|---------|-------------| | outputFileName | Auto-generated | Override the output filename. Default pattern: output-{objectType}-{timestamp}.csv. |

Setup Steps

1. Create the Target Credential

   Go to Administration > Credentials > Add Credential. Select CSV File (Target) and enter the outputDir:

   /data/exports/pipeline-output
   

2. Configure the Sync Profile Target

   Set the target connector to CSV File:

   {
     "outputFileName": "approved-headcount-2026-q1.csv"
   }
   

   If you omit outputFileName, VersionForge generates a timestamped filename automatically, so successive runs do not overwrite previous outputs.

Validating the Target

The test verifies:

• The output directory exists or can be created
• The directory is writable
• Sufficient disk space is available

Common Use Cases

Migration from Legacy Systems

Use the CSV source to load historical data from a legacy ERP or HRIS. Export from the legacy system as CSV, place it in the base directory, and configure a sync profile that transforms and pushes the data to your planning target (Adaptive, Pigment, etc.).

Testing and Dry Runs

Point your sync profile at a CSV target instead of a live planning system. This lets you run the full pipeline -- extraction, diffing, transforms, Safety Gate -- and review the output without making any changes to your planning model.

Round-Trip Validation

Use CSV as both source and target to validate VersionForge transforms. Load a known input file, run the pipeline, and compare the output CSV against expected results.

Manual Review Exports

Configure a CSV target alongside your primary planning target. After each sync, the CSV export contains the exact data that was pushed, providing a file-based audit trail for compliance teams.

Test Your Connection

For source mode, click Test Connection on the credential. VersionForge reads the file and returns the row count and file path. For target mode, VersionForge verifies directory writability. Both tests are non-destructive.

Common Issues

"File not found" -- The filePath is relative to the basePath. Verify both values. If your base path is /data/imports and your file is at /data/imports/workforce/q1.csv, set basePath to /data/imports and filePath to workforce/q1.csv.

Parse errors -- Ensure the delimiter in your configuration matches the actual delimiter in the file. A semicolon-delimited file parsed with a comma delimiter will appear as a single-column file with very long values.

Empty extraction -- The file must have at least two lines (a header and one data row). A file with only a header row produces zero records.