80 added, 17 removed. Audit A to A.
---
name: sapcc-skill
- description: SAP Commerce Cloud skill for querying, administrating and operating a SAP CC (Hybris / CCv2) instance. Use this skill when the user asks to query, inspect, modify or administrate SAP Commerce Cloud – e.g. find products, orders, customers, run ImpEx, check cronjobs, execute business logic, or retrieve platform data. Automatically selects Groovy or FlexSearch based on request complexity.
+ description: SAP Commerce Cloud skill for querying, administrating and operating a SAP CC (Hybris / CCv2) instance, including Cloud Portal DevOps operations. Use this skill when the user asks to query, inspect, modify or administrate SAP Commerce Cloud data (products, orders, customers, cronjobs, business logic) via HAC, or to manage CCv2 Cloud Portal resources (environments, builds, deployments, backups, scaling, endpoints, certificates, scheduled activities, properties, roles). Automatically selects FlexSearch, Groovy, or a Cloud Portal API call based on request intent.
license: MIT
- compatibility: Requires Node.js >= 18. SAP CC credentials must be set in .env (HAC_URL, HAC_USERNAME, HAC_PASSWORD). Dependencies are installed automatically on first use — no manual npm install needed.
- metadata: {"author":"eljoujat","version":"2.0.0","homepage":"https://github.com/eljoujat/sapcc-skill","tags":["sapcommerce","hybris","groovy","flexiblesearch","ccv2","sap"]}
+ compatibility: Requires Node.js >= 18. SAP CC HAC credentials must be set in .env (HAC_URL, HAC_USERNAME, HAC_PASSWORD). Cloud Portal credentials must be set in .env (PORTAL_API_URL, PORTAL_SUBSCRIPTION_CODE, PORTAL_TOKEN_ENDPOINT, PORTAL_CLIENT_ID, PORTAL_CLIENT_SECRET, PORTAL_RESOURCE). Dependencies are installed automatically on first use — no manual npm install needed.
+ metadata: {"author":"eljoujat","version":"2.1.0","homepage":"https://github.com/eljoujat/sapcc-skill","tags":["sapcommerce","hybris","groovy","flexiblesearch","ccv2","sap","cloud-portal","devops"]}
---
# SAP Commerce Cloud Skill
- Interact with a SAP Commerce Cloud (Hybris/CCv2) instance using [`sapcc-hac-client`](https://www.npmjs.com/package/sapcc-hac-client) — currently supporting Groovy scripts and FlexibleSearch queries. Designed to be extended with additional SAP CC capabilities over time.
+ Interact with a SAP Commerce Cloud (Hybris/CCv2) instance using two complementary companion clients:
+ - [`sapcc-hac-client`](https://www.npmjs.com/package/sapcc-hac-client) (`scripts/execute.js`) — Groovy scripts and FlexibleSearch queries against the HAC (application data & business logic)
+ - [`sapcc-portal-cli`](https://www.npmjs.com/package/sapcc-portal-cli) (`scripts/portal.js`) — Cloud Portal REST API (environments, builds, deployments, backups, scaling, endpoints, certificates, scheduled activities, properties, roles)
+
+ Designed to be extended with additional SAP CC capabilities over time.
+
The skill automatically decides whether to use:
- **FlexibleSearch** – for data queries (SELECT/WHERE on SAP CC types)
- **Groovy script** – for complex logic, service calls, multi-step operations, or writes
+ - **Cloud Portal API** – for DevOps/platform operations (builds, deployments, environment lifecycle, scaling, backups, certs, roles)
Works with **Claude Code, Cursor, Copilot, Codex, Pi** and any agent compatible with the [Agent Skills](https://agentskills.io) format.
---
## Setup
- Dependencies are **installed automatically** the first time `execute.js` runs — no manual `npm install` needed.
+ Dependencies are **installed automatically** the first time `execute.js` or `portal.js` runs — no manual `npm install` needed.
Create a `.env` file in your project root (or in the skill directory as fallback):
```bash
cp <skill-dir>/.env.example .env
# Then fill in your values
```
- Required `.env` variables:
+ Required `.env` variables for HAC (Groovy/FlexSearch):
```
HAC_URL=https://backoffice.<your-instance>.commerce.ondemand.com
HAC_USERNAME=admin
HAC_PASSWORD=your_password
HAC_IGNORE_SSL=false # set true for self-signed certs
HAC_TIMEOUT=30000
```
+ Required `.env` variables for Cloud Portal (builds/deployments/environments/...):
+ ```
+ PORTAL_API_URL=https://portalapi.commerce.ondemand.com/v2
+ PORTAL_SUBSCRIPTION_CODE=your_subscription_code
+ PORTAL_TOKEN_ENDPOINT=https://ycloud.accounts.ondemand.com/oauth2/token
+ PORTAL_CLIENT_ID=your_client_id
+ PORTAL_CLIENT_SECRET=your_client_secret
+ PORTAL_RESOURCE=your_resource_urn
+ PORTAL_TIMEOUT=30000
+ ```
+
Verify setup:
```bash
node <skill-dir>/scripts/execute.js --health-check
+ node <skill-dir>/scripts/portal.js --health-check
```
---
- ## Decision Guide: FlexSearch vs Groovy
+ ## Decision Guide: FlexSearch vs Groovy vs Cloud Portal
- Read [references/decision-guide.md](references/decision-guide.md) for the full matrix.
+ Read [references/decision-guide.md](references/decision-guide.md) for the FlexSearch vs Groovy matrix, and [references/portal-guide.md](references/portal-guide.md) for the full Cloud Portal command reference.
**Quick rule:**
- | Use FlexSearch when… | Use Groovy when… |
- |---|---|
- | Pure data retrieval (SELECT) | Business service calls (ProductService, OrderService…) |
- | Simple WHERE conditions | Multi-step / conditional logic |
- | Counting / listing items | Writes, creates, updates, deletes |
- | Joining SAP CC types | Running ImpEx programmatically |
- | Checking attribute values | Triggering cronjobs / business processes |
- | Fast exploration | Complex calculations or transformations |
+ | Use FlexSearch when… | Use Groovy when… | Use Cloud Portal (`portal.js`) when… |
+ |---|---|---|
+ | Pure data retrieval (SELECT) | Business service calls (ProductService, OrderService…) | Listing/inspecting environments |
+ | Simple WHERE conditions | Multi-step / conditional logic | Creating/tracking builds & deployments |
+ | Counting / listing items | Writes, creates, updates, deletes (app data) | Managing backups, scaling, endpoints, certs |
+ | Joining SAP CC types | Running ImpEx programmatically | Scheduling maintenance windows |
+ | Checking attribute values | Triggering cronjobs / business processes | Reading/writing service properties, managing user roles |
+ | Fast exploration | Complex calculations or transformations | Any CCv2 DevOps / platform operation |
---
## Workflow
- ### Step 1 – Assess the request
+ ### Step 0 – Classify the domain
+ First decide **which client** is relevant:
+ - Application data / business logic → **HAC** (`execute.js`, FlexSearch or Groovy)
+ - CCv2 platform operations (builds, deployments, environments, scaling, backups, certs, roles) → **Cloud Portal** (`portal.js`)
+
+ If ambiguous, ask the user or infer from vocabulary ("deploy", "build", "environment", "scale", "backup", "certificate" → Cloud Portal; "product", "order", "customer", "cronjob", "query" → HAC).
+
+ ### Step 1 – Assess the request (HAC path)
+
Classify the user's intent into one of:
- `flexsearch` – data query, no side effects, can be expressed as a SELECT statement
- `groovy` – business logic, writes, service access, multi-type joins with business rules
If in doubt, prefer FlexSearch first; escalate to Groovy if the query returns insufficient data or requires logic.
### Step 2 – Compose the script or query
**For FlexSearch:** write a valid FlexibleSearch query.
- Always qualify attributes: `{product:pk}`, `{p:code}`, etc.
- Use `JOIN` syntax for related types
- Apply `WHERE` clauses with proper escaping
- Read [references/flexsearch-guide.md](references/flexsearch-guide.md) for syntax and common patterns
**For Groovy:** write a Groovy script.
- Use Spring beans via the `spring` variable: `spring.getBean('productService')`
- Use `catalogVersionService`, `userService`, `orderService`, etc.
- Return a value or use `println` for output
- Set `--commit` only when writing data
- Read [references/groovy-patterns.md](references/groovy-patterns.md) for patterns and Spring bean names
### Step 3 – Execute
```bash
# FlexibleSearch
node <skill-dir>/scripts/execute.js \
--type flexsearch \
--query "SELECT {pk},{code},{name[en]} FROM {Product} WHERE {code} LIKE '%LAPTOP%' ORDER BY {code} ASC" \
--max-count 50
# Groovy (read-only)
node <skill-dir>/scripts/execute.js \
--type groovy \
--script "
def ps = spring.getBean('productService')
def cv = spring.getBean('catalogVersionService').getCatalogVersion('electronicsProductCatalog','Online')
def p = ps.getProductForCode(cv, 'LAPTOP_001')
return p?.name
"
# Groovy (write – commit=true)
node <skill-dir>/scripts/execute.js \
--type groovy \
--commit \
--script "
def product = new de.hybris.platform.core.model.product.ProductModel()
product.code = 'TEST_001'
modelService.save(product)
return 'saved'
"
# From a .groovy file
node <skill-dir>/scripts/execute.js --type groovy --file /tmp/my-script.groovy
# JSON output (for programmatic use)
node <skill-dir>/scripts/execute.js --type flexsearch --query "..." --json
```
### Step 4 – Interpret and present results
**FlexSearch result** (JSON):
```json
{
"success": true,
"resultCount": 42,
"executionTime": 123,
"headers": ["pk","code","name[en]"],
"rows": [["8796093055058","LAPTOP_001","Laptop Pro"]]
}
```
**Groovy result** (JSON):
```json
{
"success": true,
"executionResult": "Laptop Pro",
"outputText": "",
"stacktrace": ""
}
```
- Present tabular data as a Markdown table when `headers` and `rows` are available
- Highlight `success: false` with the `error` or `stacktrace` message
- When `resultCount` is 0, suggest query refinements
### Step 5 – Error handling
| Error | Action |
|---|---|
| `Missing required environment variables` | Ask user to fill `.env` (HAC_URL, HAC_USERNAME, HAC_PASSWORD) |
| `Authentification échouée` | Check credentials; try `--health-check` |
| `HTTP 403` | Check user permissions in HAC |
| FlexSearch syntax error | Fix query; check type names and attribute aliases |
| Groovy `MissingMethodException` | Check Spring bean name in [references/groovy-patterns.md](references/groovy-patterns.md) |
| `ECONNREFUSED` / `ETIMEDOUT` | Check HAC_URL reachability; try HAC_IGNORE_SSL=true for dev |
---
+ ## Cloud Portal path (builds, deployments, environments, ...)
+
+ For DevOps/platform requests, use `scripts/portal.js` instead of `execute.js`. Full command reference,
+ workflows and error handling: [references/portal-guide.md](references/portal-guide.md).
+
+ ```bash
+ # List environments
+ node <skill-dir>/scripts/portal.js environments list
+
+ # Build & deploy
+ node <skill-dir>/scripts/portal.js builds create --branch develop --name release-2.5.0
+ node <skill-dir>/scripts/portal.js builds progress <buildCode>
+ node <skill-dir>/scripts/portal.js deployments create --build-code <buildCode> --environment-code staging \
+ --db-mode UPDATE --strategy ROLLING_UPDATE
+ node <skill-dir>/scripts/portal.js deployments progress <deploymentCode>
+
+ # Backup before a risky deployment
+ node <skill-dir>/scripts/portal.js backups create prod --description "Before release-2.5.0" --type STANDARD
+
+ # Scale a service
+ node <skill-dir>/scripts/portal.js scaling update prod --service storefront --replicas 4 --memory-scale-factor 1.5
+ ```
+
+ Output shape (JSON, same style as `execute.js`):
+ ```json
+ { "success": true, "data": { "...": "..." } }
+ ```
+ ```json
+ { "success": false, "error": "...", "detail": "..." }
+ ```
+
+ Always confirm destructive actions first (deletes, `REJECT` decisions, production deployments) — see the
+ "Notes for the agent" section in [references/portal-guide.md](references/portal-guide.md).
+
+ ---
+
## Reference Files
Load these on-demand when needed:
| File | When to load |
|---|---|
| [references/decision-guide.md](references/decision-guide.md) | Complex cases where you're unsure of FlexSearch vs Groovy |
| [references/flexsearch-guide.md](references/flexsearch-guide.md) | Composing FlexibleSearch queries (syntax, types, joins, caveats) |
| [references/groovy-patterns.md](references/groovy-patterns.md) | Common Groovy patterns, Spring bean names, service examples |
| [references/sap-cc-types.md](references/sap-cc-types.md) | Common SAP CC type names, attributes and catalog structure |
+ | [references/portal-guide.md](references/portal-guide.md) | Cloud Portal command reference: builds, deployments, environments, backups, scaling, endpoints, certificates, activities, properties, roles |