sapcc-skill

SAP Commerce Cloud Skill

Interact with a SAP Commerce Cloud (Hybris/CCv2) instance using `sapcc-hac-client` — currently supporting Groovy scripts and FlexibleSearch queries. 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

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

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

Verify setup:

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

Decision Guide: FlexSearch vs Groovy

Read references/decision-guide.md for the full matrix.

Quick rule:

Workflow

Step 1 – Assess the request

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

Reference Files

Load these on-demand when needed: