sapcc-hac-skill

SAP Commerce Cloud HAC Skill

Interact with a SAP Commerce Cloud (Hybris/CCv2) instance through the Hybris Administration Console (HAC) using `sapcc-hac-client`.

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

Run once after installation:

cd <skill-dir> && npm install

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/setup.js
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: