Seeding public apps and events

Source files in zwing-connect

Public catalog rows are maintained as JSON in the repo:

Shape of each file

Both files use the same envelope:

{
  "meta": { ... },
  "data": [ ... ]
}

• apps.json — meta includes matchKey (e.g. name), repo: "publicAppRepo", and optional objectIds for id conversion.
• events.json — meta includes matchKey (e.g. _id), repo: "publicEventRepo", and objectIds so string appId values in JSON are converted to ObjectIds when seeding.

After editing these files, deploy or sync them onto the seeders storage backend that ACS uses (see below), then call the seed API.

Prerequisites

1. App Connector Service (ACS) is running with global prefix /acs (see ACS API overview).
2. The seed JSON files are readable by ACS from the seeders storage disk (CommonService.seedData loads via Storage.disk('seeders').get(fileName)). In development this is typically wired to the storage/seeders content from the zwing-connect repo; in other environments follow your deployment’s storage mapping.
3. auth-key header — Routes use SsoApiKeyGuard; the header name is auth-key (SSO_TOKEN_HEADER in @libs/dip-v2). Use the API key configured for your environment (do not commit real keys into docs or git).

Optional body field ssoEnterpriseId on the seed request is required only when seeding data rows that use the sentinel ssoEnterpriseId: "DYNAMIC" (then the guard injects the tenant id into each row).

Seed API: POST /acs/common/seed

Upserts rows according to meta.repo and meta.matchKey (see CommonService.seed in zwing-connect).

Replace the host/port with your ACS URL (example uses localhost:5001). Replace YOUR_AUTH_KEY with a valid auth-key. Set fileName to the JSON file name on the seeders disk (apps.json or events.json).

Seed public apps

curl --location 'http://localhost:5001/acs/common/seed' \
  --header 'Content-Type: application/json' \
  --header 'auth-key: YOUR_AUTH_KEY' \
  --data '{
    "fileName": "apps.json"
}'

Seed public events

Seed apps first (or ensure every appId in events.json already exists as a public app _id).

curl --location 'http://localhost:5001/acs/common/seed' \
  --header 'Content-Type: application/json' \
  --header 'auth-key: YOUR_AUTH_KEY' \
  --data '{
    "fileName": "events.json"
}'

Success response shape: { message: 'Seed data successfully' } (wrapped by your serializer as usual).

Sync public events to enterprise apps: POST /acs/common/sync-public-events

After public apps/events are seeded (or updated), run sync so existing tenant apps that reference a public app (refPublicAppId) get matching enterprise events created or updated from public events (CommonService.syncPublicEventsToEnterpriseApps).

One enterprise

Pass ssoEnterpriseId to limit the run to that tenant:

curl --location 'http://localhost:5001/acs/common/sync-public-events' \
  --header 'Content-Type: application/json' \
  --header 'auth-key: YOUR_AUTH_KEY' \
  --data '{
    "ssoEnterpriseId": "01KA88F70R1TA3N0AE0RNPVR67"
}'

All enterprises

Omit ssoEnterpriseId (or send an empty JSON object {}) so every qualifying private app with a refPublicAppId is processed.

curl --location 'http://localhost:5001/acs/common/sync-public-events' \
  --header 'Content-Type: application/json' \
  --header 'auth-key: YOUR_AUTH_KEY' \
  --data '{}'

The handler returns a result object with counters such as enterpriseAppsProcessed, eventsInserted, eventsUpdated, orphanPublicAppRefs, and perAppSync (see SyncPublicEventsResult in zwing-connect).

Recommended order

1. Update storage/seeders/apps.json / events.json in zwing-connect and ensure files are on the seeders disk ACS reads.
2. POST /acs/common/seed with apps.json, then with events.json.
3. POST /acs/common/sync-public-events for the tenant(s) that should receive new/updated events on their enterprise apps.

Related

• Public apps and default connectors — how enterprise apps link to public apps and events.
• ACS API overview — other /acs/common routes.