Siebel Scripting – Advanced

concepts

Scripting Concepts: Advanced

2 of 16

Introduction

BusComps and BusObjects

PropertySets

TheApplication

Business Services

Scripting In Applets

Using Windows Script Popups

Garbage Disposal

Final Thoughts

3 of 16

BusComps And Bus Objects

The Bus Comp is a central object used in Siebel Scripting

It represents a Siebel Business Component

Has Child Objects, such as Fields

Must have a Bus Object to create a Bus Comp

4 of 16

BusObjects

Represent the Siebel Business Object

Two ways to create:

Both created using TheApplication object

ActiveBusObject

Any BusComps created from this way will have data in them

GetBusObject (“BusObjName”)

BusComps created from this will be empty, and must be filled before they can be used

5 of 16

ActiveBusObject Syntax

eScript

var boContact = TheApplication().ActiveBusObject();

var bcContact = boContact.GetBusComp(“Contact”);

Siebel VB

Dim boContact As BusObject

Dim bcContact As BusCOmp

Set boContact = TheApplication.ActiveBusObject

Set bcContact = boContact.GetBusComp(“Contact”)

bcContact will have data in it, because it is based on the Active Business Object

Generally used only in script on an Applet

6 of 16

GetBusObject Syntax

eScript

var boContact = TheApplication().GetBusObject(“Contact”);

var bcContact = boContact.GetBusComp(“Contact”);

Siebel VB

Dim boContact As BusObject

Dim bcContact As BusCOmp

Set boContact =

TheApplication.GetBusObject(“Contact”)

Set bcContact = boContact.GetBusComp(“Contact”)

bcContact will not have data in it

Must be filled by executing a Query on it

7 of 16

Querying a BusComp

Sometimes, a BusComp does not have any data (as when using

GetBusObject) or does not have the data you need- it is just an

empty structure

To get data into it, you must use the ExecuteQuery method of

the BusComp

However, there are other things you must also set before you

can call ExecuteQuery

8 of 16

Query Prerequisites

SetViewMode

ActivateField

ClearToQuery

SetSearchSpec

When you query a Business Component, you are building a

SQL query behind the scenes

9 of 16

SetViewMode Method

Used to filter data, similar to using the My Views, My Team‟s Views, All Across All Organization‟s View, and so on

Most of the Time, you will be using the AllView Mode, which does not filter any data at all (All Across All Organizations)

Syntax (eScript):

bcContact.SetViewMode(AllView);

In the SQL Query, this controls part of the where clause

10 of 16

ActivateField Method

Must be done before ClearToQuery

When a query is execute on a Business

Component, it does not automatically query for

every field, only the following:

Fields that are a part of the current Applet

System Fields

Fields that are set as Force Active

Fields that are Activated via the ActivateField Method

Syntax (Siebel VB):

bcName.ActivateField “FieldName”

In the SQL Query, this controls the Select clause

11 of 16

ClearToQuery Mothod

Clears any existing data from the Business Component about to

be queried

This includes any search spec included with the current Applet

Does clear any sort spec

In the SQL Query, this empties the where clause from previous

queries

12 of 16

SetSearchSpec Method

Can have multiple fields, but is usually only

consists of one field

Syntax and Example(eScript):

bcName.SetSearchSpec(“FieldName”, Value);

bcSR.SetSeachSpec(“Id”, “1-13G5T”);

In SQL, that translates to:

where ROW_ID = „1-13G5T‟

In the SQL Query, this gives the main part of the

where clause

If you use the Id field, the record set will contain at

most, one record

13 of 16

ExecuteQuery Method

Once all the pieces are in place, you can execute the

query

Syntax (Siebel VB):

bcName.ExecuteQuery Mode

Mode Determines how you can transverse the data

ForwardOnly: You can only go through the data in one

direction. You cannot go back to a record once you move

to another

ForwardBackward: Allows you to go through the data any

direction, or revisit any data already read. Slower and

more taxing on the database than ForwardOnly

14 of 16

The with (With) statement

With allows you to access many methods or sub-objects of an

object without repeating the name of the object

Since there are so many pre-requisites to executing a query, all

of which are methods of the same business component, with is

very useful in executing queries

15 of 16

ExecuteQuery With Siebel VB

With bcContact

.SetViewMode AllView

.ActivateField “Last Name”

.ActivateField “Email Address”

.ClearToQuery

.SetSearchSpec “Id”, sRowId

.ExecuteQuery ForwardOnly

End With

16 of 16

ExecuteQuery with eScript

with (bcContact)

{

SetViewMode(AllView);

ActivateField(“Last Name”);

ActivateField(“Email Address”);

ClearToQuery();

SetSearch Spec (“Id”, sRowId);

ExecuteQuery(ForwardOnly);

}

17 of 16

GetFieldValue

As expected, used to retrieve the value of a field in a business

component

Example:

sLName = bcContact.GetFieldValue(“Last Name”)

Takes an argument of a field of the BC (same spelling and case)

Returns the value in that field in the current record

If the field is not active, will cause an error

18 of 16

SetFieldValue

Sets a field in a BC to a specified value in the current record

Field does NOT have to be active

Takes two arguments, no return

The Field to be updated (same spelling and case as in the BC in

Tools)

The value to update it with (in string format)

19 of 16

Transversing BusComp Data

FirstRecord

NextRecord

PreviousRecord

LastRecord

20 of 16

FirstRecord Method

Moves the record pointer to the first record, if it exists

If it does, returns non-zero in SiebelVB, true in eScript

If no first record exists (which means that the query returned no

records), returns 0 (zero) in Siebel VB and false in eScript

If BusComp was queried in ForwardOnly mode, FirstRecord

cannot be called once the record pointer moves to any other

record

21 of 16

NextRecord Method

Moves record pointer to the next record in the data set

If there are no more records, returns 0 or false

If there are, returns non-zero or true

22 of 16

PreviousRecord Method

Same as NextRecord, including return values, except it moves

the record pointer to the previous record

May only be used on BusComps that have been queried in

ForwardBackward mode

23 of 16

LastRecord Method

Moves the record pointer to the last record in the data set

If there is a record, returns non-zero or true

If there are no records in the record set, returns 0 or false

Unless the query was made in ForwardBackward mode, cannot move to any other record after using this method

24 of 16

NewRecord Method

Begins creating a new record in the Business Component

New record is not saved until WriteRecord method is used

Use SetFieldValue to assign values to whatever fields you need to in the new record

Fields that have a pre or post default value will also get values in them

Use WriteRecord to save the new record once all values have been set

25 of 16

NewRecord Arguments

The NewRecord requires one argument that specifies where in

the current data set to save the new record

NewAfter saves the record after the current one

NewBefore Saves the record before the current one

26 of 16

NewRecord Example

with bcContact

{

NewRecord NewAfter;

SetFieldValue(“Last Name”, “Harrison”);

SetFieldValue(“First Name”, “James”);

SetFieldValue(“Home Phone #”, “7195550234”);

WriteRecord();

}

27 of 16

NewAfter(Before)Copy

You can also use NewAfterCopy or NewBeforeCopy to create a Copy of the current record

Just like right clicking in the application and selecting “Copy Record”

Must still use WriteRecord to Save the new record

Example:

bcContact.newRecord(NewAfterCopy);

bcContact.WriteRecord();

28 of 16

Other Important BC Methods

UndoRecord

Pick

DeleteRecord

GetMVGBusComp

GetPicklistBusComp

GetUserProperty

ParentBusComp

29 of 16

Property Sets

Simple description: name-value pairs

What that really means is that a property set can hold a number of separate string variables

Name: name of the string variable

Name can be whatever you choose, it is also stored as a string

Just be sure to be consistent

Value: value of that variable

30 of 16

Passing Data Between Objects

Can be used to pass information from one object to another

Set the values in one object

Retrieve them in the other, using the names you created when setting

Can pass all related data, such as different fields from the same BC record

Can also pass unrelated data, such as some BC fields, the BC name, and the number of current records in the BC record set

31 of 16

Hierarchical Property Sets

Property Sets not only contain name-value pairs, but can also

contain other property sets

This means that a property set hierarchy can be set up

One of the most important uses for this is seen in it‟s

comparison with XML:

32 of 16

XML

EXstensible Markup Language

Like HTML, is made up of tags and values, but the similarity

ends there

With HTML, there is <title>, <body>, <table>, <br>, <p> and so

on

In XML, there are no pre-defined tags, but there is structure

Opening and closing tags

Hierarchy of tags

33 of 16

XML Example

<Contact>

<FirstName>”Jay”</FirstName>

<LastName>”Smith”</LastName>

<Phone>”8055551234”</Phone>

<MiddleName></MiddleName>

<Email/>

</Contact>

34 of 16

XML And Property Sets

XML tags can contain data

Property Sets can also contain data

XML tags can contain other XML tags

Property Sets can contain other property sets

Property Sets are ideal for representing XML files in Siebel Script

Several pre-defined Business Services exits in Siebel that take advantage of this

35 of 16

Property Set Methods

NewPropertySet

SetProperty

GetProperty

AddChild

GetChild

PropertyExists

GetPropertyCount

GetChildCount

36 of 16

NewPropertySet Method

Is a method of TheApplication

Creates a new property set object or re-initializes (erases all

previous data) of an existing property set

Syntax:

Dim psIn As PropertySet

Set psIn = TheApplication.NewPropertySet

var psIn = TheApplication().NewPropertySet();

37 of 16

SetProperty GetProperty

Get or set a property in the property set

Syntax for Set:

psName.SetProperty(“PropName”, Value);

psIn.SetProperty(“LastName”, “Smith”);

Syntax for Get:

var sVar = psName.GetProperty(“PropName”);

Var sLName = psIn.GetProperty(“Last Name”);

38 of 16

AddChild Method

AddChild sets an existing property set as a child PS of another

existing property set

Both entities must be property sets- in eScript, if they aren‟t, they will

be changed into property sets

Syntax:

var psOuter = TheApplication().NewPropertySet();

var psInner = TheApplication().NewPropertySet();

psOuter.AddChild(psInner);

39 of 16

GetChild Method

Takes an integer as an argument

Child PropertySets are stored as if in an array that is numbered from 0 as the first Child PropertySet added

Returns a child property set or null, if no such PS exists

Syntax:

Dim psNew As PropertySet

Set psNew = psOld.GetChild(0)

40 of 16

PropertyExists Method

Very simple method- used to find out whether or

not a specific name property exists in a

PropertySet

Takes a string (the name of the property) as an

argument

Returns a boolean (or integer in VB) of either

true (or non-zero) if the property exists or false

(0) if the property does not

Using a GetProperty with a property that does

not exist will create an error- you can use this

method to ensure that doesn‟t happen

41 of 16

GetPropertyCount Method

Simply returns the number of properties in a Propset

Each time SetProperty is used with a new name, this count is increased by one

SetProperty with the same name simply changes the value of an existing property, thus the count does not increase

RemoveProperty will decrease the count by one

42 of 16

GetChildCount Method

Only returns the number of child propsets that belong directly to the PS it is used on- it does not tell anything about any children those propsets may have

iCount = psIn.GetChildCount();

But it can be “stacked” with GetChild

iCount = psIn.GetChild (2).GetChildCount();

This returns the number of children of the 3rd child of psIn (remember, starts at 0), not the number of children of psIn itself

43 of 16

Property Sets

Property Sets are one of the most important objects in Siebel

It is important to learn all you can about using them

Using a Property Sets to their full potential is the mark of a good

Siebel scripter

44 of 16

TheApplication Object

TheApplication is a special object in the Siebel World

It represents the actual Application you are using (Call Center, Financial Services, etc) in code

Any code placed on the Application Object is a part of TheApplication object

In eScript, this code (methods and objects) can be accessed from anywhere else in the system

45 of 16

Business Services

As previously mentioned, Business Services are Siebel object

with one purpose: To hold scripts

They are the best place to hold scripts that will be accessed

from elsewhere

For some simple scripts, consider using TheApplication with

eScript

46 of 16

The PreInvokeMethod Event

In each Siebel Object that can be scripted, there are a few important events:

PreCanInvokeMethod

PreInvokeMethod

InvokeMethod

Each time a method in the object is called, these events fire

However, there are internal events that fire first

47 of 16

Internal Events

Whenever a method is called, the following events happen Internal PreInvokeMethod

Scripted PreInvokeMethod

Internal InvokeMethod

Scripted InvokeMethod

If Internal Invoke Method is called on any Method that is not declared internally in Siebel, an error is generated

Therefore, you must put the code you wish to execute in your Methods in the PreInvokeMethod event, and then tell Siebel to cancel the operation

48 of 16

Canceling The Operation

Each event returns an integer constant, either

ContinueOperation or CancelOperation

CancelOperation tells the system to stop trying to run

InvokeMethod on the named method

InvokeMethod can only be run on methods that have been

declared internally, so you must return this from the

PreInvokeMethod of any method you create

49 of 16

Canceling The Invoke Syntax

In PreInvokeMethod Event:

if (MethodName == “MyMethod”)

{

// Code that you need to accomplish in your

// method

return (CancelOperation);

}

Better way is demonstrated on the white board

50 of 16

Functions

Instead of putting all of your code into the PreInvokeMethod event, consider creating functions in the object and calling those

function MyFunction()

{

// put all my method code here

}

Call this function from the PreInvokeMethod event

51 of 16

Function Example

function GetName (sRowId)

{ var boCnct = TheApplication().GetBusObject(“Contact”);

var bcContact = boCnct .GetBusComp(“Contact”);

var sName = “”;

with (bcContact)

{ SetViewMode(AllView);

ActivateField(“Last Name”);

ClearToQuery();

SetSearchSpec(“Id, sRowId);

ExecuteQuery(ForwardOnly);

}

sName = bcContact.GetFieldValue(“Last Name”);

return (sName);

}

52 of 16

Calling The Function

In BS PreInvokeMethod Event:

var iRetVal = ContinueOperation;

if (MethodName == “GetLName”)

{ // Make sure to cancel InvokeMethod

iRetVal = CancelOperation;

// Get Data

var sContactId = Inputs.GetProperty(“Contact Id”);

//Call Function

var sLName = GetName(sContactId);

//Send the data back out of the BS

Outputs.SetProperty(“Last Name”, sLName);

}

return (iRetVal);

53 of 16

Calling A Method In A

Business Service 1) Declare the service and property sets

2) Get the Service

3) Set any appropriate input property set

4) Invoke the Method, passing the method name, input property

set, and output property set

5) Retrieve any returned data from the output property set

54 of 16

Declare The Objects

var psIn = TheApplication().NewPropertySet();

var psOut = TheApplication().NewPropertySet();

Var bsCode = TheApplication.GetService(“Service Name”);

55 of 16

Set Up The Input Property Set

Set Properties in input property set of any data that needs to be

passed to the business service

psIn.SetProperty(“Contact Id”, “1-145FT”);

psIn.SetProperty(“BC Name”, “Contact”);

56 of 16

InvokeMethod

The InvokeMethod method is a special method in Siebel

Use it to call a method from any object

Take 3 arguments:

A string that is the name of the method

A property set that includes all of the data being passed into the method

A property set that can be used to pass data back out of the object

Syntax:

Object.InvokeMethod(“MethodName”, InPS, OutPS);

57 of 16

Retrieve Returned Data

In your objects, use the output property set to pass data back

out

Notice that the PreInvokeMethod event has three arguments

passed to it: MethodName, Inputs, Outputs –just like what you

pass in the InvokeMethod method

Syntax:

var sName = psOut.GetProperty(“Last Name”);

58 of 16

Full Example

WebApplet_PreInvokeMethod

{

var iRetVal = ContinueOperation;

if (MethodName == “GetLName”)

{

iRetVal = CancelOperation;

GetLastName();

}

return (iRetVal);

}

59 of 16

GetLastName Function

function GetLastName()

{ var sRowId = this.BusComp.GetFieldValue(“Id”);

Var bsGetName = TheApplication().GetService(“Contact Name BS”);

var psIn = TheApplication().NewPropertySet();

var psOut = TheApplication().NewPropertySet();

psIn.SetProperty(“Contact Id”, sRowId);

bsGetName.InvokeMethod(“GetLName”, psIn, psOut);

var sName = psOut.GetProperty(“Last Name”);

this.BusComp.SetFieldValue(“Alias”, sName);

}

60 of 16

Applet Scripting

The primary use for scripting in applets is to make buttons

First, create a button on the web layout of the applet (copying an

existing one is easiest)

Set the Name Property, the MethodInvoked property, and the

Caption Property

Then add code to the PreCanInvokeMethod and the

PreInvokeMethod events using the MethodInvoked value as your

MethodName

61 of 16

PreCanInvokeMethod

The PreCanInvokeMethod event is an event that fires for every control on the applet as soon as the applet is loaded, and often after that

It takes two arguments

The MethodName

A string called CanInvoke (by Reference)

Set CanInvoke to “TRUE” in order to make your button clickable

62 of 16

PreCanInvoke Example

WebApplet_PreCanInvokeMethod(MethodName, &CanInvoke)

{ var iRetVal = ContinueOperation;

if (MethodName == “MyMethod”)

{ iRetVal = CancelOperation;

CanInvoke = “TRUE”;

}

return (iRetVal);

}

63 of 16

Example Explanation

All that code is simply to make the button clickable (not grayed-

out)

Note that you must also return CancelOperation in

PreCanInvokeMethod as well, just like PreInvokeMethod –if you

don‟t, it will cause an error

64 of 16

Applet Considerations

Use PreCanInvoke to make button clickable

Always best to use function in the declarations section for your

actual work-code, rather than putting it in the PreInvokeMethod

event

Even better is to create a business service and call that from

your applet code

Makes your script more modularized and re-usable

65 of 16

Windows Script Object

Useful for debugging only

Can be used to create popup windows, but since they are made

with a Windows Script, they are created on the machine that

they are called on

In other words, they only work with a Mobile Client, not with a Web

Client

66 of 16

Creating a WScript Object

eScript:

var WShell;

WShell = COMCreateObject(“WScript.Shell”);

Siebel VB:

Dim WShell as Object

Set WShell = CreateObject(“WScript.Shell”)

67 of 16

Using the WScript Popup

WShell.Popup(“Message”);

WShell.Popup(“Hello World”);

WShell.Popup(bcContact.GetFieldValue(“Id”);

68 of 16

Garbage Disposal

Objects are dynamically created by the Siebel system using memory allocation

The system cleans them up automatically, but it doesn‟t do a very good job –it doesn‟t necessarily clean them up in the proper order

For example, since a BusComp is created from a BusObject, if the BusObject happens to get cleaned up before the BusComp, there is no more access to the BusComp to clean it up with

69 of 16

Garbage Disposal cont

Therefore, you should clean it up yourself

Always remove objects in the reverse order than they were created

eScript:

bcContact = null;

boCnct = null;

Siebel VB:

Set bcContact = Nothing

Set boCnct = Nothing

70 of 16

Scripting Final Thoughts

We have just scratched the surface on what scripting can do

Always continue studying scripting and practicing it

All of the Use Scenarios (full assignments) at the end of the course will include some scripting

(In my opinion) A Siebel Consultant who can‟t script isn‟t worth a damn to anyone