Apply a data package

The JSON you authored in Create a data package sits on disk. It does not seed the tenant by itself. This page is how the rows land: three doors, insert-only, never a rewrite of a row the tenant already edited.

Note

Pack ids are {Model}/{id} (Tax/vat, LocalizationSaudiArabia/vat-SA). The script does not read the disk. GetService<IDataPackageService>().ApplyAsync goes through data transfer with mode=insert.

How to#

1. Pick the door.

Tenant setup is the product door for catalogs a tenant keeps. The click path for an empty stand is Open a stand: Ribbon → Administrator → Server → Tenant setup. The first press, while the country list is empty, is Load catalogs (when: "once"). After the stand is set up, open Data packages and press Apply on the row you want (when: "once" / country grouped as Base catalogs — countries, currencies, units, terms, taxes ({count} packages); when: "manual" is its own row).

A job may call ApplyAsync. There is no platform hook after model install: bumping modelVersion ships the files, it does not apply them. The bump belongs on Create a data package, not here.

Showcase / demo packs are when: "manual". Loading the showcase is a scheduled job, not an install step. Do not use that pack as a template for a catalog the tenant keeps.

2. Apply from a script. Resolve the platform service. Pass the pack id. Read Inserted / Skipped / Errors — a re-run that finds the rows already there is a skip, not an overwrite.

var packs = GetService<IDataPackageService>();
var result = await packs.ApplyAsync("Tax/vat");
// result.Ok, result.Inserted, result.Skipped, result.Errors

Example only — job ApplyVatPack is invented; no model ships that job today. Tax/vat is a real pack.

public class ApplyVatPackTask : TaskScriptBase
{
    public override async Task ExecuteAsync(TaskContext context)
    {
        var result = await GetService<IDataPackageService>()
            .ApplyAsync("Tax/vat");
        context.Log("+" + result.Inserted
            + " skip " + result.Skipped
            + " err " + result.Errors);
    }
}

On import, jobs arrive disabled. Turning isActive on is a separate step — Create a job.

3. Do not Recreate a live tenant. RecreateAsync wipes every row in the pack's tables, rewinds their number sequences to StartValue, then applies. A live tenant with documents pointing at those rows will lose integrity or refuse the wipe. Tenant setup never offers Recreate on Base catalogs (the button there is Apply / Top up). Do not call RecreateAsync from a script on a stand that already has references.

Warning

Live workspace sync and apply-file skip the files. A data package has no kind envelope, so the warning is not a workspace envelope: …/DataPackages/vat-SA.json with created=0 updated=0 errors=[] — that looks like success. Saving the JSON does not seed the tenant. Apply through IDataPackageService.ApplyAsync or Tenant setup Load catalogs / Apply.

Data transfer (the Developer page) is not this door. Its default mode is upsert and it will overwrite. ApplyAsync always uses insert.

What's not there yet#

There is no hook that applies packs when a model installs. The files land on disk; someone still presses Load catalogs / Apply, or a script calls ApplyAsync.

Where next#

• Create a data package
• Import via data transfer
• Data package
• Open a stand
• Create a job