Skip to content

Customer data — user guide#

This guide walks through moving customer configuration between CommandCenter environments with a customer-data package (.bmpkg): export it here, look at it, import it there. How it works underneath, and the differences between package versions, are on the customer data page.

Where the screens are

Export and Import are the two buttons next to the search box on the Customers page. Each stage row also has an Export icon, next to Clone, for that one stage. Every export and import runs as a task you can follow under Background tasks.

Before you start#

What a package carries. Customers, their stages (environments), the application versions and tool schedules they use, and — if you ask — their deploy, server and exception logs. These are CommandCenter's own records about the customer.

What it does not carry. The customer's BenefitManager databases. A stage in the package points at a SQL instance and a database by name; that database must exist on the target instance already, or be restored there separately. After an import, a stage whose database is missing shows up but does not work.

What you need.

  • The target environment must have customer-data storage configured. Without it, export and import are refused straight away with "Customer-data storage unavailable".
  • The CommandCenter database must allow snapshot isolation. If it does not, the task fails with the ALTER DATABASE … SET ALLOW_SNAPSHOT_ISOLATION ON statement to give your DBA.

Export#

  1. On the Customers page, search for the customers you want (or leave the search empty for all), then select Export. For a single stage, select the Export icon on its row instead.
  2. In the dialog:
    • Source environment — the name of the environment you are exporting from. It is written into the package, and shown later wherever the package is looked at. It starts as the Stage on the Settings page, the name in the page header; you can type another, and the field suggests the environments the BMO agents report.
    • Customers — every customer the page shows starts ticked; untick the ones you do not want, or use Select all / Select none. (Not shown when you export a stage.)
    • Log tables — tick deploy, server and/or exception logs. Leave them all unticked to export configuration only, which is small and fast.
    • Only the last … days of logs — starts at 120 days; clear it for all history. Logs are most of a package's size, so shorten it when you need less.
  3. Select Start export. The dialog stays open and shows the export's steps as they run; Open the task page shows the same in full, and Close leaves it running.
  4. When it has finished, the dialog — and the task page — shows the package, its size, digest and contents, with Download package. The download is checked against the package's SHA-256 digest in your browser before it is saved; if they differ, you are told and nothing is saved.

With a very long list of customers ticked but not all of them, the dialog asks you to narrow the selection or tick them all: exporting every customer needs no list at all.

The package stays downloadable for two hours after the export finished or was last downloaded. After that the task page says "The package has been removed": export again.

Look at a package before importing it#

The Import dialog shows both of these after the upload, before anything is written:

  • Package — where and when it was exported, its size and digest, the rows per table (with the oldest and newest log entry), the customers and stages it holds, and the tool schedules that will run once it is imported. This is what bmo manage customer-data show <file> --verbose prints, read by the same code.
  • What already exists here — per table, how many are new and how many are already in this environment, with the names of the customers and stages that are.

Look at the tool schedules in particular: every active one will run on the target environment.

Import#

  1. On the Customers page of the target environment, select Import.
  2. Choose the .bmpkg file and select Upload. The file goes up in chunks with a progress bar; a chunk that fails on the way is sent again once. A package of another version is refused here with "Package schema version … is not supported".
  3. Review the package and what already exists (see above), then choose:
    • When a customer or stage already exists — Skip, Replace or Fail; see Choosing what happens to existing data below.
    • SQL instance for added and replaced stages — read-only. It is the Standaard SQL Server instance on the Settings page, the same default a stage added by hand gets. The stages the import adds or replaces go there, under the database name in the package. When that setting is empty or cannot be read, Import stays disabled while the import would add or replace a stage.
    • Stages that the import skips keep their own instance and database.
    • A different instance, or a different database name, can only be chosen with the bmo command-line tool (--override-instance, --override-database).
  4. Select Import. With Replace and stages that already exist, you are asked to type replace first.
  5. The dialog stays open and follows the import: its status and its steps as they happen, the same as on the task page, which Open the task page shows in full. When it has finished, the last step lists the counts — customers and stages inserted, kept and replaced, log rows imported — and the Customers list behind the dialog picks up the new customers and stages. Cancel task stops it after the current step. Close only closes the dialog: the import carries on, and the task page on Background tasks shows it later; reload the Customers page once it has succeeded.

Closing the dialog before step 4 removes the upload. An upload you do not import is removed after 24 hours anyway.

Choosing what happens to existing data#

The import matches customers by name and stages by their identifier, which a stage keeps for life, whatever it is called. Application versions are matched by version number and reused.

Choose When Existing customers and stages
Skip Adding new customers or stages next to what is there; importing the same package twice kept exactly as they are; nothing is imported under an existing stage
Fail You expect nothing of it to exist yet, and want to be told if it does the import is refused before anything is written, naming what already exists
Replace Making existing stages match the package — for example restoring a stage's configuration from an earlier export the customer is kept, with all its other stages; each stage in the package is removed and imported again

Replace, in more detail:

  • It only touches the stages that are in the package.
  • It refuses a stage that is active or online, or still being cloned. Switch it offline and inactive in the stage's details on the Customers page first, and back on after the import.
  • For a replaced stage, its server log is deleted; its deploy log, exception log and tool-schedule run history are kept but no longer linked to it; its tool schedules are replaced by the package's.
  • There is no undo. Export the stage first if you might want it back.

Common tasks#

Copy a customer from Acceptatie to Productie

  1. On Acceptatie, search for the customer and select Export — configuration only, or with a few days of logs.
  2. Make sure the customer's databases exist on Productie's SQL Server.
  3. On Productie, select Import and choose Skip. The dialog shows the SQL instance the added stages go on: Productie's default SQL Server instance from its Settings page.
  4. Check the new stages on the Customers page, and their schedules under Schedules.

Refresh a stage's configuration from an earlier export

  1. Switch the stage offline and inactive in its details on the Customers page.
  2. Select Import, choose the package and Replace, and type replace to confirm.
  3. Check the stage, then switch it back online and active.

Keep a copy before a risky change

Export the customer with its logs and keep the file — outside CommandCenter, since the download expires after two hours. Import it with Replace to put the configuration back.

After an import#

  • Tool schedules: an active schedule's next run is moved forward to its next regular moment on the target, so it does not fire the moment it arrives. A schedule with a start date in the future keeps it and runs then.
  • Databases: open each new stage once to check it reaches its database.
  • Logs: log rows are imported only for the stages the import added or replaced. For a replaced stage, its earlier deploy and exception logs stay (unlinked from it) next to the imported ones, so history from the package and from the target can both be there.

When something goes wrong#

What you see Why What to do
Customer-data storage unavailable The environment has no customer-data storage configured Ask for CustomerData:Storage to be set
Package schema version 1 is not supported The file was made by BMO before v1.7.0 Export it again from the source — see package versions
These already exist in the target and the import was asked to fail on conflicts Fail found existing customers or stages Import with Skip or Replace, or not at all
Stages cannot be replaced: '…' is active or online Replace met a live stage Switch it offline and inactive, then commit again
Snapshot isolation is not enabled on database … A database setting Give the statement in the message to your DBA
The import task failed before or on Import customers, stages, versions and schedules Something went wrong on that step; the task page shows the reason Nothing was imported. Fix the cause, upload the file again and import it
The import task failed on an Import … log step The customers and stages are in; the log rows after the failure point are not A second import with Skip adds no logs to stages that now exist. If you need the missing logs, switch those stages offline and inactive and import again with Replace
The download's digest does not match The download was cut off Download again
The package has been removed More than two hours since the export or the last download Export again
The review or commit step answers with a gateway error for a very large package A known limit of this release: those steps read the whole package while you wait Export with fewer log days, or split the export per customer

From the command line#

The bmo CLI (bmo manage customer-data export | import | show) still talks to BMO's own service, not to CommandCenter, until its move to CommandCenter (ADR 0005 Phase 5). It reads and writes the same version-2 packages, so a file from either side imports on the other. Two differences to keep in mind: bmo manage customer-data import requires --override-instance, and BMO's importer treats Skip and Replace differently — see same package, different importer. The commands themselves are in the orchestrator guide.