// |
| name | sap-sac-custom-widget |
| description | SAP Analytics Cloud (SAC) Custom Widget development skill. Use when building custom visualizations, interactive components, extending SAC with Web Components, or creating Widget Add-Ons to customize built-in widgets. Covers JSON metadata configuration, JavaScript Web Components, lifecycle functions, data binding with feeds, styling panels, builder panels, property/event/method definitions, custom types, script API data types, third-party library integration, hosting options, security, performance optimization, and debugging. Includes Widget Add-On feature (QRC Q4 2023+) for extending built-in widgets without creating from scratch. Provides templates for basic widgets, data-bound charts, styling panels, and KPI cards. Supports Optimized Story Experience and Analytics Designer. Prevents common errors: missing lifecycle functions, incorrect JSON schema, integrity warnings, CORS failures, property type mismatches, data binding issues, and performance anti-patterns. Keywords: sap analytics cloud, sac custom widget, custom widget development, web component sac, json metadata widget, widget lifecycle functions, onCustomWidgetBeforeUpdate, onCustomWidgetAfterUpdate, onCustomWidgetResize, onCustomWidgetDestroy, sac data binding, widget data binding, dataBindings feeds, getDataBinding, getResultSet, styling panel widget, builder panel widget, widget properties events methods, propertiesChanged event, dispatchEvent custom widget, sac echarts integration, sac d3js integration, third party library sac, widget hosting sac, sac hosted widget, integrity hash widget, sha256 integrity, widget security cors, sac widget debugging, custom visualization sac, sac analytics designer widget, optimized story experience widget, sac widget api, widget add-on, sac script api widget, custom types enumeration, MemberInfo ResultMemberInfo Selection, widget installation admin, sac performance optimization, shadow dom web component, sac tooltip customization, plot area addon |
| license | GPL-3.0 |
| metadata | {"version":"1.2.0","last_verified":"2025-11-26T00:00:00.000Z","sac_version":"2025.21","token_savings":"~75%","errors_prevented":"25+","official_docs":["https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/0ac8c6754ff84605a4372468d002f2bf/75311f67527c41638ceb89af9cd8af3e.html","https://help.sap.com/doc/c813a28922b54e50bd2a307b099787dc/release/en-US/CustomWidgetDevGuide_en.pdf"],"samples_repo":"https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets"} |
| allowed-tools | ["Read","Write","Edit","Bash","WebFetch"] |
This skill enables development of custom widgets for SAP Analytics Cloud (SAC). Custom widgets are Web Components that extend SAC stories and applications with custom visualizations, interactive elements, and specialized functionality.
Use this skill when:
Requirements:
A custom widget requires two files:
1. widget.json (Metadata)
{
"id": "com.company.mywidget",
"version": "1.0.0",
"name": "My Custom Widget",
"description": "A simple custom widget",
"vendor": "Company Name",
"license": "MIT",
"icon": "",
"webcomponents": [
{
"kind": "main",
"tag": "my-custom-widget",
"url": "https://your-host.com/widget.js",
"integrity": "",
"ignoreIntegrity": true
}
],
"properties": {
"title": {
"type": "string",
"default": "My Widget"
}
},
"methods": {},
"events": {}
}
2. widget.js (Web Component)
(function() {
const template = document.createElement("template");
template.innerHTML = `
<style>
:host {
display: block;
width: 100%;
height: 100%;
}
.container {
padding: 16px;
font-family: Arial, sans-serif;
}
</style>
<div class="container">
<h3 id="title">My Widget</h3>
<div id="content"></div>
</div>
`;
class MyCustomWidget extends HTMLElement {
constructor() {
super();
this._shadowRoot = this.attachShadow({ mode: "open" });
this._shadowRoot.appendChild(template.content.cloneNode(true));
this._props = {};
}
connectedCallback() {
// Called when element is added to DOM
}
onCustomWidgetBeforeUpdate(changedProperties) {
// Called BEFORE properties are updated
this._props = { ...this._props, ...changedProperties };
}
onCustomWidgetAfterUpdate(changedProperties) {
// Called AFTER properties are updated - render here
if (changedProperties.title !== undefined) {
this._shadowRoot.getElementById("title").textContent = changedProperties.title;
}
}
onCustomWidgetResize() {
// Called when widget is resized
}
onCustomWidgetDestroy() {
// Cleanup when widget is removed
}
// Property getter/setter (required for SAC framework)
get title() {
return this._props.title;
}
set title(value) {
this._props.title = value;
this.dispatchEvent(new CustomEvent("propertiesChanged", {
detail: { properties: { title: value } }
}));
}
}
customElements.define("my-custom-widget", MyCustomWidget);
})();
โ ๏ธ Production Note: The ignoreIntegrity: true setting above is development only. For production deployments, generate a SHA256 integrity hash and set ignoreIntegrity: false.
SAP provides 15+ ready-to-use custom widget samples:
Repository: SAP-samples/SAC_Custom_Widgets
| Category | Widgets |
|---|---|
| Charts | Funnel, Pareto, Sankey, Sunburst, Tree, Line, UI5 Gantt |
| KPI/Gauge | KPI Ring, Gauge Grade, Half Donut, Nested Pie, Custom Pie |
| Utilities | File Upload, Word Cloud, Bar Gradient, Widget Add-on Sample |
Requirements: Optimized View Mode (OVM) enabled, data binding support
Note: Check third-party library licenses before production use.
Essential functions called by SAC framework:
onCustomWidgetBeforeUpdate(changedProperties) - Pre-update hookonCustomWidgetAfterUpdate(changedProperties) - Post-update (render here)onCustomWidgetResize() - Handle resize eventsonCustomWidgetDestroy() - Cleanup resourcesConfigure in widget.json to receive SAC model data:
{
"dataBindings": {
"myDataBinding": {
"feeds": [
{
"id": "dimensions",
"description": "Dimensions",
"type": "dimension"
},
{
"id": "measures",
"description": "Measures",
"type": "mainStructureMember"
}
]
}
}
}
Access data in JavaScript:
// Get data binding
const dataBinding = this.dataBindings.getDataBinding("myDataBinding");
// Access result set
const data = this.myDataBinding.data;
const metadata = this.myDataBinding.metadata;
// Iterate over rows
this.myDataBinding.data.forEach(row => {
const dimensionValue = row.dimensions_0.label;
const measureValue = row.measures_0.raw;
});
1. SAC-Hosted (Recommended, QRC Q2 2023+)
"/path/to/widget.js""integrity": "" and "ignoreIntegrity": true2. GitHub Pages
https://username.github.io/repo/widget.js3. External Web Server
Access-Control-Allow-Origin: *For production, generate SHA256 hash:
# Generate hash
openssl dgst -sha256 -binary widget.js | openssl base64 -A
# Update JSON
"integrity": "sha256-abc123...",
"ignoreIntegrity": false
| Error | Cause | Solution |
|---|---|---|
| "The system couldn't load the custom widget" | Incorrect URL or hosting issue | Verify URL is accessible, check CORS |
| "Integrity check failed" | Hash mismatch | Regenerate hash after JS changes |
| Widget not appearing | Missing connectedCallback render | Call render in onCustomWidgetAfterUpdate |
| Properties not updating | Missing propertiesChanged dispatch | Use dispatchEvent with propertiesChanged |
| Data not displaying | Data binding misconfigured | Verify feeds in JSON match usage |
onCustomWidgetAfterUpdate(changedProperties) {
console.log("Widget updated:", changedProperties);
console.log("Current props:", this._props);
console.log("Data binding:", this.myDataBinding?.data);
this._render();
}
Widget Add-Ons extend built-in SAC widgets without building from scratch.
Use Cases:
Supported Charts: Bar/Column, Stacked Bar/Column, Line, Stacked Area, Numeric Point
Key Differences:
main and builder components (no styling)tooltip, plotArea, numericPoint)See references/widget-addon-guide.md for complete implementation.
For detailed templates and examples, see:
references/json-schema-reference.md - Complete JSON schema documentationreferences/widget-templates.md - Ready-to-use widget templates (6 templates)references/echarts-integration.md - ECharts library integration guidereferences/widget-addon-guide.md - Widget Add-On development (QRC Q4 2023+)references/best-practices-guide.md - Performance, security, and development guidelinesreferences/advanced-topics.md - Custom types, script API types, installationreferences/integration-and-migration.md - Script integration, content transportreferences/script-api-reference.md - DataSource, Selection, MemberInfo APIsPrimary References (for skill updates):
Sample Widgets:
v1.2.0 (2025-11-26)
v1.1.0 (2025-11-22)
v1.0.0 (2025-11-22)
Last Verified: 2025-11-26 | SAC Version: 2025.21 | Skill Version: 1.2.0