Adaptive Dimension Auto-Create

Overview

When source data contains dimension values that do not yet exist in Adaptive Planning -- a new department code, a recently opened location, a cost center added last week -- the import fails with "Unknown dimension value" errors. VersionForge's dimension auto-create feature detects these gaps before the push, creates the missing members via the Adaptive XML API, and then proceeds with the import.

This eliminates a common FP&A bottleneck: waiting for someone to manually add dimension members in Adaptive before data can flow.

How It Works

The auto-create process runs during the prepare() phase, before any data rows are sent:

1. Metadata Introspection

VersionForge calls exportDimensions to retrieve every dimension and its current member list. It also calls exportSheetDefinition to determine which columns in the target sheet reference which dimensions.

Sheet column "department" → references dimension "Department"
Sheet column "location"   → references dimension "Location"
Sheet column "account"    → references dimension "Account"

2. Gap Detection

VersionForge scans the source records and compares each dimension field value against the corresponding dimension's member list. Any value present in the source data but absent from Adaptive is flagged as a gap.

For example, if the source contains department Engineering - Platform but the Adaptive Department dimension only has Engineering, Engineering - Backend, and Engineering - Frontend, then Engineering - Platform is identified as a missing member.

3. Auto-Create via XML API

For each missing value, VersionForge calls the createDimensionValue API method:

<?xml version='1.0' encoding='UTF-8'?>
<call method="createDimensionValue" callerName="VersionForge">
  <credentials token="your-api-token-here"/>
  <dimensionValue name="Engineering - Platform"
                  dimensionName="Department"
                  parentName="Engineering"/>
</call>

The new member is created in the dimension hierarchy and is immediately available for import.

4. Import Proceeds

After all missing members are created, the normal batched import runs. Rows that previously would have failed with dimension errors now succeed.

Auto-Parenting

When creating a new dimension member, VersionForge attempts to infer the correct parent using these rules:

1. Explicit mapping -- If your sync profile includes a parentMapping configuration, VersionForge uses it to look up the parent for each new value.

2. Name-prefix matching -- If the new value name starts with an existing member name followed by a separator (-, /, .), that existing member is used as the parent. For example, Engineering - Platform matches under Engineering.

3. Root-level fallback -- If no parent can be inferred, the member is created at the root level of the dimension hierarchy.

Conflict Handling

Several scenarios can produce conflicts during auto-create:

Duplicate names -- Adaptive dimensions can have members with the same name at different levels. If VersionForge tries to create a member that already exists by name but under a different parent, the API returns an error. VersionForge logs this conflict and skips the create, relying on Adaptive's name-based matching during import to resolve the reference.

Case sensitivity -- Adaptive dimension member names are case-insensitive for matching but case-preserving for display. VersionForge normalizes case during gap detection to avoid creating engineering when Engineering already exists.

Concurrent creates -- If two sync runs execute simultaneously and both detect the same missing member, the second create call will find the member already exists. VersionForge handles this gracefully by catching the "already exists" response and continuing.

Configuration

Enable auto-create in your sync profile's target configuration:

{
  "sheetName": "Headcount Plan",
  "versionName": "Plan",
  "autoCreateDimensions": true
}

When to Use Auto-Create

Good use cases:

• Dynamic environments where new departments, locations, or cost centers are added frequently
• Initial data loads where the Adaptive model is sparse and the source system is the authoritative dimension list
• Syncing from Workday HCM where organizational changes happen regularly

When to avoid:

• Tightly governed planning models where every dimension member must go through an approval process
• Dimensions with complex hierarchies that require manual parent assignment
• Production environments where accidental dimension creation could affect downstream formulas

For governed environments, disable auto-create and use the metadata-alignment module instead, which shows you the gaps and lets you approve each new member before creation.