sap-sac-scripting

# SAP Analytics Cloud Scripting

## Related Skills

- **dependency-upgrade**: Use when securing dependency and SDK/tooling upgrades used in story automation pipelines that integrate with external script tooling

Comprehensive skill for scripting in SAP Analytics Cloud (SAC) Analytics Designer and Optimized Story Experience.

## Getting Started

When the user invokes this skill with no specific task (e.g. "help with SAC scripting", "use SAC scripting skill", or no follow-up question), respond with this structured orientation:

> Welcome! I can help you with SAP Analytics Cloud scripting.
>
> First, which environment are you working in?
> 1. **Analytics Designer** — application-based scripting, full API
> 2. **Optimized Story Experience** — story-based scripting, OSE API (v2025.20)
>
> Then, what do you need help with?
> - Write a new script (filter, planning, navigation, export...)
> - Debug an existing script
> - Optimize performance
> - Find the right API method
> - Planning operations (version management, data locking...)

## Plugin Components

This plugin provides specialized tools for SAC development:

**Agents** (use via Task tool):
- `sac-script-debugger` - Debug script errors, trace issues
- `sac-performance-optimizer` - Analyze and fix performance bottlenecks
- `sac-planning-assistant` - Guide planning operations and version management
- `sac-api-helper` - Find correct APIs and provide code examples

**Commands** (use via /command):
- `/sac-script-template` - Generate script templates (filter, planning, export, etc.)
- `/sac-debug` - Interactive debugging guidance
- `/sac-optimize` - Performance analysis and recommendations
- `/sac-planning` - Planning operation templates

**Hooks**:
- Automatic validation on SAC script writes for common issues

## MCP Setup

This plugin ships with a `.mcp.json` that connects to the community `sap_analytics_cloud_mcp`
server, exposing 90 SAC REST API tools across 11 service areas (Content, Data Export, Data Import,
Multi Actions, Calendar, Content Transport, User Management, Monitoring, Schedule & Publication,
Translation, Smart Query).

**Before using MCP tools**, check if the server is already installed:
- Look for `.claude/sac-mcp.local.md` in the project
- Or check if `SAC_MCP_PATH` is set in the environment

If not installed, ask the user once: **"Would you like help setting up the SAC MCP server?"**

**If yes**, guide them through:

1. Clone and build:
   ```bash
   git clone https://github.com/secondsky/sap_analytics_cloud_mcp
   cd sap_analytics_cloud_mcp && npm install && npm run build
   ```

2. Configure environment variables:
   - `SAC_MCP_PATH` — absolute path to the cloned repo (e.g. `/home/user/sap_analytics_cloud_mcp`)
   - `SAC_BASE_URL` — SAC tenant root URL (e.g. `https://mytenant.eu10.hanacloudservices.cloud.sap`)
   - `SAC_TOKEN_URL` — OAuth token endpoint
   - `SAC_CLIENT_ID` / `SAC_CLIENT_SECRET` — from SAC OAuth client configuration

3. After successful install, write `.claude/sac-mcp.local.md` (gitignored) with:
   ```markdown
   # SAC MCP Installation Record
   - Installed: [date]
   - Path: [absolute path to build/index.js]
   - Env vars configured: SAC_MCP_PATH, SAC_BASE_URL, SAC_TOKEN_URL, SAC_CLIENT_ID, SAC_CLIENT_SECRET
   ```

This prevents re-prompting in future sessions.

## What's New in Q2 2026 (2026.8)

Key scripting enhancements in the latest SAC release:
- **Enhanced `onAfterExecute` Event** - Upload events now include message, statistics, rejected records, target version, and filename
- **Data Export API Job Monitoring** - New job monitor tab for delta extraction and calculation jobs
- **Data Import Service API** - Import master data to public dimensions in SAP Datasphere; import external fact data to private versions
- **Multi-Action API Step** - HTTP 204 response now allowed; enhanced header field restrictions
- **Export to S/4HANA Deprecated** - Use write-back integration scenario instead
- **Asymmetric Reporting** - Differing time ranges, hierarchies, and measures per row/column
- **Composite Versioning** - Manage multiple composite versions during story design

See `references/whats-new-qrc2-2026.md` for complete details.

## Environment Detection

Before writing or analyzing any script, identify which SAC environment the user is working in.

**Detection signals:**

| Signal | Environment |
|--------|-------------|
| Mentions `.story`, "Optimized Story", OSE, `Story.`, `Application.getActivePage()` | **OSE** |
| Mentions Analytics Designer, `AnalyticApplication`, `Designer`, `.application` | **Analytics Designer** |
| Says "SAC script" / "my script" without further context | **Unclear** |

**When environment is unclear**, ask ONE concise question before proceeding:

> "Are you scripting in **Analytics Designer** or **Optimized Story Experience**? This determines which API reference I use."

Do not ask again after the user answers.

**After confirmation**, use the correct references:
- **OSE** → `references/ose-api-*.md` (8 files, Q2 2026, v2025.20)
- **Analytics Designer** → `references/api-*.md` (existing files)

## Quick Start

### Script Editor Access
- **Analytics Designer**: Edit mode → Select widget → Scripts tab
- **Optimized Story Experience**: Advanced Mode → Select widget → Add script

### Basic Script Structure
```javascript
// Event handler example (onSelect on Chart_1)
var selections = Chart_1.getSelections();
if (selections.length > 0) {
    var selectedValue = selections[0]["Location"];
    Table_1.getDataSource().setDimensionFilter("Location", selectedValue);
}
```

## Core APIs

### DataSource API
Access via `Widget.getDataSource()`. Key methods:
- `getMembers(dim, {accessMode: MemberAccessMode.BookedValues})` - Get dimension members efficiently
- `getResultSet()` - Cached data access (preferred over getData())
- `setDimensionFilter(dim, value)` - Apply filters
- `setRefreshPaused(true/false)` - Batch multiple operations

### Planning API
Access via `Table.getPlanning()`. Key operatio