3.x → 8.x

This guide describes the breaking changes required when upgrading from the 3.x to the 8.x release.

---

Embed URL — Required app Query Parameter

In 8.x, the /embed path no longer loads the Variant Configuration application directly. This change was made to support multiple applications running under the same host. You must now specify which application to load using the app query parameter.

	URL
Old	https://{{app-name}}.cfapps.us10.hana.ondemand.com/embed
New	https://{{app-name}}.cfapps.us10.hana.ondemand.com/embed?app=vc-ui

Update any iframe src attributes, deep links, or configuration that reference the /embed path to include ?app=vc-ui.

---

INITIAL-CONTEXT Event Payload

The following changes apply to the configuration object sent via the INITIAL-CONTEXT message channel event. Review each section below and update your integration accordingly.

---

Breaking Changes

1. AppSettings — Settings must be nested under a product key

3.x: AppSettings was a flat object containing Variant Configuration settings directly at the top level.

8.x: To support multiple products, all settings must now be nested under a product-specific key. For Variant Configuration, use "VC".

- "AppSettings": {
-     "IsIncompleteAllowed": true,
-     "DefaultSummaryExpanded": true,
-     "DisplayVcValueWithDescription": false,
-     "DisplayShowPrices": false,
-     "DisplayQuantity": false,
-     "DisplayVcLog": false,
-     "DisplayVcTemplate": false
- }
+ "AppSettings": {
+     "VC": {
+         "IsIncompleteAllowed": true,
+         "DefaultSummaryExpanded": true,
+         "DisplayVcValueWithDescription": false,
+         "DisplayShowPrices": false,
+         "DisplayQuantity": false,
+         "DisplayVcLog": false,
+         "DisplayVcTemplate": false
+     }
+ }

---

2. Header and Item — Must be moved into VcSettings

3.x: Header and Item were top-level keys on the context object.

8.x: Both are nested inside a VcSettings wrapper object. A new required field IsComplete must also be included. Set this to false when sending the initial context.

- "Header": {
-     "SalesDocumentType": "ZORD",
-     "SalesOrganization": "C510",
-     "DistributionChannel": "00",
-     "Division": "50",
-     "SoldToParty": "200091",
-     "ShipToParty": "200091"
- },
- "Item": {
-     "Material": "VP-F",
-     "Plant": "5108",
-     "OrderQuantity": 1
- }
+ "VcSettings": {
+     "Header": {
+         "SalesDocumentType": "ZORD",
+         "SalesOrganization": "C510",
+         "DistributionChannel": "00",
+         "Division": "50",
+         "SoldToParty": "200091",
+         "ShipToParty": "200091"
+     },
+     "Item": {
+         "Material": "VP-F",
+         "Plant": "5108",
+         "OrderQuantity": 1
+     },
+     "IsComplete": false
+ }

---

3. SalesDocumentCurrency — Moved from Header to Item

3.x: SalesDocumentCurrency was a field on the Header object.

8.x: It belongs on the Item object inside VcSettings.

  "VcSettings": {
      "Header": {
-         "SalesDocumentCurrency": "USD"
      },
      "Item": {
+         "SalesDocumentCurrency": "USD"
      }
  }

---

4. Selectedvalues — Must be moved into VcSettings

3.x: Selectedvalues was a top-level array.

8.x: It is nested inside VcSettings.

- "Selectedvalues": [
-     {
-         "CharacteristicName": "SYS_IPC_YESNO",
-         "CharacteristicValue": "IPC",
-         "CharacteristicValueDescription": "Config in external online tool",
-         "UserModified": true
-     }
- ]
+ "VcSettings": {
+     ...
+     "Selectedvalues": [
+         {
+             "CharacteristicName": "SYS_IPC_YESNO",
+             "CharacteristicValue": "IPC",
+             "CharacteristicValueDescription": "Config in external online tool",
+             "UserModified": true
+         }
+     ]
+ }

---

Complete Before/After Example

3.x Payload

{
    "Api": {
        "BaseURL": "https://example.com/transact",
        "ApiKey": "your-api-key",
        "Authorization": { "Token": "" },
        "Headers": { "SERVER_LOG_WEBHOOK_URL": "" },
        "SapClient": "005",
        "SapCid": "",
        "SapLanguage": "EN",
        "ApiTimeout": 30000,
        "DebounceDelay": 2000
    },
    "AppSettings": {
        "IsIncompleteAllowed": true,
        "DefaultSummaryExpanded": true,
        "DisplayVcValueWithDescription": false,
        "DisplayShowPrices": false,
        "DisplayQuantity": false,
        "DisplayVcLog": false,
        "DisplayVcTemplate": false
    },
    "Header": {
        "SalesDocumentType": "ZORD",
        "SalesOrganization": "C510",
        "DistributionChannel": "00",
        "Division": "50",
        "SalesDocumentCurrency": "USD",
        "SoldToParty": "200091",
        "ShipToParty": "200091"
    },
    "Item": {
        "Material": "VP-F",
        "Plant": "5108",
        "OrderQuantity": 1
    },
    "Selectedvalues": [
        {
            "CharacteristicName": "SYS_IPC_YESNO",
            "CharacteristicValue": "IPC",
            "CharacteristicValueDescription": "Config in external online tool",
            "UserModified": true
        }
    ]
}

8.x Payload

{
    "Api": {
        "BaseURL": "https://example.com/transact",
        "ApiKey": "your-api-key",
        "Authorization": { "Token": "" },
        "Headers": { "SERVER_LOG_WEBHOOK_URL": "" },
        "SapClient": "005",
        "SapCid": "",
        "SapLanguage": "EN",
        "ApiTimeout": 30000,
        "DebounceDelay": 2000
    },
    "AppSettings": {
        "VC": {
            "IsIncompleteAllowed": true,
            "DefaultSummaryExpanded": true,
            "DisplayVcValueWithDescription": false,
            "DisplayShowPrices": false,
            "DisplayQuantity": false,
            "DisplayVcLog": false,
            "DisplayVcTemplate": false
        }
    },
    "VcSettings": {
        "Header": {
            "SalesDocumentType": "ZORD",
            "SalesOrganization": "C510",
            "DistributionChannel": "00",
            "Division": "50",
            "SoldToParty": "200091",
            "ShipToParty": "200091"
        },
        "Item": {
            "Material": "VP-F",
            "Plant": "5108",
            "OrderQuantity": 1,
            "SalesDocumentCurrency": "USD"
        },
        "IsComplete": false,
        "Selectedvalues": [
            {
                "CharacteristicName": "SYS_IPC_YESNO",
                "CharacteristicValue": "IPC",
                "CharacteristicValueDescription": "Config in external online tool",
                "UserModified": true
            }
        ]
    }
}