Quickstart: Your First Sync

What You Will Build

By the end of this guide, you will have a working sync pipeline that extracts data from a source system, reviews the changes in the Safety Gate, loads them into your planning target, and verifies the totals match. The entire process takes under 15 minutes for a first-time setup.

Prerequisites

Before you begin, make sure you have:

• A VersionForge account with admin or editor permissions
• API credentials for your source system (e.g., NetSuite token, Workday API key, or a CSV file ready to upload)
• API credentials for your target system (e.g., Adaptive Planning OAuth client or Pigment API token)

Steps

1. Create a source connection

   Navigate to Connections in the sidebar and click New Connection. Select your source system from the connector list (NetSuite, Workday HCM, Stripe, or CSV).

   Enter your credentials. For API-based connectors, this typically includes a base URL, client ID, and secret or token. For CSV, you upload or point to a file path.

   Click Test Connection to verify VersionForge can reach the source. You should see a green confirmation with the number of available entities.

   Store credentials securely. VersionForge encrypts all credentials at rest, but you should still follow your organization's secret management policies for the values you enter.

2. Create a target connection

   Repeat the same process for your planning target. Click New Connection, select Adaptive Planning or Pigment, and enter the required OAuth or API credentials.

   Test the connection to confirm VersionForge can authenticate and list available import targets (sheets, models, or datasets depending on your platform).

3. Configure a sync profile

   Go to Sync Profiles and click New Profile. A sync profile defines which data moves from source to target and how it is transformed along the way.

   1. Select source connection -- Pick the connection you created in Step 1.
   2. Select target connection -- Pick the connection you created in Step 2.
   3. Map fields -- For each target dimension or column, select the corresponding source field. VersionForge shows you the source schema and target schema side by side so you can drag or select matches.
   4. Set transform rules (optional) -- Apply value mappings, concatenation, or default fill rules for fields that need translation between systems.
   5. Configure diff key -- Choose the field(s) that uniquely identify a row (e.g., employee ID, account code). This is how VersionForge matches rows across snapshots to detect changes.

   Click Save Profile when your mapping is complete.

   You do not need to map every source field. Map only the fields your target requires. VersionForge ignores unmapped columns during extraction.

4. Run the sync

   From your sync profile, click Run Now to trigger the pipeline manually. VersionForge will:

   • Extract a snapshot from your source
   • Compare it to the previous snapshot (on the first run, every row is an "add")
   • Apply your transform rules
   • Stage the results for review

   The run status updates in real time. When extraction and diffing are complete, the run enters Pending Review status and the Safety Gate lights up.

5. Review in the Safety Gate

   Click Review to open the Safety Gate. You will see a table of every proposed change, color-coded by type:

   • Green rows -- New records being added
   • Yellow rows -- Existing records with updated field values (changed fields are highlighted)
   • Red rows -- Records marked for deletion

   For each row, you can:

   • Approve -- Accept the change as-is
   • Reject -- Exclude the row from this load
   • Override -- Edit a specific field value before it reaches the target

   When you are satisfied, click Approve & Load to push the approved changes to your target system.

   On your first sync, every row will appear as an add. This is expected -- there is no previous snapshot to compare against. Review a sample of rows to confirm the data looks correct, then approve the batch.

6. Verify with cross-check

   After the load completes, VersionForge automatically runs a cross-check reconciliation. Navigate to the Verification tab on the run detail page to see the results.

   Cross-check compares aggregate totals between what was extracted from the source and what was loaded into the target. If the variance is within your configured tolerance (default: $1.00), the check passes with a green indicator.

   If the cross-check flags a variance, click into the detail view to see which dimensions or accounts are off. This helps you catch mapping errors or missing rows before they become problems downstream.

What Happens Next

Your sync ran once manually. To set up a recurring schedule (daily, weekly, or on a cron expression), edit the sync profile and configure the Schedule section. VersionForge will run the pipeline automatically, and the Safety Gate will queue changes for review each time.

For deeper guidance on field mapping, transforms, and connector-specific configuration, explore the Connectors section of the knowledge base.