Adaptive Planning Connector Setup

Overview

The Adaptive Planning connector is a target connector -- it pushes data into Adaptive Planning modeled sheets via the XML API. VersionForge uses the importConfigurableModelData endpoint to load rows in pipe-delimited format, batched in groups of 100. Authentication uses a long-lived API token that does not require refresh logic.

Prerequisites

• Adaptive Planning administrator access to generate API tokens
• A modeled sheet configured in your Adaptive model to receive data
• Knowledge of which version (Plan, Forecast, Actuals) and level to target

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | apiToken | Yes | API token generated from Adaptive Planning administration. | | instanceUrl | No | Override the default API base URL. Defaults to https://api.adaptiveplanning.com. Only change this for non-standard deployments. |

Setup Steps

1. Generate an API Token

   In Adaptive Planning, navigate to Administration > Security > API Tokens. Click Generate New Token. Copy the token immediately -- it cannot be retrieved after you leave the page.

   Assign the token to a service account with the appropriate role. The role must have:

   • Import Data permission on the target sheet(s)
   • Export Metadata permission for dimension and sheet discovery
   • Create Dimension Values permission if you plan to use auto-create

   API tokens in Adaptive are long-lived and do not expire unless manually revoked. Treat them with the same care as a password. Rotate tokens periodically and revoke any that are no longer in use.

2. Identify Your Target Sheet

   VersionForge needs to know which modeled sheet to push data into. You can specify either the sheet name or its numeric ID. To find the sheet ID, use the sheet list in Adaptive's administration interface, or let VersionForge discover it automatically during the metadata introspection step.

3. Select the Version

   Choose the target version for the import. Common options:

   • Actuals -- for loading historical financial data or headcount actuals
   • Plan or Forecast Q2 2026 -- for loading planning assumptions from source systems

   The version name must match exactly as it appears in Adaptive Planning, including capitalization and spaces.

4. Configure the Credential in VersionForge

   Go to Administration > Credentials > Add Credential. Select Adaptive Planning as the connector type. Enter the apiToken and optionally the instanceUrl.

5. Configure the Sync Profile Target

   In your sync profile, set the target connector to Adaptive Planning and configure these options:

   {
     "sheetName": "Headcount Plan",
     "versionName": "Plan",
     "importMode": "append",
     "isLevelAssigned": true,
     "autoCreateDimensions": false
   }
   

Import Modes

| Mode | Behavior | |------|----------| | append | Adds new rows without removing existing data. Default and safest for incremental syncs. | | replace | Clears all existing data in the sheet/version before importing. Use for full reloads. | | replace-at-level | Clears data only at a specific level before importing. Requires levelName to be set. |

Test Your Connection

Click Test Connection on the credential detail page. VersionForge calls the Adaptive XML API's exportSheets method to verify the token is valid and has metadata export permissions. A successful test confirms:

• The API token authenticates against the Adaptive instance
• The token's role has export metadata permissions
• The XML API endpoint is reachable

Common Issues

HTTP 401 or "Invalid token" -- The API token was revoked or entered incorrectly. Generate a new token from the Adaptive administration panel.

"Sheet not found" during push -- The sheetName in your sync profile does not match any sheet in the Adaptive model. Sheet names are case-sensitive. Use the metadata discovery endpoint to list available sheets.

"Version not found" -- The versionName does not match an active version. Verify the version name in Adaptive under Modeling > Versions.

Import permission denied -- The token's role lacks the Import Data permission on the target sheet. Contact your Adaptive administrator to update the role.