Decisioning Migration API decisioning-migration-api

On this page: Use the Decisioning Migration Service API to move Decision management objects between sandboxes with automated dependency analysis and rollback support, so you can transition decisioning content across environments while preserving data integrity.

The Decisioning Migration Service API enables you to migrate Decision management objects from one sandbox to another. The migration process runs as asynchronous workflows that include dependency analysis, execution, and optional rollback capabilities.

This API allows you to seamlessly transition your decisioning content between environments while maintaining data integrity and relationships.

To learn about the benefits and capabilities of Decisioning compared to Decision management, refer to this page.

Capabilities capabilities

The Decisioning Migration Service API provides the following capabilities:

Prerequisites prerequisites

Required permissions permissions

To use the Migration API, you need appropriate permissions in both the source and target sandboxes:

Source sandbox - Read access to Decision management objects

Target sandbox - Create and edit access to Decisioning objects

Typical permissions include:

Prepare your target sandbox target-sandbox-preparation

Before running a migration, ensure your target sandbox is properly configured:

For more information about sandbox management, refer to Use and assign sandboxes.

Cross-Sandbox Migration Prerequisites cross-sandbox-prerequisites

When source sandbox ≠ target sandbox, the following items are required:

API basics api-basics

Base URL base-url

Use the following base URL:

Authentication authentication

All API requests require the following headers:

For detailed instructions on setting up authentication, refer to the Journey Optimizer authentication guide.

Migration workflow migration-workflow

The migration process consists of two main steps: analyzing dependencies and executing the migration. Follow these steps to ensure a successful migration.

Step 1: Analyze dependencies analyze-dependencies

Before migrating, use the dependency workflow to identify what needs to be mapped from Decision management to Decisioning in your target sandbox. This analysis helps you understand the relationships between objects and prepare the necessary mappings.

Create a dependency workflow create-dependency-workflow

Use the following API call to create a dependency analysis workflow.

API format

POST /workflows/generate-dependencies

Sandbox-level dependency (recommended first)

Start with a sandbox-level analysis to get a complete view of all dependencies:

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies?request-level=sandbox" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" }
  }'

Offer-level dependency

To analyze dependencies for specific offers only, call the same endpoint with request-level=offer in the query string and provide an offersList array in the body with the offer IDs you want to analyze.

Decision-level dependency

To analyze dependencies for specific decisions only, use request-level=decision in the query string and provide a decisionsList array in the body with the decision IDs you want to analyze.

Check dependency workflow status poll-dependency-status

Poll the dependency workflow to check when the analysis is complete.

API format

GET /workflows/generate-dependencies/{id}

Request

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

When the status field shows Completed, the dependency analysis is ready. Use the workflow output to build your migration dependency mappings:

You supply these mappings in the dependency object of the migration request in Step 2.

Step 2: Execute the migration execute-migration

Once you have analyzed the dependencies and prepared your mappings, you can execute the migration.

Create a migration workflow create-migration-workflow

Use the dependency mappings from Step 1 to configure and execute your migration.

API format

POST /workflows/migration

Sandbox-level migration

To migrate all decisioning objects from one sandbox to another:

curl --request POST \
  --url 'https://decisioning-migration.adobe.io/workflows/migration?request-level=sandbox' \
  --header 'Authorization: Bearer <IMS_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-gw-ims-org-id: <IMS_ORG_ID>' \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" },
    "createDataStream": true,
    "dependency": {
      "profileAttributes": {
        "sourceAttr1": "targetAttr1"
      },
      "segments": {
        "sourceSegmentKey1": {
          "namespace": "<TARGET_SEGMENT_NAMESPACE>",
          "id": "<TARGET_SEGMENT_ID>"
        }
      },
      "contextAttributes": {
        "sourceCtx1": "targetCtx1"
      },
      "datasetName": "<TARGET_DATASET_NAME>"
    }
  }'

Offer-level migration

To migrate specific offers only, use request-level=offer in the query string and add an offersList array to the body:

"offersList": ["offer-id-1", "offer-id-2"]

Decision-level migration

To migrate specific decisions only, use request-level=decision in the query string and add a decisionsList array to the body:

"decisionsList": ["decision-id-1", "decision-id-2"]

Request fields

Monitor migration status poll-migration-status

Poll the migration workflow to track its progress.

API format

GET /workflows/migration/{id}

Request

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/migration/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

Migration results

When the status field shows Completed, the migration was successful. The workflow result includes:

When the status field shows Failed, review the errors[] array and result.error field for details about what went wrong.

Every workflow (dependency, migration, and rollback) returns the same resource fields:

Validate your migration validate-migration

After the migration completes successfully, verify that all objects were migrated correctly.

Validation checklist validation-checklist

Example test-runtime-delivery

If your migration created a datastream, you can test offer delivery using the following example:

curl --request POST \
  --url "https://edge.adobedc.net/ee/or2/v1/interact?configId=<DATASTREAM_ID>" \
  --header "Content-Type: application/json" \
  --header "x-request-id: <uuid>" \
  --data '{ "events": [ ... ] }'

Rollback a migration rollback

If you discover issues during validation, you can roll back a completed migration to restore the target sandbox to its previous state.

Create a rollback workflow create-rollback-workflow

Initiate a rollback by creating a rollback workflow that references the migration you want to revert.

API format

POST /workflows/rollback

Request

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/rollback" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{ "rollbackWorkflowId": "<MIGRATION_WORKFLOW_ID>" }'

Replace <MIGRATION_WORKFLOW_ID> with the ID of the migration workflow you want to roll back.

Monitor rollback status poll-rollback-status

Poll the rollback workflow to track its progress.

API format

GET /workflows/rollback/{rollbackWorkflowId}

Request

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/rollback/<ROLLBACK_WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

Handle concurrent workflows handle-concurrency

The Migration API allows only one workflow to run at a time per organization. If you attempt to create a new workflow while another is in progress, you will receive a 409 Conflict error response (“A workflow is already in progress…”).

In this case, wait for the in-progress workflow to complete, or retrieve the workflow ID and poll its status. Once the current workflow finishes, you can create a new one.

Migration scope and coverage migration-scope

Understanding the scope of the migration helps you plan and validate your transition from Decision management to Decisioning. This section outlines what is covered by the migration process and what requires manual action.

In-Scope: What is covered in-scope

The Migration API handles the following items and capabilities:

Out-of-Scope: What is not covered or requires manual action out-of-scope

The following items require manual action or are not supported by the migration tooling:

Entity mapping reference entity-mapping

When migrating from Decision management to Decisioning, entities are mapped according to the following table. The mappings include the primary Decisioning entities and additional associated entities created or used during migration.

Decision management to Decisioning Entity Mapping

Naming Conventions

The migration process applies naming conventions using the ExD_ prefix to ensure consistency and prevent naming conflicts.

Additional Attributes

Request and response model request-response-model

When migrating from Decision management to Decisioning, your application code must be updated to use the new request and response formats. Both systems use the Edge Network endpoint, but with different payload structures and field names.

Decision management Edge Request (Current) dm-request

The current Decision management Edge request follows this structure:

Endpoint:

POST https://edge.adobedc.net/ee/v2/interact

Headers:

Request Body Parameters:

Example request body:

{
  "xdm": {
    "dryRun": false,
    "propositionRequests": [
      { "activityId": "<ACTIVITY_ID>", "placementId": "<PLACEMENT_ID>", "itemCount": 3 }
    ],
    "profiles": [
      { "identityMap": { "ECID": [ { "id": "<ECID>", "primary": true } ] } }
    ],
    "validateContextData": true,
    "responseFormat": { "includeContent": true }
  }
}

Decisioning Edge Request (After Migration) decisioning-request

After migration, use the Decisioning request format via the same Edge Network endpoint.

Endpoint:

POST https://edge.adobedc.net/ee/v2/interact

Key Request Fields:

Example request body (server-side):

{
  "events": [
    {
      "query": {
        "identity": { "fetch": ["ECID"] },
        "personalization": {
          "surfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"],
          "schemas": [
            "https://ns.adobe.com/personalization/json-content-item",
            "https://ns.adobe.com/personalization/html-content-item"
          ]
        }
      },
      "xdm": {
        "eventType": "decisioning.propositionFetch",
        "environment": {
          "type": "browser",
          "browserDetails": { "viewportWidth": 1280, "viewportHeight": 900, "userAgent": "<USER_AGENT>" }
        },
        "identityMap": {
          "ECID": [ { "id": "<ECID>", "authenticatedState": "ambiguous", "primary": true } ]
        },
        "timestamp": "2025-09-08T12:00:00.000Z"
      },
      "data": {
        "__adobe": { "ajo": { "allowDuplicateDecisionItems": false } }
      }
    }
  ],
  "meta": {
    "state": {
      "domain": "my-web",
      "cookiesEnabled": true,
      "entries": [
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>" },
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>" }
      ]
    }
  }
}

Decisioning Edge Response decisioning-response

The Decisioning response contains multiple handles organized by concern type: personalization:decisions (the offers), locationHint:result, and state:store (the cookies to persist).

Response Structure:

{
  "requestId": "<REQUEST_ID>",
  "handle": [
    {
      "type": "personalization:decisions",
      "eventIndex": 0,
      "payload": [
        {
          "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
          "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
          "scopeDetails": {
            "decisionProvider": "AJO",
            "correlationID": "<CORRELATION_ID>",
            "characteristics": {
              "eventToken": "<base64 message-level event token>",
              "subPropositions": "<base64-encoded array of decision items>"
            },
            "rank": 1,
            "activity": {
              "id": "<campaignId>#<actionId>",
              "priority": 0,
              "matchedSurfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"]
            }
          },
          "items": [
            {
              "id": "36646bab-af1b-44c6-b632-bbfb9c357919",
              "schema": "https://ns.adobe.com/personalization/json-content-item",
              "data": { "content": "{ ...offer JSON... }" }
            }
          ]
        }
      ]
    },
    {
      "type": "locationHint:result",
      "payload": [
        { "scope": "EdgeNetwork", "hint": "ind1", "ttlSeconds": 1800 }
      ]
    },
    {
      "type": "state:store",
      "payload": [
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>", "maxAge": 1800 },
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>", "maxAge": 34128000 }
      ]
    }
  ]
}

Key Response Fields:

The characteristics.subPropositions string base64-decodes to the array of served items, each with its per-item token:

[
  {
    "id": "1ae75277-8832-4c23-bbbc-09f01cfe6c8b",
    "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
    "scopeDetails": { "decisionProvider": "EXD", "correlationID": "<CORRELATION_ID>-0", "rank": 1 },
    "items": [
      { "id": "dps:<schema>:1be64ff83a612488", "name": "ExD_Personal Loan Offer", "score": 997.0, "token": "CLaefQnVLcLbCtzEXV3Jeg" },
      { "id": "dps:<schema>:1be6516838e1248c", "name": "ExD_Home Loan Offer",     "score": 995.0, "token": "ALlB5KV1B0e+CpHoahi7Ew" },
      { "id": "dps:<schema>:1be650da3cd06e98", "name": "ExD_Auto Loan Offer",     "score": 994.0, "token": "koJTRQcwFkR92AqbZ88ytQ" },
      { "id": "dps:<schema>:1be65612d5a1248d", "name": "ExD_Fallback Offer",      "itemSelection": { "selectionDetail": { "selectionType": "fallback" } }, "token": "GHo4ow7h6iCzBOhYR1+6jg" }
    ]
  }
]

Implementation patterns implementation-patterns

Decisioning supports three implementation approaches:

Client-Side Implementation (Web SDK / Mobile SDK) client-side

The Web SDK or Mobile SDK handles all requests and cookie management automatically. The SDK stores and forwards both identity and cluster cookies with each request.

Cookie handling: Automatic — Web SDK manages kndctr_<OrgId>_identity and kndctr_<OrgId>_cluster cookies.

Server-Side Implementation (Edge Network API) server-side

The application server POSTs directly to Edge Network and must manually manage cookie forwarding. The server extracts browser cookies from incoming requests and forwards them to Edge Network via meta.state.entries[], then returns cookies in the response.

Cookie handling: Manual — App server must extract cookies from browser request, forward to Edge Network in request body, and set in response. Cookies must be explicitly forwarded in meta.state.entries for identity consistency.

Hybrid Implementation hybrid

Combines server-side rendering (initial page load) with client-side SDK (subsequent interactions). The server renders initial content via Edge Network, then Web SDK takes over for subsequent personalization requests.

Cookie handling: Mixed — Server side requires manual cookie forwarding to Edge Network; client side handled automatically by Web SDK. Ensure identity tokens from server-side rendering are available to client-side SDK for consistent identity resolution.

Event tracking and data collection event-tracking

To properly attribute decisioning results, enable frequency capping, and power AI-based ranking optimization, you must implement event tracking using the Decisioning event schema.

Required Event Fields event-fields

Both eventType and _experience.decisioning.propositionEventType are required. If either is missing, the corresponding display/interact counter will not increment.

Schema Requirements schema-requirements

Associate the Decisioning field group to your event dataset schema before migration:

Tracking Token Handling tracking-token

The tracking token must be handled according to these requirements:

Decisioning Event Examples event-examples

Each example echoes back the served proposition (including its scopeDetails, which carries characteristics.subPropositions) and sets both eventType and propositionEventType. Counters increment against the items in subPropositions; propositionAction.tokens selects which items.

Display Events

Display events notify Decisioning when an offer is shown to a user. Provide the token(s) of the shown item(s), or omit tokens to increment the display counter for all items in subPropositions:

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionDisplay",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg", "ALlB5KV1B0e+CpHoahi7Ew"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Interact (Click) Events

Interact events track when a user clicks or engages with a displayed offer. You must provide exactly one token identifying the clicked item:

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionInteract",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "interact": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Custom Events

A custom event uses a customer-defined eventType (any value other than decisioning.proposition<Display|Interact|Dismiss>) and sets all of display/interact/dismiss to 0 in propositionEventType (classified as OTHER). Custom events are decoded like display events (multi-token filtering) against subPropositions, and are evaluated via the configured PQL:

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "originalTimestamp": 1700000
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "add-to-cart",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 0, "interact": 0, "dismiss": 0 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

These events enable frequency capping, out-of-the-box reporting, and AI-driven ranking optimization in Decisioning. For sending proposition events with the Web SDK, see Code-based experience: Decisioning implementations.

End-to-end Migration Process migration-process

Related topics related-topics