The Leader in eBusiness

I E B E L

Y S T E M S

N C

Technical Note: Browser Scripting Techniques in Siebel 7 and Siebel 8

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Forward
Background
Introduced in Siebel eBusiness Applications version 7, browser scripting provides a flexible scripting environment for implementing browser side procedural logic. Common uses of browser script include: Data manipulation and validation on the selected record Client side integration User Interaction and prompts The purpose of this technical note is to discuss some fundamental topics, such as Browser Script Generation and Document Object Model support for High and Standard Interactivity Applications, as well as advanced topics such as: Accessing Force Active fields from Browser Script Using the RaiseError, RaiseErrorText, and LookupMessage functions in script Creating Custom Modal Dialogs in Siebel 7 and onwards Scripting in a Multilingual Environment Dynamic Read-Only Controls

For additional information regarding browser scripting, please refer to the Siebel Bookshelf 8.0 > Object Interfaces Reference > Browser Scripting.

2/15/2002

Page 2

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Contents
THE LEADER IN EBUSINESS....................................................................................... 1 FORWARD........................................................................................................................ 2 BACKGROUND...................................................................................................................... 2 CONTENTS........................................................................................................................3 JAVASCRIPT FILES THAT COMPRISE THE CLIENT FRAMEWORK.............. 5 DO NOT MODIFY ANY FILES THAT CONSTITUTE THE SIEBEL FRAMEWORK.................................... 5 SUPPORTED DOCUMENT OBJECT MODEL (DOM) EVENTS............................. 5 BROWSER SCRIPT GENERATION IN SIEBEL 7.X AND 8.X.................................6 ACCESSING FORCE ACTIVE FIELDS FROM BROWSER SCRIPT.....................7 DESCRIPTION....................................................................................................................... 7 RECOMMENDATION............................................................................................................... 7 USING THE RAISEERROR, RAISEERRORTEXT, AND LOOKUPMESSAGE FUNCTIONS IN SERVER SCRIPT AND BROWSER SCRIPT...............................11 DESCRIPTION..................................................................................................................... 11 RECOMMENDATION............................................................................................................. 11 RaiseError................................................................................................................. 12 RaiseErrorText.......................................................................................................... 12 Note on RaiseError and RaiseErrorText...................................................................13 LookupMessage......................................................................................................... 13 EXAMPLES.........................................................................................................................14 Message Category Example...................................................................................... 14 Creating a Message in Siebel Tools.......................................................................... 16 RaiseError Server Script Example............................................................................ 17 RaiseErrorText Server Script Example..................................................................... 18 LookupMessage Server Script Example.................................................................... 19 LookupMessage Browser Script Example................................................................. 19 SCRIPTING IN A MULTILINGUAL ENVIRONMENT...........................................23 DESCRIPTION..................................................................................................................... 23 Messaging Issues....................................................................................................... 23 Internal Coding Issues...............................................................................................23 MESSAGING BACKGROUND.................................................................................................. 23 SERVER-SIDE ERROR MESSAGES.......................................................................................... 24 RaiseError Method.................................................................................................... 24 Code Sample.............................................................................................................. 24 BROWSER-SIDE ERROR MESSAGES....................................................................................... 25 2/15/2002 Page 3 .

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

LookupMessage Method............................................................................................ 25 Code Sample.............................................................................................................. 25 INTERNAL CODING BACKGROUND......................................................................................... 26 DEFAULTING OR SETTING FIELD VALUES...............................................................................27 SETTING SEARCH SPECIFICATIONS......................................................................................... 28 CONDITIONAL STATEMENTS..................................................................................................28 CONCLUSION......................................................................................................................29 HOW TO INVOKE A BUSINESS SERVICE ON THE SERVER FROM A BROWSER SCRIPT....................................................................................................... 30 DESCRIPTION..................................................................................................................... 30 EXAMPLES.........................................................................................................................31 BEST PRACTICES................................................................................................................ 33 CREATING CUSTOM MODAL DIALOG BOXES IN BROWSER SCRIPT.........34 CREATE AN HTML PAGE FOR THE MODAL DIALOG BOX........................................................34 1. Create a Custom Web Page like the following:.....................................................34 1. Create a custom web page like the following (Continued):.................................. 35 1. Create a custom web page like the following (Continued):.................................. 36 2. Place the custom web page in the sea7(8)X\\PUBLIC\ENU folder...................36 3. Create a browser-side business service to encapsulate calls for the modal dialog. ................................................................................................................................... 36 DYNAMIC READ-ONLY CONTROLS....................................................................... 37 DESCRIPTION..................................................................................................................... 37 HIGH INTERACTIVITY.......................................................................................................... 37 STANDARD INTERACTIVITY...................................................................................................37

2/15/2002

Page 4

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

JavaScript Files that Comprise the Client Framework

Do not Modify any Files that Constitute the Siebel Framework
Should customers need to implement functionality in the browser, this should be done via Browser Script, authored in Siebel Tools. Modification of files that constitute the Siebel eBusiness Applications framework run the risk of complicating the upgrade process may have a negative impact on the UI framework, and will not be supported. Files that constitute this framework are located in the following directories and consist of the following files:

Siebel Server:
siebsrvr/WEBMASTER/<build number>/SCRIPTS SWEApp/public/enu/<build number>/SCRIPTS client\PUBLIC\enu\<build number>\SCRIPTS

Mobile Web Client:

There are more files in 7.5.3 than the ones listed for 7.0.3. Im not sure if we need to list them specifically or if we simply say that manually modifying these files is not supported whether that is good enough. If we do list the files then were setting ourselves up to have multiple lists for each version. Also, we should have whatever approach we use validated by PM.

Supported Document Object Model (DOM) Events

Either way is ok with me. I think it makes sense to include the information all in one place (this doc) but a xref is better from a maintenance standpoint. The supported DOM events are documented in the bookshelf > Siebel Object Interfaces Reference > Browser Scripting > Supported DOM Events for High Interactivity Mode. And in the bookshelf > Siebel Object Interfaces Reference > Browser Scripting > Supported DOM Events for Standard Interactivity Mode.

2/15/2002

Page 5

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Browser Script Generation in Siebel 7.X and 8.X

Either the information should be here or in the Alert but not both. If the Alert is the point of reference for all docs that discuss how to generate browser script then I would suggest that we update the alert for 7.0.x and 7.5.3 and change this doc to xref the alert for details on how to generate browser script. The Metalink3 document - Browser Script Generation in Siebel 7.x and 8.x (Doc ID 476506.1) describes the necessary steps to generate browser script and deploying them to the web server.

2/15/2002

Page 6

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Accessing Force Active Fields from Browser Script

Description
The Smart Web Architecture in Siebel eBusiness Applications version 7.x and 8.x, which is the basis for the High Interactivity Client, is fundamentally different from clients in previous versions of Siebel eBusiness Applications. As a result, the behavior of fields with their Force Active property set to TRUE may not be intuitive for those who have only recently been introduced to version 7.x/8.x. The purpose of this section is to explain how to interact with such fields in version 7.x/8.x from Browser Script. In version 7.x/8.x, the only fields that are available to browser script are: Id Fields whose values appear in the UI

Note that the only system field that is always available is the Id field, and that other system fields (Created By, Updated, etc.) are not available unless they are displayed. To give some background, the High Interactivity Client is based on the notion of two types of objects: C++ objects that are maintained within the Application Object Manager (referred to as "server objects" here), and JavaScript proxy objects that are maintained within the Interaction Manager within the client browsers JavaScript interpreter (referred to as "browser objects" here). Most Siebel eBusiness Applications objects, such as business components, business services, applets, property sets, exist in this manner. The browser objects are lightweight versions of their server objects; they contain only a subset of the functionality of the server objects, including the available fields. Because of this distinction between server and browser objects, setting the Force Active property to TRUE does not make a given fields value available to browser script. It guarantees that the value will be available to server script; in other words, it will be present on the server object but not the browser object. This minimizes the amount of data maintained on the browser to improve overall performance. When a field is forced to be active, its corresponding column is queried each time an ExecuteQuery() is performed on its parent business component. Its value is maintained on the server instance of the business component and is only on the browser if it appears in the UI. If it does not make sense for a fields value to be displayed in the UI, but browser script needs to get the fields value, a business service may be used to retrieve the value from the server instance of the object and return it to the calling browser script.

Recommendation
Obtaining a field value from the server instance can be done with a simple, generically written business service. Following are the steps to create a simple example.

2/15/2002

Page 7

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

First, create a business service named "Sample", and add the following new function in the server script:
function ServerGetFieldValue ( psIn, psOut ) { var sBCName = psIn.GetProperty ( "BC Name" ); var sFieldName = psIn.GetProperty ( "Field Name" ); var sValue = ""; var boActive; var bcActive; try { if ( sBCName == "" || sBCName == null || sFieldName == "" || sFieldName == null ) { psOut.SetProperty ( "Value", "" ); return; } boActive = TheApplication ().ActiveBusObject (); bcActive = boActive.GetBusComp ( sBCName ); if ( bcActive == null ) { psOut.SetProperty ( "Value", "" ); } sValue = bcActive.GetFieldValue ( sFieldName ); psOut.SetProperty ( "Value", sValue ); } catch ( e ) { psOut.SetProperty ( "Value", "ERROR: " + e.message ); } finally { bcActive = null; boActive = null; }

Be sure to add a handler to the new business services PreInvokeMethod event:

function Service_PreInvokeMethod (MethodName, Inputs, Outputs) { switch ( MethodName ) { case "ServerGetFieldValue": ServerGetFieldValue ( Inputs, Outputs ); return ( CancelOperation ); break; } return (ContinueOperation); }

2/15/2002

Page 8

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

A good place to test this is from the Account List Applet. This applet is based on the Account business component, which contains the Alias field. It is not active by default and it is not present in the applet by default, so set its Force Active property to TRUE. Add a button to the Account List Applet; for the purposes of this example, set the buttons Method Invoked property to MyMethod. On the applets PreInvokeMethod event, add the following browser script:
function Applet_PreInvokeMethod (name, inputPropSet) { switch ( name ) { case "MyMethod": try{ var bsUtil = TheApplication ().GetService( "Sample" ); var psIn = TheApplication ().NewPropertySet (); var psOut; var sValue = ""; // Display the field val available to browser script; it will show nothing alert ( this.BusComp ().GetFieldValue ( "Alias" ) ); psIn.SetProperty ( "BC Name", "Account" ); psIn.SetProperty ( "Field Name", "Alias" ); psOut = bsUtil.InvokeMethod ( "ServerGetFieldValue", psIn ); sValue = psOut.GetProperty( "Value" ); alert ( "Value returned = " + sValue ); return ("CancelOperation"); break; } catch(e){ alert(An error has occurred in the Applet_PreInvokeMethod of the + this.Name() + method. + e.message); } finally{ bsUtil = null; psIn = null; psOut = null; } } return ("ContinueOperation"); }

Now compile the relevant objects and test. Be sure to test for an account record that has a valid value in the Alias field, since many in the sample database do not. The first GetFieldValue() call will return an empty string because the field is not present in the UI. 2/15/2002 Page 9 .

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

The ServerGetFieldValue() function works because setting the Alias fields Force Active property to TRUE forced the server version of the business component to retrieve the value for the Alias field, stored in the ALIAS_NAME column every time the business component is queried. The following line from the server script obtains a reference to the business object that is currently active in the user interface.
boActive = TheApplication ().ActiveBusObject ();

That provides the ability to reference any business component that is part of that business object; in this case, it provides a reference to the current instance of the Account business component, which was passed as a parameter to the service.
bcActive = boActive.GetBusComp ( sBCName );

Once that is done, a check should ensure that a reference was actually returned. If it was, then a GetFieldValue() call can be executed for the field that was passed as an argument, and the result placed in the output property set.
if ( bcActive == null ) { psOut.SetProperty ( "Value", "" ); } sValue = bcActive.GetFieldValue ( sFieldName ); psOut.SetProperty ( "Value", sValue );

The value can then be retrieved from the return property set in browser script by looking at the Value property:
sValue = psOut.GetProperty( "Value" );

An extension of this idea would be to have the ServerGetFieldValue() function take a variable number of field names whose Force Active property is set to TRUE and return all their values in the return property set. Aditionally, the document How Can You Add Hidden Fields to a List Applet for Browser Script Access? (Doc ID 477229.1) demonstrates a technique of adding hidden fields to the applet for browser script access.

2/15/2002

Page 10

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Using the RaiseError, RaiseErrorText, and LookupMessage Functions in Server Script and Browser Script
Description
In Siebel eBusiness Applications version 7.x/8.x, there are two basic types of scripts customers can write to add procedural logic to an application configuration: server scripts and browser scripts. Server script executes within the Object Manager. This type of script existed in previous versions of Siebel eBusiness Applications and continues to be supported in version 7.x/8.x. Server scripts are written in Siebel VB orSiebel eScript. Some examples of server script objects are BusComp Server Scripts, Business Service Server Scripts, Application Server Scripts, and Applet Server Scripts. These scripts allow developers to script the behavior of business components. business services, applications, and applets by writing event handlers for the various events exposed by the scripting model. Browser Script executes in, and is interpreted by, the browser. Browser Scripts are written in JavaScript and interact with the Document Object Model (DOM), as well as with the Siebel Object Model available in the browser through the Browser Interaction Manager. A developer can script the behavior of Siebel application events, as well as the browser events that are exposed through the DOM. Browser Script may only be used with High Interactivity applications, except when scripting Control events supported by the Browser Document Object Model. In migrating Siebel eBusiness Applications version 6.x code to version 7.x/8.x, server business component and application scripts that contain references to UI methods need to be modified. Server script executes within an interpreter that resides on the Siebel Server, so no direct UI interaction is possible. In particular, calls to MsgBox need to be replaced by calls to new methods. There are three new methods in version 7.x/8.x which allow developers to raise a notification on the browser from the server: RaiseError, RaiseErrorText, and LookupMessage. These methods can be used in certain cases for substituting functionality that was previously available through the MsgBox method.

Recommendation
In order to provide an alert notification from server script, the RaiseError, RaiseErrorText, and LookupMessage methods were introduced. These methods allow a language neutral message to be displayed as an alert in the web client. Note that these methods are only available in server script; they are not available in browser script.

2/15/2002

Page 11

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

An important point to remember when using RaiseError and RaiseErrorText in Server Script is that that any lines of code that follow the calls to RaiseError or RaiseErrorText methods will not be executed. For more information on these methods, refer to Siebel Bookshelf > Siebel Object Interfaces Reference > Interfaces Reference > Application Methods.

RaiseError
The RaiseError method, which is executed on the server, raises a scripting error message to the browser based on the specified key. This key is used to look up the message text for the current application language from the Message Category "User-Defined Errors". One or more parameter placeholders can be specified in the message text, which are substituted with the corresponding ordered parameters passed into the function. The syntax for RaiseError is as follows: TheApplication.RaiseError((<key>, [param1], [param2]... [paramN])) Where Parameter Description key The error text is based on the specified key, looked up for the current language from the Message Category "User-Defined Errors". In Siebel Tools, the key appears as the Message Name property of the Message object. param1, Optional parameters used to format the error message if it contains param2, ..., any substitution parameters (%1, %2, etc.) paramN return RaiseError does not return a value. value

RaiseErrorText
The RaiseErrorText method, which is executed on the server, raises a scripting error message to the browser using text that is passed as a value into the function. One or more parameter placeholders can be specified in the value, which are substituted with the corresponding ordered parameters passed into the function. The syntax for RaiseErrorText is as follows: TheApplication.RaiseErrorText((value, [param1], [param2]... [paramN])) Where Parameter value param1, param2, ..., paramN return value Description The error text is the specified literal string. Optional parameters used to format the error message if it contains any substitution parameters (%1, %2, etc.) RaiseErrorText does not return a value.

2/15/2002

Page 12

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Note on RaiseError and RaiseErrorText

When invoked, the RaiseError and RaiseErrorText methods will cause execution of the script to terminate, and a notification will be sent to the browser. Internally, the RaiseError and RaiseErrorText methods raise a server script exception. Therefore, if error handling has already been implemented in scripts, please note that this error handling may suppress RaiseError or RaiseErrorText functionality. For example, if the script includes the statement "On Error Goto..., the RaiseError and RaiseErrorText methods will result in the script transferring execution to the error handler. On Error Resume Next will completely suppress the RaiseError and RaiseErrorText methods. In eScript, the RaiseError and RaiseErrorText methods will result in a scripting exception being raised, transferring control to the catch statement. In order for the error message to be displayed, the error must be thrown using the throw statement. eScript Example of Error Handling with RaiseErrorText
function BusComp_PreDeleteRecord () { try{ var status = this.GetFieldValue("Account Status"); if (status == "Gold") { TheApplication().RaiseErrorText("Unable to delete Account");

} else { return (ContinueOperation); } } catch (e) { BcAccount = null throw e; } finally { // Do cleanup here }

LookupMessage
The LookupMessage method returns the translated string for the specified key, in the current application language, from the specified Message Category. The optional parameters are used to format the string if it contains any substitution parameters. Note than unlike the RaiseError method, the LookupMessage method is not restricted to the User-Defined Errors Message Category, and it does not provide a mechanism to display the message that is retrieved. The syntax for LookupMessage is as follows: TheApplication.LookupMessage((category, key, [param1], [param2]... [paramN])) Where

2/15/2002

Page 13

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Parameter category key

param1, param2, ..., paramN return value

Description Name of the Message Category object, as defined in Siebel Tools, that is the parent of the key value The error text is based on the specified key, looked up for the current language from the Message Category "User-Defined Errors". In Siebel Tools, the key appears as the Message Name property of the Message object. Optional parameters used to format the error message if it contains any substitution parameters (%1, %2, etc.) A string containing the localized version of the message text.

LookupMessage is useful for retrieving locale specific custom error messages. For more information, see the following section in this document, "Scripting in a Multilingual Environment". LookupMessage is one of the global state functions the Application object provides that return information about the current state of the system.

Examples
The following examples illustrate the use of Message Category, RaiseError, RaiseErrorText, and LookupMessage.

Message Category Example

Messages for LookupMessage and RaiseError are maintained and managed under Message Category in the Types Object Explorer. If the Message Category object in the Siebel Tools Object Explorer is not already displayed, select View > Options, and then select the Object Explorer tab in the Development Tools Options dialog.

2/15/2002

Page 14

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Adding Message Category to Types tab in Object Explorer

Message Category is the category of messages found in the user interface, for example <swe:messages> tag, used by the Siebel Web Engine, and user defined error messages. The properties of Message Category are as follows: Property Name Description/Usage Name of the Message Category Example User Defined Errors

Expanding the Message Category Object in the Type tab of the Object Explorer exposes the Message child object. Message is used with the Query function in the user interface, to display text when a query is submitted and when the results are received. It is used with <swe:messages> tag of the Siebel Web Engine. The properties of Message are as follows: Property Name Text Description/Usage Name of the message The text of the message Example TestMessage This is a test message

2/15/2002

Page 15

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Finally, expanding Message exposes the child object Message Locale. Message Locale represents the language-specific overrides used with the Message object type. The properties of Message Locale are as follows: Property Name Text Description/Usage The abbreviation of the language used by the application The text of the message Example ENU "This is a test message"

Creating a Message in Siebel Tools

To create a message in Siebel Tools, expand the Message Category object in the Type tab of the Object Explorer and select User Defined Errors in the Message Category list applet. Then select the child object, Messages, under Message Category in the Object Explorer to display the Messages list applet. Create a new record in the Messages applet, specifying the Name of the message and the Text of the message. If dynamic parameters are to be displayed in the message, use % followed by a number indication the order of the parameter(s) passed in to the function.

Message Category objects in the Object Explorer

Navigating to the Message Locale child object will display the language specific records automatically created: These can be translated into the language specified by the language code. Message Locale Records

2/15/2002

Page 16

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

The displayed message TestMessage will be used in the following examples.

RaiseError Server Script Example

In order to use RaiseError to display a message box from a server script, the following code could be placed in the BusComp_PreInvokeMethod. Server Script for RaiseError coded in Siebel Tools

Remember that the RaiseError method will cause execution of the script to terminate, so no lines of code following the call to RaiseError will be executed. The line of code in the example above "return (CancelOperation)" would not have been executed even if it had not been commented out. Commenting this line out serves to remind the developer that the operation has been cancelled. Compiling and executing the above code in the application will result in the following message box being displayed when the Test button (upper left corner in image below) is clicked. Note that the parameter text Test button has replaced the %1 parameter placeholder in the Message TestMessage defined above. RaiseError message box in a Siebel 7 Application

2/15/2002

Page 17

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

RaiseErrorText Server Script Example

In a similar fashion RaiseErrorText can be used to display a message box from server script containing a dynamic message, by placing the following code in the BusComp_PreInvokeMethod event handler. Server Script for RaiseErrorText coded in Siebel Tools

Once again, remember that the RaiseErrorText method will cause execution of the script to terminate, so no lines of code following the call to RaiseErrorText will be executed. The line of code in the example above "return (CancelOperation)" would not have been executed even if it had not been commented out. Commenting this line out serves to remind the developer that the operation has been cancelled. Compiled and executing the above code in the application will result in the following message box being displayed when the Test button (upper left corner in image below) is clicked. The actual message coded in the function now is passed into the RaiseErrorText function, rather than being accessed as a Message in the Message Category object, as it would be in the case of the RaiseError function. Note that in RaiseErrorText, the parameter placeholder %1 is embedded in the text parameter, and that the text Test button has replaced the %1 parameter placeholder in the message box below. RaiseErrorText message box in a Siebel 7 Application

2/15/2002

Page 18

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

LookupMessage Server Script Example

LookupMessage will return a translated string for the specified key in the current application language for the specified Message Category. The following server script example uses LookupMessage to retrieve the string, which is then customized, and passed to RaiseErrorText for display. Server Script for LookupMessage coded in Siebel Tools

In the above code, LookupMessage retrieves the requested message from the current language of the Message Category, User Defined Errors. This message is then customized by appending the string using %1 to allow for an additional parameter. This customized message is then passed into the RaiseErrorText function with the additional parameter, LookupMessage, which when compiled and executed, is displayed as follows. Using LookupMessage in a RaiseErrorText message box in Server Script

LookupMessage Browser Script Example

The purpose of this example is to display a language neutral message from browser script that states that the field is required whenever the user clears the contents of the required First Name and Last Name fields in the Contact Form Applet. To begin, another message named Required Message, must be added to the Message child object of the User Defined Errors Message Category in Siebel Tools. This is done as follows: Expand the Message Category object in the Type tab of the Object Explorer and select User Defined Errors in the Message Category list applet.

2/15/2002

Page 19

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Select the child object, Messages, under Message Category in the Object Explorer to display the Messages list applet. Create a new record in the Messages applet, specifying the Name of the message as "Required Field", and the Text of the message as "%1 is a required field and may not be blank".

Required Field Message added to User Defined Errors Message Category

This is the message that will display in a browser script alert, monitored in the Applet_ChangeFieldValue event, each time the user clears a required field. But to retrieve this message via LookupMessage from the server, it will be necessary to create a Business Service.

2/15/2002

Page 20

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Building a LookupMessage Business Service Next, create the Business Service called LookupMessage, which will be used in this example. Adding a Business Service

Now the Business Service function that will be called from browser script, LookupMsg, must be added to the business service. This function takes two property sets, psInputs and psOutputs, as parameters. The property set psInputs will contain the name of the field that is changed, and will be passed into the LookupMessage call. The property set psOutputs will return the message that is retrieved via LookupMessage. Note in the code that in order to access to message we just added, the Message Category, User Defined Errors, and the Message Name, Required Field, are also passed into the LookupMessage function. Adding LookupMsg Function to the Business Service

Finally, in order to call the LookupMsg function just added to the Business Service from the browser Applet_ChangeFieldValue event handler, the Service_PreInvokeMethod must be modified as follows.

2/15/2002

Page 21

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Modifying the Service_PreInvokeMethod to handle the LookupMsg function

Accessing the LookupMsg Business Service in the Applet_ChangeFieldValue Event Handler All that remains now is to script the Applet_ChangeFieldValue event handler to invoke the LookupMsg in the LookupMessage Business Service the each time the user clears either of the required fields, First Name or Last Name. Applet_ChangeFieldValue code to call the LookupMessage Business Service

Thus, when a required field is cleared, the following language neutral alert is displayed. Using a Business Service to access LookupMessage from Browser Script

2/15/2002

Page 22

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Scripting in a Multilingual Environment

Description
Multilingual deployments of Siebel eBusiness Applications version 7.x/8.x present special challenges for scripting. The issues that must be addressed are:

Messaging Issues
How to deal with server-side error messages that need to be displayed on the client How to deal with browser-side error messages

Internal Coding Issues

How to default field values via script How to set search expressions in script How to do conditional comparisons in script

Each of these issues will be dealt with in this section. This section assumes that the reader has a basic understanding of Siebel Scripting and Multilingual List of Values. For additional background on these topics, please consult the Siebel Bookshelf > Object Interfaces Reference and Global Deployment Guide respectively.

Messaging Background
Siebel eBusiness Applications version 7.x/8.x has built-in mechanisms for handling multilingual user messages in server and browser scripts. As noted in the above section, "Using the RaiseError, RaiseErrorText, and LookupMessage Functions in Server Script and Browser Script", the developer can create different Message Category objects in Siebel Tools, such as User-defined Errors or Client Messages. The Message Category object has a child object called Message. Using the Message object, the developer creates a descriptive key for each message for a category. For instance, in the Message Category User-defined Errors, there could Messages with keys like InvalidPhone, BadZipCode, NoSuchUser. These message keys are not the actual message delivered to the user. They are merely keys that will be used to look up the language-appropriate message for the user. The Message object has a child object called Message Locale. The Message Locale object contains the actual message translations for each Message object. For instance, for the Message object with key NoSuchUser, there could be a Message Locale entry for English with the text, Sorry. This user doesnt exist and a Message Locale entry for 2/15/2002 Page 23 .

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Spanish with the text, No tal usuario. Note that for each Message there can be only one Message Locale record for a specific language. Below is a graphic showing this example in Siebel Tools:

Server-Side Error Messages

RaiseError Method
As noted in the previous section, the Application objects RaiseError method is used in server script to display error messages in the current users language. The simplified syntax for RaiseError is as follows:
TheApplication().RaiseError(<Message Key>)

where <Message Key> is one of the Message keys from the User-Defined Errors Message Category in Siebel Tools.

Code Sample
In the following example, the RaiseError method would display an error message in the current users language.

2/15/2002

Page 24

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

function BusComp_PreWriteRecord() { Code to lookup the User field. if(!bcUser.FirstRecord()) { TheApplication().RaiseError(NoSuchUser); return(CancelOperation); } }

Browser-Side Error Messages

LookupMessage Method
As noted above, the Application objects LookupMessage method is used to retrieve general user messages from the User Category object. Note than unlike the RaiseError method, the LookupMessage method is not restricted to the User-Defined Errors message category and it does not provide a mechanism to display the message that is retrieved. Although the LookupMessage method only works in server script, a browerser script can call server-side business services. In this manner, LookupMessage may be used to display language-specific messages to users in browser script. The idea here is to create a browser-script business service that communicates with a server-side business service. Refer to the previous section for a detailed example. The simplified syntax for the LookupMessage method is:
TheApplication().LookupMessage(<Message Category>, <Message Key>)

where <Message Category> is the name of one of the Message Category records in Siebel Tools and <Message Key> is the key for the Message object in the <Message Category>. In Siebel 7.x/8.x, the LookupMessage method only works in Server Script, but we can call server-side business services from browser script, so we can make use of LookupMessage to display language-specific messages to users in browser script. The idea here is to create a browser-script business service that communicates with a serverside business service to get the message as in the example below.

Code Sample
Custom Server-side Business Service GetMessage
function Service_PreInvokeMethod(MethodName, Inputs, Outputs) { if(MethodName == LookupMessage) { var sCategory = Inputs.GetProperty(Category); var sKey = Inputs.GetProperty(Key); var sReturn = TheApplication().LookupMessage(sCategory, sKey); Outputs.SetProperty(Msg, sReturn); return(CancelOperation); } }

2/15/2002

Page 25

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Custom Client-side Business Service LookupMessage

function Service_PreInvokeMethod(methodName, inputPropSet, outputPropSet) { if(methodName == LookupMessage) { try{ var sCategory = inputPropSet.GetProperty(Category); var sKey = inputPropSet.GetProperty(Key); var oService = TheApplication().GetService(GetMessage); var iPropSet = TheApplication().NewPropertySet(); iPropSet.SetProperty(Category, sCategory); iPropSet.SetProperty(Key, sKey); var oPropSet = oService.InvokeMethod(LookupMessage,iPropSet); sReturn = oPropSet.GetProperty(Msg); //note following way of setting the output property set works in Siebel 7.0.4 forward. //Prior to this version there was a bug that required a little more obscure syntax outputPropSet.SetProperty(Msg, sReturn); return(CancelOperation); } catch(e){ alert(An error has occurred in the Service_PreInvokeMethod + of the + this.Name() + object.\n + e.message); } finally { oService = null; iPropSet = null; oPropSet = null; }

Internal Coding Background

The mechanism in Siebel eBusiness Applications for dealing with multilingual issues within a script makes use of the built-in multilingual support for Multilingual List of Values (MLOV). There are two functions in particular that are of interest: LookUpValue(<type>, <LIC>): takes the LOV type and the Language Independent Code (LIC) as arguments and returns the translated value based on the language that the application is currently running in. LookUpName(<type>, <Display Value>): takes the LOV type and the translated display value and returns the Language Independent Code.

These functions are available in Siebel Tools for use in calculated fields, validations and search specifications. They can also be easily written for the scripting environment using business services. Once these functions are coded into business services, they will be available throughout the application and can be used in the cases that follow. Custom Application methods can also be created to mimic the LookUpValue and LookUpName functions:

2/15/2002

Page 26

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

function LookupValue(sType, sLIC) { try{ var oService = TheApplication().GetService(MLOVService); var inPropSet = TheApplication().NewPropertySet(); var outPropSet = TheApplication().NewPropertySet(); var sReturn; inPropSet.SetProperty(Type, sType); inPropSet.SetProperty(LIC, sLIC); oService.InvokeMethod(LookupValue, inPropSet, outPropSet); sReturn = outPropSet.GetProperty(TranslatedValue); if(sReturn != ) return(sReturn);
else RaiseError(MLOV_BadTypeOrLIC);

} catch(e) { throw e.toString(); } finally { oService = null; inPropSet = null; outProptSet = null; } }

The custom LookupName would look very similar, but would return the LIC instead of the translated value.

Defaulting or Setting Field Values

To default a field value through script when the field uses MLOV, the script should hardcode the LIC and dynamically look up the language specific value to place into the field. In order to do this, the developer would use the LookUpValue() method to retrieve the Language Specific Values for a given Language Independent Code. For example:
function BusComp_NewRecord() { //default Type value for new records var sType = TheApplication().LookupValue(ACCNT_TYPE, NewAccount); this.SetFieldValue(Type, sType); }

2/15/2002

Page 27

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

The example above is a case of pre-defaulting a field. This technique will also work for situations where a post-default is needed, or in any case where a field needs to be set based on a conditional expression.

Setting Search Specifications

Setting search specifications in script is like automating a user-defined query with the developer choosing the search criteria. In this case, the developer must set the search specs based on Language Specific Values. Again, the developer would use the custom method LookupValue() to return a language-specific value based on an LIC. This means that an LIC will be coded in the script causing a Language Specific Value to be retrieved and entered as part of the Search Specification. For example:
function BusComp_WriteRecord() { try{ //Only search active accounts var sSearchSpec = TheApplication().LookupValue(ACCNT_TYPE, Active); with(bcAccount) { ClearToQuery(); SetSearchSpec(Type, sSearchSpec); ExecuteQuery(ForwardOnly); } } catch(e) { throw e.toString(); } }

Conditional Statements
Conditional statements need to operate independently of language, but the fields on which they operate will contain Language Specific Values when the business component is queried. Therefore, the developer will need to use the LookupName function, which returns the LIC for a language-specific value. The idea is that when the developer retrieves a language-specific field value with the BusComp.GetFieldValue method, the LIC for the field value will then be retrieved using LookupName in order to compare it with the hard-coded LIC in script and not languagespecific value. For example:

2/15/2002

Page 28

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8 function BusComp_SetFieldValue(FieldName) { try{ if(FieldName == Type) { var sFieldValue = this.GetFieldValue(FieldName); var sLIC = TheApplication().LookupName(ACCNT_TYPE, sFieldValue); if(sLIC == GoldAccnt) this.SetFieldValue(Free Coffee, Y); // Note that Boolean fields like this are intrinsically language-independent. // So there is no need to translate them. } } catch(e){ throw e.toString(); } }

Version 1.01

Conclusion
Using the techniques outlined in this section will allow organizations to deploy scripts that will meet the needs of multilingual deployments.

2/15/2002

Page 29

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

How to Invoke a Business Service on the Server from a Browser Script

Description
Siebel Business Services in Siebel 7.x/8.x can contain both server and browser script. Business service methods execute within the browser if they are written in browser script or on the server if they are written in server script. This section describes how to invoke business service methods written in server script from an applet browser script. First, it is important to note that a server script cannot be directly called from a browser script; invoking a server script from a browser script is an implicit operation. The interaction manager on the Siebel Web Client processes requests to invoke methods on business services. When a business service method is invoked with InvokeMethod() from browser script, the events are triggered in the following order:

If either of the PreInvokeMethod events returns CancelOperation, the sequence is aborted. Siebel Business Services can contain any combination of browser and server script, which allows services to exist that contain only browser script or only server script. Siebel Business Services that contain only browser script will execute exclusively on the browser, while those that contain only server script will execute exclusively on the server. This example uses a business service that contains only server script. This way, an applet script can invoke a method on, and retrieve a return value from, a server script. The primary reason a developer would want to invoke a server script from a browser script is that it is not possible to execute queries on arbitrary business components from browser script. The Siebel Object Interfaces available to browser script are a subset of those available to server script and do not include the business component methods such as ClearToQuery(), ExecuteQuery(), FirstRecord(), and so on needed to query the database. As a result, to execute a query, update fields, or interact with the database at all, server script must be used. In many cases this does not require both browser and server script, as the developer can write all the script on server events. In the case that browser script must be used to trigger a server script (most often for some sort of field-level validation), the technique illustrated in the following example can be used. Another reason to use server script for business logic that interacts with the database is that using server script is the best way to keep queries and data manipulation as close to

2/15/2002

Page 30

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

the database server as possible. Data that is transferred between the browser and the Siebel Web Engine undergoes several iterations of encoding and processing, whereas server objects interact directly with the Data Manager layer, which exchanges data directly with the database.

Examples
Following are the steps required to write a browser script that passes data to a server script and then have the server script return a different value to the browser script: Add the following script to the ChangeFieldValue event of any list applet for example, the Account List Applet.
function Applet_ChangeFieldValue (field, value) { try{ var bsTest; var psInputs; var psOutputs; var sReturnValue; bsTest = TheApplication().GetService( "Test" ); psInputs = TheApplication().NewPropertySet(); psInputs.SetProperty( "Input Value", "Sent from browser"); // // Note that the output property set is returned from InvokeMethod() unlike server script // where it is simply modified by the method but not returned. // psOutputs = bsTest.InvokeMethod( "Test", psInputs ); sReturnValue = psOutputs.GetProperty( "Return Value" ); alert( "Return value = " + sReturnValue ); } catch(e){ alert(An error occurred in the Applet_ChangeFieldValue event of the + this.Name() + object.\n + e.message); } finally{ psInputs = null; psOutputs = null; bsTest = null; } }

Then create a business service named Test and modify the Service_PreInvokeMethod server script function to resemble the code in the next example. The PreInvokeMethod event must be used to return CancelOperation to stop the Siebel Object Manager from executing the named method against the base class of the service.

2/15/2002

Page 31

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

function Service_PreInvokeMethod (MethodName, Inputs, Outputs) { switch ( MethodName ) { case "Test": Test( Inputs, Outputs ); // Return CancelOperation so the OM does not attempt to invoke the custom //method on the business service's base class. return( CancelOperation ); } return (ContinueOperation); }

2/15/2002

Page 32

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Then add the Test() function to the same business service:

function Test( psInputs, psOutputs ) { // Since this script is executing on the server, we can trace what's happening with the // Trace() functions. TheApplication().TraceOn("D:\\sea7\\Test.txt", "Allocation", "All" ); var sInputValue; sInputValue = psInputs.GetProperty( "Input Value" ); TheApplication().Trace( "Input value = " + sInputValue ); psOutputs.SetProperty( "Return Value", "Returned from server" ); TheApplication().TraceOff(); }

The first script (a browser script) will invoke the Test method on the second set of scripts (server scripts) and display the value returned.

Best Practices
To get the best response time from the above script, developers should adhere to a few best practices. There is network traffic overhead associated with invoking business services and exchanging data with the server. When a business service is invoked from an applet script, the local interaction manager (all written in JavaScript) must invoke any pre-event browser script, package the invocation for delivery to the server, transmit and receive results, and invoke the post-event browser script. This puts processing overhead on the client and creates more work for the Siebel Web Engine, which attenuates scalability. To minimize the processing overhead placed on the client and on the Siebel Web Engine when calling server-based services, the best practice is to exchange only parameters and return values, not result sets. For example, overall system performance will suffer if a developer writes a business service that the results to the calling browser script. It may seem useful to write such a service, but the amount of overhead required to do so will limit scalability. Another best practice is to centralize functionality as much as possible in either browser or server script. Centralizing functionality helps performance by minimizing network traffic. Centralizing functionality also eases maintenance, debugging, and future development.

2/15/2002

Page 33

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

Creating Custom Modal Dialog Boxes in Browser Script

Create an HTML page for the Modal Dialog Box
To create a custom modal dialog box in the browser, perform the following steps.

1. Create a Custom Web Page like the following:

<HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0"> <link href="files/main.css" rel="stylesheet"/> <TITLE> </TITLE> <SCRIPT> var arr = window.dialogArguments; returnValue = 2; var intButtons = parseInt(arr.buttons); function InitMe() { theForm.Yes.disabled = false; document.body.disabled = false; } </SCRIPT> </HEAD> <BODY bgcolor=buttonface margin=0> <SCRIPT> document.title=arr.title; </SCRIPT> <TABLE cellSpacing=20 cellPadding=0 width="100%" height="80" align="center" border=0> <TR> <SCRIPT> if((intButtons | 16) == intButtons) document.write('<TD width="10%"><div align="center"><IMG src="IMAGES/msgbox_critical.gif"></TD>'); else if((intButtons | 32) == intButtons) document.write('<TD width="10%"><div align="center"><IMG src="IMAGES/msgbox_question.gif"></TD>'); else if((intButtons | 48) == intButtons) document.write('<TD width="10%"><div align="center"><IMG src="IMAGES/msgbox_exclamation.gif"></TD>'); else if((intButtons | 64) == intButtons) document.write('<TD width="10%"><div align="center"><IMG src="IMAGES/msgbox_information.gif"></TD>'); </SCRIPT> <TD width="90%"><div align="center">

2/15/2002

Page 34

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

1. Create a custom web page like the following (Continued):

<SCRIPT> document.write(arr.prompt); </SCRIPT> </div></TD></TR> </TABLE> <TABLE cellSpacing=10 cellPadding=0 width="100%" align="center" border=0> <TR valign="bottom" align="center"> <TD align="center"><div align="center"> <form id=theForm name=theForm> <SCRIPT> //5 = Retry and Cancel if((intButtons | 5) == intButtons) { document.write('<INPUT id=Retry type=button value=Retry ' + 'name=Retry onclick="Javascript:returnValue=4;window.close();">&nbsp;'); document.write('<INPUT id=Cancel type=button value=Cancel ' + 'name=Cancel onclick="Javascript:returnValue=2;window.close();">&nbsp;'); } //4 = Yes and No else if((intButtons | 4) == intButtons) { document.write('<INPUT id=Yes type=button value=Yes ' + 'name=Yes onclick="Javascript:returnValue=6;window.close();">&nbsp;'); document.write('<INPUT id=No type=button value=No ' + 'name=No onclick="Javascript:returnValue=7;window.close();">&nbsp;'); } //3 = Yes, No and Cancel else if((intButtons | 3) == intButtons) { document.write('<INPUT id=Yes type=button value=Yes ' + 'name=Yes onclick="Javascript:returnValue=6;window.close();">&nbsp;'); document.write('<INPUT id=No type=button value=No ' + 'name=No onclick="Javascript:returnValue=7;window.close();">&nbsp;'); document.write('<INPUT id=Cancel type=button value=Cancel ' + 'name=Cancel onclick="Javascript:returnValue=2;window.close();">&nbsp;'); } //2 = Abort, Retry, Ignore else if((intButtons | 2) == intButtons) { document.write('<INPUT id=Abort type=button value=Abort ' + 'name=Abort onclick="Javascript:returnValue=3;window.close();">&nbsp;'); document.write('<INPUT id=Retry type=button value=Retry ' + 'name=Retry onclick="Javascript:returnValue=4;window.close();">&nbsp;'); document.write('<INPUT id=Ignore type=button value=Ignore ' + 'name=Ignore onclick="Javascript:returnValue=5;window.close();">&nbsp;'); } //1 = Ok and Cancel else if((intButtons | 1) == intButtons) { document.write('<INPUT id=OK type=button value=OK ' + 'name=OK onclick="Javascript:returnValue=1;window.close();">&nbsp;'); document.write('<INPUT id=Cancel type=button value=Cancel ' + 'name=Cancel onclick="Javascript:returnValue=2;window.close();">&nbsp;'); } //0 = Ok Only else document.write('<INPUT id=OK type=button value=OK ' + 'name=OK onclick="Javascript:returnValue=1;window.close();">&nbsp;');

2/15/2002

Page 35

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

1. Create a custom web page like the following (Continued):

</SCRIPT> </form> </div> </TD> </TR> </TABLE> </BODY> </HTML>

2. Place the custom web page in the sea7(8)X\\PUBLIC\ENU folder. 3. Create a browser-side business service to encapsulate calls for the modal dialog.
function HTMLMsgBox(inPropSet) { var msgtext = inPropSet.GetProperty("Message"); var titletext = inPropSet.GetProperty("Title"); var intButtons = parseInt(inPropSet.GetProperty("Buttons")); intButtons = parseInt(intButtons); var arr = new Object; arr.prompt = msgtext; arr.buttons = intButtons; arr.title = titletext; top.SetBusy(false); var intRet = theApplication().ShowModalDialog("MsgBox.htm", arr, "dialogHeight:150px; dialogLeft:200px; dialogWidth:500px; status:no; help:no;"); return intRet;

function Service_PreInvokeMethod (methodName, inputPropSet, outputPropSet) { switch(methodName) { case "HTMLMsgBox": var iRet = HTMLMsgBox(inputPropSet); //workaround for Output property set CR# 12-A7FUCI in browser script inputPropSet.SetProperty("Return", iRet); break; } return ("CancelOperation"); }

4. Call the business service from the browser script:

2/15/2002

Page 36

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

function Applet_ChangeFieldValue (field, value) { try{ var myService = TheApplication().GetService("ModalDialog"); var inPropSet = TheApplication().NewPropertySet(); inputPropSet.SetProperty(Message, Are you sure you want to change the field?) inputPropSet.SetProperty(Title, Confirmation); inputPropSet.SetProperty(Buttons, 35); //yes, no, cancel + ? var myProp = myService.InvokeMethod("HTMLMsgBox", inPropSet); var sReturn = myProp.GetProperty(Return); if(sReturn == 6) alert(You clicked Yes); } catch(e){ alert(An error occurred in the Applet_ChangeFieldValue event of the + this.Name() + object.\n + e.message); } finally{ myService = null; inPropSet = null; myProp = null; }

Dynamic Read-Only Controls

Description
One of the exciting features regarding scripting in Siebel eBusiness Applications version 7.x/8.x is the dynamic visibility and read-only status of controls. Different approaches are required for the High Interactivity and Standard Interactivity clients.

High Interactivity
The correct method for determining if a control is read-only under High Interactivity client is to use the Data Driven Access Control user properties: BC Read Only Field, Field Read Only Field & Parent Read Only Field. These user properties are documented in Siebel Bookshelf > Siebel Developer's Reference > User Properties. By including a calculated field on the business component, these three user properties can set a single field, current row or the parent business component to read-only. As the driver for the user properties is a calculated field the read-only property of the controls on the user interface will react as the data changes.

Standard Interactivity
The Data Driven Access Control user properties can also be used within the Standard Interactivity client. However, as the Standard Interactivity client works on a connectionless protocol, this method requires a round-trip from the client to the server in order to recalculate the calculated field upon which the user properties depend. This may provide an unacceptable response time.

2/15/2002

Page 37

Technote: Browser Scripting Techniques in Siebel 7 and Siebel 8

Version 1.01

In cases where a dynamic read-only control is required on the user interface, browser script will be required to obtain a handle to the control through the Document Object Model and change the readOnly property of the HTML tag representing the control. By setting the HTMLAttribute property of the control to provide a unique Id value in tools, this field can be referenced in browser script by specifying the applet name and control Id, and its HTML Attributes can be directly manipulated at runtime through browser script events.

2/15/2002

Page 38