Skip to end of metadata
Go to start of metadata

SAP Screen Personas

Executing Personas Scripts asynchronously or triggered by Non-Personas Sources

SAP SCREEN PERSONAS KNOWLEDGE BASE - by Sushant Priyadarshi , Tamas Hoznek , Clemens Gantert , Regina Sheynblat


In SAP Screen Personas 3.0 scripting method GuiUtils.executeScriptAsync() exists in the SAP GUI for HTML and Slipstream Engine clients. This method allows executing a Personas script out of turn and can be triggered by a caller that is not part of the Personas or the client's framework because the method is globally accessible through sap.personas.scripting.executeScriptAsync(). This article describes how to use this powerful method.

Use Cases

  1. Allows external libraries or window timer methods (window.setTimeout()) call a Personas script as callback. The Personas script has access to the full scripting API and after it is finished the screen is updated. See Scripting: Building flavors with Barcode scanning functionality for how this method is used to accomplish barcode scanning via the Cordova library.
  2. Many customers have created elaborate UIs inside of a Personas HTML viewer control, for instance a UI5 table (see ). To stay with the UI5 table example, if a user interacts with the UI5 table, such as selecting a table row, then an event is fired by UI5 and GuiUtils.executeScriptAsync() can be used to pass information such as the selected row key from the html viewer UI to the surrounding main window.
  3. Long running scripts that otherwise block the client for a long time can be broken up in smaller chunks. The asynchronous nature of GuiUtils.executeScriptAsync() allows the main window to get updated with progress information while the script does its job. GuiUtils.executeScriptAsync() can be considered the official replacement of sap.personas.scripting.scriptingEngine.scheduleTask() which is an experimental feature for the SAP GUI for HTML introduced with SP3 (see Experimental Feature: Scheduling scripting tasks to be executed asynchronously).

How it works

The method takes two parameters, the ID of the script that is supposed to be executed and an optional data object that is available in the asynchronously called script as variable "data". This means there is always at least two scripts, the calling script and the asynchronous script.

It is crucial to understand the process flow:

  1. The calling script hits the executeScriptAsync() statement, but the asynchonous script is not executed yet.
  2. The calling script finishes.
  3. If there are onLoad or onAfterRefresh scripts, they are executed.
  4. The screen is rendered (and the cumulative changes made by the calling, onLoad and onAfterRefresh scripts are displayed).
  5. Only after the screen has been completely rendered, the asynchronous script is started.
  6. The asynchronous script finishes.
  7. If there are onLoad or onAfterRefresh scripts, they are executed.
  8. The screen is rendered (and the cumulative changes made by the assynchrouns, onLoad and onAfterRefresh scripts are displayed).

Usage Examples

Simple Example: Delayed Execution

Calling Script
session.findById("<label id>").text = 'started at: '+(new Date()).toString();
function doIt(){
	session.utils.executeScriptAsync( "<async script ID>", {myData: "Hello World!"});
window.setTimeout(doIt, 5000); // wait 5s
Asynchronous Script
session.findById("<label id>").text = "At "+(new Date()).toString()+", data.myData was:"+data.myData;

The label will change to "started at: <date>" and then around 5s later it will change again to "At <date> data.myData was Hellow World!."

Calling from HTML Viewer UI

Calling executeSciptAsyn() from the HTML viewer UI you have to consider three things:

  1. Use the globally accessible method at sap.personas.scripting.executeScriptAsync() because the UI does not have access to the session object and therefore not to the method (note that the doIt() function in the previous example "saved" the session object in its Javascript closure).
  2. HTML viewers live in their own iFrame. So, the access to the methods has to go through the parent window:
  3. As with all cross-window scripting you have to make sure that the main window is relaxed and that the HTML viewer's domain matches the main window.

Calling Scipt (and use the same delayed script from the previous example):

Calling Scipt (use the same asynchronous script from the previous example)
var html = "<html><head>\
function doIt() {\'<async script ID>', {myData: 'Hello World!'});\
<button onClick='doIt()'>Press Me</button>\
session.findById("<html viewer id>").content = html;

Note that we set the html viewer's domain to the same domain as the main window's domain. This works well in SAP GUI for HTML because this client usually relaxes the domains already, but on SE you may have to relax the domain explicitly even for the main window.

Breaking up long running scripts

Unlike sap.personas.scripting.scriptingEngine.scheduleTask() (see Experimental Feature: Scheduling scripting tasks to be executed asynchronously) GuiUtils.executeScriptAsync() lets you only schedule one asynchronous script at a time. Therefore each single task has to "schedule" the next one when it is complete.

Calling Script that defines all tasks and starts the asynchronous script for the first time
var tasks = ["one", "two", "tree"]; 
session.utils.executeScriptAsync("<async script ID>", tasks);
Asynchronous Script that executes the first task and then reschedules itself.
var tasks = data;
var task = tasks.shift(); // get the next task (and remove it from 'tasks')
session.findById("<label id>").text = task;
if (tasks.length>0) { // if tasks left, execute it again
	session.utils.executeScriptAsync("<async script ID>", tasks);

Related Content

Related Search Terms:

executeScriptAsync, Personas, scripting, HTML viewer

Related SAP Notes/KBAs

Scripting: Building flavors with Barcode scanning functionality,, Experimental Feature: Scheduling scripting tasks to be executed asynchronously