Metadata Adapters: Pigment and Adaptive Planning

What Metadata Adapters Do

ParitySync needs to read dimension metadata from target systems -- the list of accounts, departments, cost centers, entities, and their hierarchies. Each target system exposes this information differently. Metadata adapters are the translation layer: they implement a standard interface that ParitySync consumes, while handling the specifics of each target system's API internally.

The Adapter Interface

Every metadata adapter implements three core methods:

interface MetadataAdapter {
  /** List all dimensions available in the target system */
  listDimensions(): Promise<DimensionDescriptor[]>;

  /** Get all members for a specific dimension */
  getMembers(dimensionId: string): Promise<DimensionMember[]>;

  /** Create a new member in the target dimension */
  createMember(
    dimensionId: string,
    member: NewMemberPayload
  ): Promise<DimensionMember>;
}

The DimensionMember type includes the fields ParitySync uses for matching and hierarchy resolution:

interface DimensionMember {
  id: string;             // target system's internal ID
  code: string;           // human-readable code (e.g., "6100")
  name: string;           // display name (e.g., "Marketing")
  parentId: string | null; // parent member ID for hierarchy
  attributes: Record<string, string>; // additional properties
}

Adaptive Planning Adapter

The Adaptive Planning adapter communicates through the XML API, specifically the exportDimensionMembers and importConfigurableModelData endpoints.

Reading Dimensions

The adapter calls exportDimensionMembers for each dimension type configured in the sync profile. It parses the XML response into the standard DimensionMember format, mapping Adaptive's hierarchy fields (parentCode, level) to the adapter interface.

Adaptive XML API → exportDimensionMembers(dimensionType: "Account")
  → Parse XML response
  → Map to DimensionMember[] { id, code, name, parentId, attributes }

Reading Hierarchies

Adaptive represents hierarchies through parent-child relationships on each member. The adapter reconstructs the full tree by resolving parentCode references, which ParitySync uses to validate hierarchy integrity and position new members correctly during auto-create.

Creating Members

New members are created via importConfigurableModelData with pipe-delimited payloads. The adapter serializes the NewMemberPayload into Adaptive's expected format, including the parent assignment and any required attributes (planning enabled, rollup behavior, display format).

Pigment Adapter

The Pigment adapter uses the REST API to read and write dimension metadata.

Reading Dimensions

The adapter queries Pigment's block structure to discover available dimensions. Each Pigment block exposes its dimensions through the /blocks/{blockId}/dimensions endpoint. The adapter aggregates dimensions across all blocks configured in the sync profile.

Reading Members

For each dimension, the adapter calls /dimensions/{dimensionId}/members to retrieve the full member list. Pigment returns members with their properties, hierarchy, and any custom attributes. The adapter normalizes these into the standard DimensionMember format.

Creating Members

New members are created via POST /dimensions/{dimensionId}/members with a JSON payload. The Pigment adapter supports bulk creation in a single request, unlike the Adaptive adapter's batch-of-100 approach.

Pigment REST API → POST /dimensions/{dimensionId}/members
  Body: { code, name, parentId, properties: { ... } }
  → Response: created member with generated ID

Extending for New Target Systems

To add ParitySync support for a new planning target, you implement the MetadataAdapter interface:

1. Implement listDimensions

   Query the target system's API to discover available dimensions. Return a DimensionDescriptor for each one, including the dimension ID, name, and whether it supports hierarchies.

2. Implement getMembers

   For a given dimension ID, retrieve all members from the target system. Normalize each member into the DimensionMember format with code, name, parent reference, and any attributes ParitySync needs for matching.

3. Implement createMember

   Accept a NewMemberPayload and create the corresponding member in the target system via its API. Return the created member with the target system's assigned ID. Handle conflicts and validation errors gracefully.

4. Register the adapter

   Add the adapter to VersionForge's connector registry so ParitySync discovers it when a sync profile uses the new target system. The adapter is loaded automatically when the corresponding target connection type is selected.

The adapter interface is intentionally minimal. Complex target-specific logic (batch size limits, rate limiting, pagination) lives inside the adapter implementation, not in ParitySync. This keeps the alignment engine clean and lets each adapter optimize for its target system's constraints.