gh-secondsky-sap-skills-skills-sap-sac-scripting/references/iframe-embedding-lumira-migration.md

iFrame Embedding and Lumira Designer Migration

Reference documentation for iFrame PostMessage communication and migration guidance from Lumira Designer to SAP Analytics Cloud.

---

Table of Contents

1. iFrame Embedding with PostMessage
2. Differences Between SAP Analytics Cloud and Lumira Designer

---

iFrame Embedding with PostMessage

When your analytic application is embedded in an iFrame, it can communicate bidirectionally with the host web application using JavaScript PostMessage.

Application Events for Embedded Scenarios

SAC analytic applications have two primary application events:

1. onInitialization: Runs once when the application is instantiated by a user
2. onPostMessageReceived: Triggered when the host application sends a PostMessage

onPostMessageReceived Event

This event fires whenever the host application makes a PostMessage call into the embedded analytic application.

Reference: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

Event Parameters

The onPostMessageReceived event provides two input parameters:

Parameter	Type	Description
origin	string	The domain of the host application
message	any	The message content passed via PostMessage

origin Parameter

The origin parameter contains the domain of the host application.

Important Security Notes:

• iFrame contents don't need to be in the same origin as the host app
• Same-origin policies may still be in effect
• Be careful about clickjacking attacks and malicious iFrame hosts
• Always validate the origin parameter to ensure the iFrame host is expected

Security Best Practice:

// onPostMessageReceived event
if (origin !== "[https://trusted-domain.com](https://trusted-domain.com)") {
    console.log("Unauthorized origin: " + origin);
    return;  // Reject messages from unknown origins
}

// Process message from trusted origin
processMessage(message);

message Parameter

The message parameter contains the standard JavaScript PostMessage content passed into SAP Analytics Cloud.

Characteristics:

• Does not follow any specific format
• Could contain almost any data type
• Encoded using the structured clone algorithm
• Some documented restrictions on what can and can't be encoded

Structured Clone Algorithm

The structured clone algorithm has some limitations on what can be cloned:

Supported:

• Primitive types (string, number, boolean)
• Arrays
• Plain objects
• Date objects
• Map, Set, ArrayBuffer, TypedArray

Not Supported:

• Functions
• DOM nodes
• Symbols
• Error objects
• Property descriptors, setters, getters

Example: Receiving PostMessage

// onPostMessageReceived event handler
// Parameters: origin, message

// Security check
if (origin !== "[https://my-portal.company.com](https://my-portal.company.com)") {
    console.log("Rejected message from: " + origin);
    return;
}

// Log the received message
console.log("Received message from: " + origin);
console.log("Message content: " + JSON.stringify(message));

// Process message based on type
if (message.type === "filter") {
    // Apply filter from host application
    var dimension = message.dimension;
    var value = message.value;

    Chart_1.getDataSource().setDimensionFilter(dimension, value);

} else if (message.type === "refresh") {
    // Refresh data
    Chart_1.getDataSource().refreshData();

} else if (message.type === "navigate") {
    // Handle navigation request
    var pageId = message.pageId;
    // Navigate to page...
}

Host Application Example

In the host web application (outside SAP Analytics Cloud):

// Get reference to the SAC iFrame
var sacFrame = document.getElementById("sac-iframe");

// Send filter command to embedded SAC application
sacFrame.contentWindow.postMessage({
    type: "filter",
    dimension: "Region",
    value: "EMEA"
}, "[https://your-tenant.sapanalytics.cloud](https://your-tenant.sapanalytics.cloud)");

// Send refresh command
sacFrame.contentWindow.postMessage({
    type: "refresh"
}, "[https://your-tenant.sapanalytics.cloud](https://your-tenant.sapanalytics.cloud)");

Security Recommendations

1. Always validate origin: Check that messages come from expected domains
2. Use specific target origins: Don't use "*" as target origin
3. Validate message structure: Ensure message format matches expectations
4. Log suspicious activity: Track rejected messages for security monitoring
5. Implement allowlist: Maintain list of trusted origins

// Recommended: Origin allowlist pattern
var trustedOrigins = [
    "[https://portal.company.com",](https://portal.company.com",)
    "[https://intranet.company.com"](https://intranet.company.com")
];

// In onPostMessageReceived
var isTrusted = false;
for (var i = 0; i < trustedOrigins.length; i++) {
    if (origin === trustedOrigins[i]) {
        isTrusted = true;
        break;
    }
}

if (!isTrusted) {
    console.log("Blocked message from untrusted origin: " + origin);
    return;
}

---

Differences Between SAP Analytics Cloud and Lumira Designer

Design Studio / Lumira Designer and SAP Analytics Cloud, analytics designer have broadly similar scripting environments. Both are JavaScript-based and perform similar missions. Analytics designer's scripting framework was informed by experience with Design Studio.

However, there are important differences to understand when migrating.

Execution Environment

Aspect	Lumira Designer	Analytics Designer (SAC)
Script Execution	Server-side	Browser-side (client)
Proximity	Close to the data	Close to the user
JavaScript Engine	Server JavaScript engine	Browser native JavaScript

Key Implication: This "close-to-data vs close-to-user" philosophical difference affects how you design scripts.

Copy-and-Paste Compatibility

Analytics Designer is NOT copy-and-paste compatible with Lumira Designer.

Scripts written for Lumira Designer will likely need modification to work in Analytics Designer. This is partially a consequence of the architectural differences.

Data Source Access

Feature	Lumira Designer	Analytics Designer
Standalone Data Sources	Available as global variables	Hidden within data-bound widgets
Access Method	Direct access by name	Must use getDataSource() method

Lumira Designer:

// Direct access to data source
DS_1.setFilter("Location", "USA");

Analytics Designer:

// Access through widget
var ds = Chart_1.getDataSource();
ds.setDimensionFilter("Location", "USA");

Note: When standalone data sources become available in SAC, you'll be able to access them as global variables, similar to Lumira.

Type System Differences

Feature	Lumira Designer	Analytics Designer
Type Conversion	More lenient	Strict (no automatic conversion)
Equality Operator	== works across types	== only valid with same types
Recommended Operator	== or ===	=== (strict equality)

Lumira Designer (allowed):

var aNumber = 1;
if (aNumber == "1") {  // Works - auto type coercion
    // Executes
}

Analytics Designer (must use explicit conversion or strict equality):

var aNumber = 1;

// Option 1: Strict equality with correct type
if (aNumber === 1) {  // Recommended
    // Executes
}

// Option 2: Explicit conversion
if (aNumber.toString() === "1") {
    // Executes
}

// WRONG: Different types with ==
// if (aNumber == "1") { }  // Error in SAC!

API Method Names

Some API methods have different names between platforms:

Operation	Lumira Designer	Analytics Designer
Set filter	setFilter()	setDimensionFilter()
Remove filter	removeFilter()	removeDimensionFilter()
Get filter	getFilter()	getDimensionFilters()

Summary of Key Migration Steps

When migrating from Lumira Designer to SAP Analytics Cloud:

1. Update data source access: Change direct data source references to widget.getDataSource()

2. Fix type conversions: Add explicit .toString() or other conversion methods

3. Update equality operators: Change == to === for comparisons, especially with different types

4. Update API method names: Replace Lumira-specific methods with SAC equivalents

5. Review script location: Consider that scripts now run in browser, not on server

6. Test thoroughly: Behavior may differ due to execution environment changes

Example Migration

Original Lumira Designer Script:

// Lumira Designer
DS_1.setFilter("Year", selectedYear);
var members = DS_1.getMembers("Location");
var count = members.length;
console.log("Count: " + count);  // Auto-converts count to string

Migrated Analytics Designer Script:

// Analytics Designer (SAC)
var ds = Chart_1.getDataSource();
ds.setDimensionFilter("Year", selectedYear);
var members = ds.getMembers("Location");
var count = members.length;
console.log("Count: " + count.toString());  // Explicit conversion required

---

Additional Resources

• SAP Analytics Designer Documentation: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD
• Lumira Designer Migration Guide: Check SAP Help Portal for official migration documentation
• PostMessage API: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

---

Source: SAP Analytics Designer Development Guide - Chapter 4: Scripting in Analytics Designer (Sections 4.2.3.1 and 4.10) Last Updated: 2025-11-23