Sapcc Skill

SAP Commerce Cloud Skill

Interact with a SAP Commerce Cloud (Hybris/CCv2) instance using two complementary companion clients:

• sapcc-hac-client (scripts/execute.js) — Groovy scripts and FlexibleSearch queries against the HAC (application data & business logic)
• 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 format.

Setup

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):

cp <skill-dir>/.env.example .env
# Then fill in your values

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:

node <skill-dir>/scripts/execute.js --health-check
node <skill-dir>/scripts/portal.js --health-check

Decision Guide: FlexSearch vs Groovy vs Cloud Portal

Read references/decision-guide.md for the FlexSearch vs Groovy matrix, and references/portal-guide.md for the full Cloud Portal command reference.

Quick rule:

Workflow

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 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 for patterns and Spring bean names

Step 3 – Execute

# 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):

{
  "success": true,
  "resultCount": 42,
  "executionTime": 123,
  "headers": ["pk","code","name[en]"],
  "rows": [["8796093055058","LAPTOP_001","Laptop Pro"]]
}

Groovy result (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

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.

# 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):

{ "success": true, "data": { "...": "..." } }

{ "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.

Reference Files

Load these on-demand when needed: