Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/skills/dx-sap-spartacus-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ When a developer has added the connector to a Spartacus app (`ng add @contentsta
- **Idempotent seed and publish**: entries upsert by their SAP uid, so re-runs update in place.
- **Verification**: a round-trip comparison against SAP and a Delivery API read of the home page.
- **Localization**: localized content and images per language from SAP's own localized responses.
- **SAP product picker**: optionally installs and configures the SAP Commerce Cloud marketplace app, so editors pick carousel products from SAP instead of typing SKUs. The agent checks the picker, repairs it at most twice, then lets the user fall back to the plain SKU list.
- **SAP product picker**: optionally installs and configures the SAP Commerce Cloud marketplace app, so editors pick carousel products from SAP instead of typing SKUs. It works for B2C and B2B sites (for example the electronics and powertools demos), and is set up only when the installed connector can render it: the npm connector 0.1.0 keeps the plain SKU list, while a connector that reads `sap_products` gets the picker. Before installing, a preflight checks that the app's SAP server has a trusted certificate, the base site, a working product search and the carousel codes, and stops the run if not. After the run the agent checks the picker, repairs it at most twice, then lets the user fall back to the plain SKU list.
- **Your own login**: writes with a management token, or with the user's `csdx auth:login --oauth` session (required for the marketplace app).

## Example prompts
Expand All @@ -31,6 +31,7 @@ When a developer has added the connector to a Spartacus app (`ng add @contentsta
- "Re-run the SAP import; we changed the homepage banners."
- "The import says a component type is unknown. What do I do?"
- "Let our editors pick the carousel products from SAP instead of typing SKUs."
- "Set up the SAP product picker on our powertools B2B demo stack too."

## References

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?dx-sap-spartacus-import"'
min: 1
---
The agent loads the `dx-sap-spartacus-import` skill.
7 changes: 7 additions & 0 deletions evals/routing-dx-sap-spartacus-import-3/prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
name: routing-dx-sap-spartacus-import-3
tags: [routing, dx-sap-spartacus-import]
max_turns: 3
timeout_seconds: 180
---
We imported our SAP powertools-spa B2B storefront into Contentstack with the Spartacus connector. Now set up the SAP Commerce Cloud product picker on the powertools carousels, like we did for electronics.
28 changes: 17 additions & 11 deletions skills/dx-sap-spartacus-import/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,35 +28,38 @@ Use another skill for:
Confirm, without asking for secret values:

1. The current directory is the Spartacus project root and `node_modules/@contentstack/contentstack-spartacus-connector/import-export/starter-pack/content_types` exists. If not, the connector isn't installed: run `ng add @contentstack/contentstack-spartacus-connector` first, or point `CONNECTOR_STARTER_PACK` at a connector checkout.
2. The SAP baseSite uid (for example `electronics-spa`) and the OCC v2 base URL (`https://HOST/occ/v2`). List baseSites with `curl -s "$OCC_BASE_URL/basesites"`.
2. The SAP baseSite uid (for example `electronics-spa`) and the OCC v2 base URL (`https://HOST/occ/v2`). List baseSites with `curl -s "$OCC_BASE_URL/basesites"` (add `-k` only when the user set `OCC_INSECURE_TLS=1` for a self-signed dev server).
3. The target stack is **new or dedicated to this import**. The publish step publishes every entry and asset in the stack.
4. `python3 --version` is 3.9 or later. The Python scripts use only the standard library.
5. How the run writes: with `CS_MANAGEMENT_TOKEN`, or, without one, as the user's own `csdx auth:login --oauth` session. The SAP Commerce Cloud app step always needs that csdx session (a management token can't install apps), plus Node.js and `@contentstack/cli` on `PATH`.
6. For the product picker: the SAP server the app will search (`SAP_APP_API_BASE_URL`, with a publicly trusted certificate), its base site (`SAP_APP_BASE_SITE`: `electronics` for the electronics demo, `powertools-spa` for the B2B powertools demo) and its Backoffice URL. It must carry the same catalog as the storefront's OCC. See [references/sap-commerce-app.md](references/sap-commerce-app.md).

## Instructions

1. Resolve `<SKILL_DIR>`: the folder this `SKILL.md` was loaded from. Run every script by absolute path, `python3 "<SKILL_DIR>/scripts/orchestrate.py"`, from the Spartacus project root.
2. Ask the user to export the variables under Environment Variables in their own shell. Never ask them to paste values into chat.
3. **Dry run** (writes nothing):
2. Ask the user to export the variables under Environment Variables in their own shell. Never ask them to paste values into chat. Required: `CS_API_KEY` and `OCC_BASE_URL`. Optional: `OCC_INSECURE_TLS`, `CS_MANAGEMENT_TOKEN` (else the csdx login), the `SAP_APP_*` picker settings, and `CS_DELIVERY_TOKEN` (only for the final delivery check; a fresh stack gets one after the run).
3. **Dry run** (writes nothing, about 2 minutes). Pass the same `--locales` and `--run-dir` you'll use for the write, so the gate reports show the full plan:
```bash
python3 "<SKILL_DIR>/scripts/orchestrate.py" --site electronics-spa
python3 "<SKILL_DIR>/scripts/orchestrate.py" --site electronics-spa \
--locales de=de-de,ja=ja-jp,zh=zh-cn --run-dir <run-dir>
```
It extracts the site, builds the plan and prints both gate reports. Summarize them for the user: pages, component entries, assets, which slots stay with SAP, any unknown component types, where carousel SKUs go (`products` or `sap_products`), and whether writes run as the management token or the csdx login.
4. **Gate 1, model approval.** If the report lists unknown typeCodes, stop. Each one is either authored (add it to `component_map` in `scripts/registry/connector.registry.json` with its connector content type and field mapping) or functional (add it to `occ_only_types.types`). Re-run the dry run. Pass `--approve-model` only after the user agrees.
5. **Gate 2, pre-publish.** Show the counts and the target stack and environment. The run stops here if the plan writes a content type or field the installed starter pack lacks. The fix is a newer connector (`npm i @contentstack/contentstack-spartacus-connector@latest`), not editing the stack by hand.
6. With the user's explicit yes, run the write:
5. **Gate 2, pre-publish.** Show the counts and the target stack and environment: gate 2 prints the stack's name and whether it's empty, the content types (the connector's full starter pack, which replaces existing types with the same uids), and components, navigation entries and pages separately. The run stops here if the plan writes a content type or field the installed starter pack lacks. The fix is a newer connector (`npm i @contentstack/contentstack-spartacus-connector@latest`), not editing the stack by hand.
6. With the user's explicit yes, run the write. It takes a while (a demo site with three languages: about 45 minutes, roughly 10 per language), so run it in the background with its output in a log, check the log until it ends, and never start a second write while one is running:
```bash
python3 "<SKILL_DIR>/scripts/orchestrate.py" --site electronics-spa \
--approve-model --approve-publish --env development
--approve-model --approve-publish --env development \
--locales de=de-de,ja=ja-jp,zh=zh-cn --run-dir <run-dir> > <run-dir>/write.log 2>&1
```
This sets up the SAP Commerce Cloud app when carousels use the picker, imports the starter-pack content types, uploads images, upserts entries, creates the environment if needed, publishes, and runs the verify steps.
7. **Carousel products.** With `SAP_APP_API_BASE_URL`, `SAP_APP_BASE_SITE` and `SAP_APP_BACKOFFICE_URL` exported, carousels go into `sap_products`, the SAP Commerce Cloud app's product picker; otherwise into the plain `products` SKU list. Force either with `--carousel-field products|sap_products`. After a picker run, follow "Verify, retry, then ask" in [references/sap-commerce-app.md](references/sap-commerce-app.md): check the picker, repair at most twice, then let the user choose between fixing it and falling back to `products`.
7. **Carousel products.** Carousels go into `sap_products`, the SAP Commerce Cloud app's product picker, when `SAP_APP_API_BASE_URL`, `SAP_APP_BASE_SITE` and `SAP_APP_BACKOFFICE_URL` are exported **and** the installed connector reads `sap_products` (the connector release, or a build or checkout of the connector repo's main branch). Otherwise they go into the plain `products` SKU list: the npm connector 0.1.0 reads only `products`, so with it the picker isn't set up and gate 2 says why. The version number can't tell them apart (a build from main also says 0.1.0), so the orchestrator checks the connector's code. Force either with `--carousel-field products|sap_products`. It works the same for B2C and B2B sites. Gate 2 runs a preflight on the picker's SAP server (trusted certificate, base site present, product search returns products without a login, carousel codes found); if it fails, the write stops with exit code 4 before the app is installed. Quote the `FAIL` line to the user with its fix. If the picker is forced onto a connector that reads only `products`, gate 2 warns that the carousels would render empty; tell the user before the write. You may have no browser for the picker check: then ask the user to do it (open a carousel entry, check the SAP Products field lists products, click Add Product(s)). After a picker run, follow "Verify, retry, then ask" in [references/sap-commerce-app.md](references/sap-commerce-app.md): check the picker, repair at most twice, then let the user choose between fixing it and falling back to `products`.
8. For more languages, add `--locales de=de-de,ja=ja-jp,zh=zh-cn` (SAP isocode = Contentstack locale). Locales are created when missing, with the master locale as fallback.
9. Report the result from `manifest.json` in the run directory, then point the user at the app config: `cmsPageContentType: 'landing_page'`, a `localeMapping` that matches the locales imported, and `occFallback: true`.
9. Report the result from `manifest.json` in the run directory. `warn` on seed, publish or a locale means some items failed (their ERR lines are in the output); re-running is safe. A `check` on the delivery read with "no CS_DELIVERY_TOKEN yet" is expected on a fresh stack: tell the user to create a delivery token for the environment and re-run `verify/cda_read.py`, as the manifest note says. Then point the user at the app config: `cmsPageContentType: 'landing_page'`, a `localeMapping` that matches the locales imported, and `occFallback: true`.

### How the pipeline works

`extract → nav-resolve → model → gate 1 → gate 2 → sap-app → seed → publish → verify → localize`. Stage details, run-directory files and flags are in [references/pipeline.md](references/pipeline.md). The mapping rules (which SAP templates, slots and typeCodes become which content types) are in [references/mapping-profile.md](references/mapping-profile.md). The SAP Commerce Cloud app stage, its auth and its recovery steps are in [references/sap-commerce-app.md](references/sap-commerce-app.md).
`extract → nav-resolve → model → gate 1 → gate 2 (+ SAP picker preflight) → sap-app → seed → publish → verify → localize`. Stage details, run-directory files and flags are in [references/pipeline.md](references/pipeline.md). The mapping rules (which SAP templates, slots and typeCodes become which content types) are in [references/mapping-profile.md](references/mapping-profile.md). The SAP Commerce Cloud app stage, its auth and its recovery steps are in [references/sap-commerce-app.md](references/sap-commerce-app.md).

### Rules

Expand Down Expand Up @@ -109,7 +112,7 @@ Never print, echo, log or store the management token, delivery token, API key or
- `CS_MASTER_LOCALE`: defaults to `en-us`.
- `CS_PREVIEW_URL`: storefront URL set on the environment for every locale, so Live Preview loads (default `http://localhost:4200`).
- `CONNECTOR_STARTER_PACK`: override the starter-pack path.
- `SAP_APP_API_BASE_URL` (host, no scheme), `SAP_APP_BASE_SITE`, `SAP_APP_BACKOFFICE_URL`: the SAP server the app's picker searches. Setting all three turns on the picker.
- `SAP_APP_API_BASE_URL` (host, no scheme), `SAP_APP_BASE_SITE` (for example `electronics` or `powertools-spa`), `SAP_APP_BACKOFFICE_URL`: the SAP server the app's picker searches. Setting all three turns on the picker.
- `SAP_APP_API_ROUTE` (default `/occ/v2/`), `SAP_APP_CONFIG_NAME` (default `hti`), and optionally `SAP_APP_UID`, `CS_ORG_UID`.

## References
Expand All @@ -126,5 +129,8 @@ Never print, echo, log or store the management token, delivery token, API key or
User: Import our SAP electronics storefront into my new stack.
Assistant: Runs the dry run, then reports: "6 pages (/, /faq, /contact, /sale, shared /product and /category layouts), 34 components, 79 navigation entries, 37 images. SearchBox, MiniCart, SiteContext and SiteLinks stay with SAP. No unknown component types. Gate 2 will write to stack 'SAP demo' and publish everything in it to 'development'. Shall I run it?" and waits.

User: Set up the SAP product picker on our powertools demo stack too.
Assistant: Asks for the SAP server and Backoffice URL the app should search (base site `powertools-spa`), runs the dry run with the `SAP_APP_*` variables exported, and reports the preflight: "powertools-spa exists, search returns 252 products, 14 of 14 carousel codes found." Then it asks before the write, which installs and configures the app once, fills both carousels' `sap_products`, and checks the picker in the browser.

User: Just publish it, skip the dry run.
Assistant: Explains that the write step only runs after the gate reports have been reviewed, runs the dry run (it writes nothing and takes about a minute), and asks for the go-ahead with the counts in front of the user.
Loading
Loading