Pigment Connector Setup

Overview

The Pigment connector is a target connector that pushes data into Pigment planning models via the CSV Push API. VersionForge formats source records as CSV, uploads them to a Pigment import configuration, and handles rate limiting, partial failures, and dimension member validation automatically.

Prerequisites

• Pigment workspace with Admin or API access
• At least one import configuration created in Pigment (under Integrations > Import Configurations)
• An API key with write permissions

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | apiKey | Yes | Pigment API key with import permissions. Found under Workspace Settings > API Keys. |

Setup Steps

1. Generate an API Key

   In Pigment, navigate to Workspace Settings > API Keys > Create API Key. Give it a descriptive name like "VersionForge Integration". Ensure the key has Import and Read scopes -- Import for pushing data, Read for metadata discovery and dimension validation.

   Copy the key immediately. It is only displayed once.

2. Create or Identify an Import Configuration

   Import configurations in Pigment define the target table, column mapping, and validation rules for incoming data. Navigate to Integrations > Import Configurations in Pigment. Either create a new configuration or identify an existing one.

   Each import configuration has:

   • A unique configuration ID (used in VersionForge sync profiles)
   • A target table (the Pigment data block that receives the data)
   • Column definitions with types, dimension references, and auto-create settings

3. Review Column Definitions

   VersionForge discovers the import configuration's column schema automatically using the Pigment metadata API. Review your import configuration's columns in Pigment to ensure they match the source data fields you plan to sync:

   • Dimension columns should have a dimensionRef pointing to the correct Pigment entity
   • Key columns should be marked as isKey: true for upsert matching
   • Required columns should be marked as required: true

4. Configure the Credential in VersionForge

   Go to Administration > Credentials > Add Credential. Select Pigment as the connector type and enter the apiKey.

5. Configure the Sync Profile Target

   In your sync profile, set the target connector to Pigment and configure:

   {
     "importConfigId": "cfg_abc123",
     "importMode": "upsert",
     "applicationId": "app_xyz789"
   }
   

   The applicationId is required for dimension member validation and null handling. Find it in Pigment under your application's settings.

Import Configuration Discovery

When you create or edit a sync profile targeting Pigment, VersionForge calls the metadata API to list all available import configurations:

GET /api/v1/import/configurations
Authorization: Bearer {apiKey}

This returns configuration IDs, names, target tables, and full column schemas. The sync profile UI displays these in a dropdown, so you can select the correct configuration without manually entering IDs.

Test Your Connection

Click Test Connection on the credential detail page. VersionForge calls the Pigment import configurations endpoint to verify:

• The API key is valid and not expired
• The key has read permissions for metadata discovery
• The Pigment API is reachable

A successful test returns the number of import configurations visible to your API key.

Common Issues

HTTP 401 Unauthorized -- The API key is invalid, expired, or revoked. Generate a new key in Pigment workspace settings.

HTTP 403 Forbidden -- The API key lacks the required scope. Verify it has both Import and Read permissions.

"Import configuration not found" -- The importConfigId in your sync profile does not match any configuration in Pigment. Use the metadata discovery dropdown to select a valid configuration.

Rate limit errors (429) -- Pigment enforces a limit of 500 requests per 5-minute window. VersionForge handles this with automatic exponential backoff and retry (up to 5 attempts). If you are running multiple sync profiles against the same Pigment workspace simultaneously, stagger their schedules to avoid hitting the rate limit.