Skip to main content

Summary

This document describes how to migrate to version 3.0.0 of Ark with respect to the connector-routing (CR) feature.

CR's read path is binding-only: every routed call resolves the target connector by looking up an open row in [dbo].[Binding]. If a binding does not exist for an entity that was created under a prior release, the call fails with CRT004005 (404 — no open binding).

This migration backfills [dbo].[ArkEntity] and [dbo].[Binding] for entities the client created under the prior release via the admin mapping endpoints (party/customer, account, card). The (arkId, vendorId) pairs live exclusively in the ark-connector-uda database; this script exports them from there and imports them into ark-platform.

Records are required for the following entities:

  • Parties / Customers
  • Accounts
  • Cards

Notifications and payees are intentionally out of scope (the client did not use those endpoints; notifications are policy-mechanism in CR and need no binding).

The procedure should be performed after all database schema migrations from version 3.0.0 have been run and before the new application code is deployed.

Prerequisites

  1. Connector-routing schema migration applied. Verify the following tables exist in ark-platform:
SELECT name FROM dbo.sys.tables
WHERE  name IN ('Connector', 'ArkEntity', 'Binding',
                'ConnectorPolicy', 'ConnectorPolicyCondition');

All five must be present.

  1. The [dbo].[Connector] catalog has a row with connectorKey = 'ultracs_v1'. Verify via:
curl -fsS "$ADMIN_BASE/v1/admin/connectors" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq '.connectors[].connectorKey'

If the row is missing, register it via Step 1 of docs/delivery/connector-routing-cutover.md (POST /v1/admin/connectors) before continuing.

  1. SQL Server Management Studio (SSMS) connection to the instance hosting both ark-platform and ark-connector-uda. Both databases must be on the same instance for the SSMS Import/Export Wizard step.

  2. Tools → Options → Query Results → SQL Server → Results to Grid → tick Include column headers when copying or saving the results.

Procedure

You must perform this procedure once for each (clientId, brandId) combination required.

1. Confirm UDA customer/party table​

export-customers.sql ships with placeholder column names. Confirm the real names by running its discovery query against ark-connector-uda:

SELECT TABLE_NAME, COLUMN_NAME
FROM   INFORMATION_SCHEMA.COLUMNS
WHERE  TABLE_CATALOG = 'ark-connector-uda'
  AND  (TABLE_NAME LIKE '%ustomer%' OR TABLE_NAME LIKE '%arty%')
ORDER BY TABLE_NAME, ORDINAL_POSITION;

Replace the three <PLACEHOLDER> tokens in export-customers.sql with the real table/column names. By the Account/Card naming convention, the table is likely [dbo].[Customer] with [CUSTOMER_ARK_ID] and [CUSTOMER_NUMBER] — but verify, don't assume.

2. Export from ark-connector-uda​

Repeat for each of export-customers.sql, export-accounts.sql, export-cards.sql:

  1. Open the file in SSMS.
  2. Set values for clientId and brandId.
  3. Execute the query against the ark-connector-uda database.
  4. Right-click the top-left corner of the Results pane → Save Results As....
  5. Name the file bindings-<entity>-<tenant>.csv and save as .csv.

You will produce three CSV files per tenant.

3. Stage in ark-platform​

  1. Run 01-create-staging.sql against the ark-platform database to create [dbo].[CrBindingStaging]. Safe to re-run.

Then, for each of the three CSVs:

  1. Right-click ark-platform in Object Explorer → Tasks → Import Data....
  2. On the Choose a Data Source step, select Flat File Source.
  3. Select the .csv file (e.g. bindings-cards-acme.csv).
  4. On the Choose a Destination step, select Microsoft OLE DB Driver for SQL Server, configure and test the connection to ark-platform.
  5. On the Select Source Tables and Views step, set the destination to [dbo].[CrBindingStaging]. Append mode (do not replace).
  6. Step through the wizard, choose Run immediately, click Finish.

After all three CSVs are imported, run:

SELECT COUNT(*) FROM [dbo].[CrBindingStaging];

The count must equal the sum of rows across the three exports.

4. Apply to ArkEntity and Binding​

  1. In 02-apply-bindings.sql, set @migrator to a meaningful audit string, e.g. 'cr-migration-3.0.0' or the operator's identifier.
  2. Execute the whole file.
  3. Confirm the output: CR binding migration completed successfully.

If any of the four guards in section (b) fail (@migrator not set, cross-tenant arkId, or coverage assertion), the transaction rolls back and the error is re-raised with the original severity.

5. Verify​

-- Binding count for the connector.
SELECT COUNT(*) FROM [dbo].[Binding] WHERE connectorId = 'ultracs_v1';

-- Per-tenant binding count.
SELECT clientId, brandId, COUNT(*)
FROM   [dbo].[Binding] b
JOIN   [dbo].[ArkEntity] ae ON ae.arkId = b.arkId
WHERE  b.connectorId = 'ultracs_v1'
GROUP BY clientId, brandId;

Pick one card known to have existed pre-migration, and call a card-controls endpoint against its arkId. Expect HTTP 200 (not CRT004005).

6. Cleanup​

Once all tenants are migrated and verified:

TRUNCATE TABLE [dbo].[CrBindingStaging];

Idempotence and rollback

  • Re-running section (b) is safe. The INSERTs use NOT EXISTS against the PK triple (arkId, connectorId, vendorId) for Binding and against arkId for ArkEntity; a second run is a no-op.
  • Rolling back the application release leaves the Binding and ArkEntity rows in place. The prior release ignores them (the tables exist post-schema-migration but are not read by the prior code path).
  • Errors roll back the whole section-(b) transaction atomically. The staging table is untouched on failure, so re-running after fixing the underlying issue is safe.

References

  • Runtime code path: apps/ark-platform/src/common/connector-routing/binding.repository.ts:110-145 (insertOpenBinding); section (b) mirrors its idempotence semantic in pure SQL.
  • Read path that requires bindings: apps/ark-platform/src/common/connector-routing/connector-routing.service.ts:175-182 (lookupByBinding).
  • Cutover runbook: docs/delivery/connector-routing-cutover.md — prerequisite Step 1 (connector catalog registration), and the line-138 "build per-tenant" hand-off this script fulfils.