2About Object Interfaces and the Programming Environment
About Object Interfaces and the Programming Environment
This chapter describes Oracle’s Siebel Object Interfaces and the programming environment you use to customize them. It includes the following topics:
Object Interfaces You Can Use to Access Siebel Objects
This topic describes object interfaces you can use to access Siebel objects. It includes the following topics:
Overview of Interfaces You Use to Access Siebel Objects
A Siebel object interface is a collection of object interface methods that reside on Siebel objects that make their data and functions available to custom code that you write in Server Script, and also to other languages that are external to Siebel CRM. These interfaces provide access to Siebel business objects that contain object interface methods, object interface events, and data.
A Siebel object interface can provide an interface between Siebel CRM and an external application. Siebel object interface definitions reference Siebel business objects and object definitions that you can configure so that Siebel CRM automatically upgrades them during a release update.
You can integrate client and server applications from different third-party vendors. Application integration typically requires that software programs interactively pass data back and forth. Application integration sometimes requires that one application controls another application.
An object interface methodis a function that allows you to control data and objects. Siebel CRM provides object interface methods to perform operations, such as manipulating files that Siebel CRM stores in the Siebel File System, or updating records through a Siebel object, such as a business component.
Objects You Can Access Through a Siebel Object Interface
You can use the following Siebel object interfaces to create or modify a Siebel object:
Scripting using Server Script or Browser Script
Component Object Model (COM) using the Web Client Automation Server, COM Data Control, COM Data Server, or Mobile Web Client Automation Server
Java using Siebel Java Data Bean
The following information lists the types of objects you can access. If a table cell includes Yes, then you can use the object type listed in the Object Type column with the Siebel object interface listed in the column header.
Table Types of Objects You Can Access Through a Siebel Object Interface
| Object Type | Server Script | Browser Script | Web Client Automation Server | Mobile Web Client Automation Server | COM Data Control | COM Data Server | Siebel Java Data Bean |
|---|---|---|---|---|---|---|---|
Applet |
Yes |
Yes |
No |
No |
No |
No |
No |
Application |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Business Component |
Yes |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Business Object |
Yes |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Business Service |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Property Set |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Control |
No |
Yes |
No |
No |
No |
No |
No |
Siebel CRM uses other object types that this topic does not describe, including some specialized types. If this topic does not describe an object type, then it is not available through a Siebel object interface. If you reference it, then Siebel CRM might not pass it to an external DLL, such as a Microsoft Visual Basic COM DLL.
For more information about the objects that the table in this topic describes, see Configuring Siebel Business Applications.
Applets
You can add a script to an applet to access this applet through an object interface. In Siebel Tools, you right-click the applet, and then choose the Edit Server Scripts or Edit Browser Scripts menu item. This work is similar to adding a script to a business component. For more information, see Using Script to Add Business Logic to a Business Component.
You can use the following scripting languages with an applet:
Siebel VB and Siebel eScript in a Server Script
Browser JavaScript in Browser Script
Business Services
A business service is an object type that contains a set of predefined methods. Siebel CRM uses C++ code to implement them. It can also contain custom methods that reside in Siebel script. It allows you to configure Siebel CRM to call C++ code or to call a scripted business service method from a script that you create. You can use a business service in the following ways:
Called from a script or from an object interface.
Reusable and can persist through a session.
Simulate a global procedure.
Provide a generic code library that Siebel CRM calls from multiple scripts.
Modify object properties. You can write a script in Siebel VB or Siebel eScript that configures a business service that modifies object properties.
You can do one of the following to create a custom business service:
Add a record in the Business Services list in Siebel Tools.
Use administrative views in the Siebel client.
To use the Web Client Automation Server or Browser Script to call a business service, you must register the business service in Siebel Tools as an application user property. This configuration prevents Service Not Found errors. For more information, see GetService Method for an Application.
You can use the following types of business services:
Repository. Defined in Siebel Tools and stored in the Siebel runtime repository.
Run-time. Defined in the Siebel client and stored in the Siebel database.
For more information, see Integration Platform Technologies: Siebel Enterprise Application Integration.
Repository Business Services
You can use the following types of repository business services:
Standard. References the CSSService class. You can script or modify a standard business service.
Specialized. References a specialized C++ class. If Siebel Bookshelf documents a specialized business service, then you can script or modify it.
You cannot configure Siebel CRM to modify a repository business service at run time, or to use a run-time script to override a predefined business service.
Property Sets
A property set is a collection of properties that you can use to store data. It can include a child property set that forms a tree data structure. You use a property set to handle inputs to and outputs from a business service. For more information, see Integration Platform Technologies: Siebel Enterprise Application Integration.
User Interface Controls
A user interface control is an object type that defines a user interface element, such as a text box, check box, or a button. Browser Script can access the properties of a control. The controls on the applet that are currently visible are the only controls that are available to Browser Script.
About the Siebel Java Data Bean Object Interface
The Siebel Java Data Bean is a set of Java libraries that use the J2SE Development Kit (JDK). It is similar to the interfaces that are available through COM Data Control. It allows you to do the following work:
Use an external application, external component, or Java applet to access Siebel objects without displaying the Siebel client.
Access a Siebel application to read and write data.
Incorporate the Java libraries in Java applications, applets, servlets, JSPs, or Enterprise Java Beans. You can add these items to your Java application.
For more information about:
Developer resources for Java technology, see the following:
Communication with an external application, see How an External Application Communicates with a Siebel Application.
Operating systems and JDKs that you can use, see Siebel System Requirements and Supported Platforms on Oracle Technology Network.
About the Siebel COM Object Interface
You can access a Siebel COM object interface in any of the following ways:
COM Data Control
COM Data Server
Web Client Automation Server
Mobile Web Client Automation Server
You can use any of the following languages to access a Siebel COM interface:
JavaScript
Visual Basic
C++
You cannot use the Perl programming language to access a Siebel COM interface.
The programming environment you use might limit the features that Siebel CRM can use the Siebel COM servers. For example, do not use Siebel VB code for the Data Server as a Windows NT service.
How an External Application Communicates with a Siebel Application
COM Data Control is a type of Siebel Object Interface that allows an external application to connect and communicate with the Siebel Application Object Manager, which is a multithreaded, multiprocess application server that hosts Siebel business objects and allows session connections with Siebel clients. This connection allows the external application to access Siebel business objects. The Siebel Internet Session Network API (SISNAPI) protocol allows this communication.
The following image illustrates how an external application uses COM Data Control to communicate with the Siebel application.
To use COM Data Control to develop a Siebel application, you must install, configure, and make sure Siebel CRM is running a Siebel Application Object Manager on a Siebel Server. For more information, see Siebel System Administration Guide.
For information about the SISNAPI protocol, see Siebel Deployment Planning Guide.
Servers That the Siebel COM Interface Uses
This topic describes the servers that the Siebel COM Interface uses.
Web Client Automation Server
The Web Client Automation Server does the following:
Allows an external application to call a business service and manipulate property sets.
Runs as a small Siebel COM object in the Web browser in Internet Explorer version 5.0 or later.
Can be used with the Siebel Web Client and the Siebel Mobile Web Client.
The following image illustrates how an external application can call a business service and manipulate a property set that resides on the Web Client Automation Server.
The Web Client Automation Server includes the following requirements:
The Siebel Web Client must be running.
You must set the EnableWebClientAutomation parameter for the Application Object Manager to TRUE. This setting configures Siebel CRM to download a small ActiveX control to the desktop and start the SiebelHTMLApplication process.
It might be necessary for you to adjust ActiveX controls, plug-ins, and security settings in the browser.
You cannot configure Siebel CRM to call the Web Client Automation Server directly from an active instance of a Siebel application.
Siebel CRM uses one of the following names for the process that represents the Web Client Automation Server. The Windows Task Manager displays this name:
siebelhtml.exe
siebelhtmlapplication.exe
SIEBEL~1.EXE
If the user ends the Siebel Web Client session, then Siebel CRM stops this process.
For more information, see Accessing the Web Client Automation Server.
Mobile Web Client Automation Server
The Mobile Web Client Automation Server accesses the server object that the Siebel application starts. If your configuration can access this object, then it can get other Siebel objects and run Siebel object interface methods through these other objects.
The following image illustrates how an external application can control a Siebel application that uses the Web Client Automation Server.
The Mobile Web Client Automation Server includes the following requirements:
The Siebel Mobile Web Client must be running.
The EnableWebClientAutomation parameter that resides in the InfraUIFramework section of the Siebel application configuration (CFG) file must be set to TRUE.
If you use Microsoft Visual Basic version 5.0 or later, then the sobjsrv.tlb file must reside in the same folder where the Siebel application configuration (CFG) file resides. If this file does not reside in the correct folder, then the COM Data Server does not work.
A call that you configure Siebel CRM to make to the Mobile Web Client Automation Server is out of process. If your customization creates a DLL that runs in process with the Siebel application, then the calls that Siebel CRM makes from the DLL to the Mobile Web Client Automation Server are out of process. For more information, see How Siebel CRM Uses Memory and Resources with the Mobile Web Client Automation Server.
For more information, see Accessing the Mobile Web Client Automation Server.
How Siebel CRM Uses Memory and Resources with the Mobile Web Client Automation Server
Siebel CRM starts a process to run the Siebel Mobile Web Client. This process uses memory and resources that are specific to this process, which are in process. If your configuration communicates with the Siebel Mobile Web Client while it is running, then the resources that Siebel CRM uses in this communication are separate form the memory and resources that it uses in the process that it started to run the Siebel Mobile Web Client. These separate resources are out of process.
COM Data Server
The following image illustrates how an external application uses the COM Data Server that does not include user interface objects. The COM Data Server uses the same technology that the Siebel Mobile Web Client uses to connect to the Siebel database.
The Mobile Web Client Automation Server includes the following requirements:
The way your configuration starts a Siebel COM server depends on the programming tool or language you use.
The COM Data Server runs without the Siebel client, so you must use the Login method to set up your Data Server object.
No current active Siebel objects exist, so you cannot use an object interface method that returns active Siebel objects. You must use your own Siebel objects.
If you use Microsoft Visual Basic version 5.0 or later, then the sobjsrv.tlb file must reside in the same folder as the Siebel application configuration (CFG) file. If this file does not reside in the correct folder, then the COM Data Server does not work.
Do not run the Microsoft VB Debug environment while your configuration communicates with the COM Data Server.
If your configuration uses the COM Data Server, then the COM client cannot create multiple connections to the Siebel COM Server. You must restart the COM client before you can attempt another connection. Use COM Data Control instead.
Calls made to the COM Data Server are in process. For more information, see How Siebel CRM Uses Memory and Resources with the Mobile Web Client Automation Server.
Note the different ways that the following servers handle DLLs:
COM Data Server. A DLL runs in the same address space where the calling program runs.
Mobile Web Client Automation Server. An executable runs in a dedicated address space. A DLL that a server task accesses must be capable of running in a multithread environment.
For more information, see Accessing the COM Data Server.
About the Siebel Programming Environment
This topic describes the Siebel programming environment.
Programming Languages
You can use the following programming languages to access object interface methods and object interface events:
Siebel VB (Siebel Visual Basic). A programming language that is syntactically and semantically compatible with Microsoft Visual Basic. It includes an editor, debugger, interpreter, and compiler. It runs only on the Windows operating system.
Siebel eScript. A programming language that is syntactically and semantically compatible with JavaScript. It uses the same tools that Siebel VB uses. Siebel eScript runs on the Windows and UNIX operating systems.
For more information, see Using Siebel Visual Basic and Siebel eScript.
Server Script
A Server Script is a type of script that the Siebel Server interprets and runs. You can use the following scripting languages in a Server Script:
Siebel VB. Siebel VB uses most of the same commands and standards as Microsoft Visual Basic, so you can customize your Siebel application and reduce training costs. Siebel CRM supports Siebel VB only on the Microsoft Windows operating system.
Siebel eScript. Siebel eScript uses most of the same commands and standards as JavaScript, so it provides you the same advantages in an alternative language. You can use Siebel eScript on all operating systems that Siebel CRM supports.
For more information, see Using Siebel Visual Basic and Siebel eScript.
Browser Script
A Browser Script is a type of script that the browser interprets and runs. It interacts with the Document Object Model and with the Siebel Object Model in the browser through the Browser Interaction Manager. You write Browser Script in JavaScript. You can script the behavior of Siebel events and the browser events that the Document Object Model makes available. The Document Object Models for Internet Explorer and Netscape Navigator are different.
Siebel CRM version 7 introduced Browser Script. For more information, see Document Object Model Events You Can Use.
Do not use Browser Script to manipulate the location of a frame or a form in Siebel CRM because this configuration causes Siebel CRM to load a new page. This configuration is a violation of preferred security practices, so the result is a permission denied error.
For more information, see Browser Script Quick Reference. For information about creating Browser Script, see Configuring Siebel Business Applications.
Siebel Script Editor
The Siebel Script Editor is an integrated editor that you can use to create, view, edit, and save custom code. It includes the Script Assist code editor. This editor includes the following features to help reduce errors when you develop a script:
Autocomplete.
Autoindentation.
A list of object interface methods.
Method signature capabilities. Some methods that the Script Assist editor lists include the input parameter names and types, outputs from the method, and the method type. For example, if a method returns chars, then it lists the following term: chars.
Siebel CRM version 7.8 introduced Script Assist. For more information, see Using Siebel Tools.
Siebel Debugger
The Siebel Debugger is a tool that helps you detect errors that occur in the code of a Siebel programming language. It does not help you detect errors that occur outside of the context of the code. You can configure Siebel CRM to start the Siebel Debugger automatically from a Siebel application if a run-time error occurs. You can also start the debugger from the Debug toolbar or the Debug menu in Siebel Tools. For more information, see Using Siebel Tools.
Siebel Compiler and Run-Time Engine
The Siebel Compiler and Run-Time Engine is a nonvisual component of a Siebel programming language that compiles and runs custom code. It is similar to Microsoft’s Visual Basic Language Interpreter. Siebel CRM compiles Siebel code and stores it in the Siebel runtime repository.
You can click the Compile icon on the Debugger toolbar in Siebel Tools to start the Siebel Compiler and Run-Time Engine. You can also start it if you compile a project that contains an object definition that is associated with a Siebel script. The Siebel Compiler and Run-Time Engine do not include a user interface. The compiler compiles the custom code, and then returns a message that indicates success or failure.
Compilation Order
The Siebel Compiler compiles Siebel VB functions and procedures in alphabetical order as they occur in the object definition. If a function or procedure calls another function or procedure that is not defined, then the compiler creates an error message that is similar to the following:
function_name Is An Unknown Function
To avoid this error, you can use the Declare statement to declare the function or procedure in the declarations section of the general section.
Siebel eScript does not require you to declare a function before you use it.
For more information, see Siebel VB Language Reference.
ST eScript Engine
The ST eScript engine is available in Siebel CRM version 7.8 and later. It is the default Siebel eScript scripting engine in Siebel CRM version 8.0 and later. It allows you to use strongly typed objects that are compliant with the ECMAScript edition 4 specification. It also provides early and late binding. For information about:
Binding, see About Early and Late Binding.
The differences that exist between the ST eScript engine and the T engine, see Siebel eScript Language Reference
Using the ST engine, see Using Siebel Tools.
About Early and Late Binding
Early binding occurs if you bind a specific object instance to a variable. The following code binds an object to a variable at design time. It is an example of early binding:
var lo_bo = TheApplication().GetBusObject("Account");
Late binding occurs if you bind an object to a variable only at run time. The following code is an example of late binding:
if (TheApplication().ActiveBusObject().Name() == "Account") var ls_bo_name = TheApplication().ActiveBusObject().Name();
This late binding code does not specify a specific object. The compiler cannot identify this object and it cannot identify that the Name method is part of the object. Siebel CRM can only bind this object to a variable at run time.
Siebel Script Profiler
The Siebel Script Profiler is a tool that gathers and displays data for the scripts that Siebel CRM runs when you start a Siebel application in Debug mode from Siebel Tools. Siebel Tools displays the profiler data in a window that is similar to the Watch window. It automatically updates information in this window while a script runs in the Siebel application.
The Script Profiler includes the following features:
Tree view that displays how the script runs
Allows you to profile functions and profile lines of chosen functions
Allows you to use the Siebel Debugger and Script Profiler at the same time
Allows you to view the compilation time that the script requires to run
You can use this data to do the following work:
Monitor the performance of a script.
Identify performance bottlenecks.
Compare profile data with previous script runs.
You can use the Script Profiler only with the ST eScript Engine.
For more information, see Using Siebel Tools.
Siebel Object Interface Methods That You Can Use to Control Data and Objects
This topic describes object interface methods that you can use to control data and objects. It includes the following topics:
Methods That Locate Objects
This topic describes object interface methods that allow your configuration to locate an active instance of an object that resides in a Siebel application so that another method can use this object:
The active object is an instance of an object that Siebel CRM currently displays as active.
The active control is the control that Siebel CRM currently displays as active.
The active applet is the applet that contains the active control.
The active business component is the business component that the active applet references.
If a Siebel object interface can locate an object, then it can use or manipulate this object.
You can use any of the following object interface methods in your configuration to locate an object:
Methods That Access Data from Business Components
This topic describes the object interface methods that allow your configuration to access and modify data that resides in a Siebel application. A business component can provide data for each field of each business component record, such as the fields of an opportunity. You can use a business component to read data, manipulate data, and then write this data to the Siebel database.
You can use a custom script that you write in Siebel VB or Siebel eScript. For example, if you create a script in Siebel VB or Siebel eScript that references the NewRecord event in a business component, then Siebel CRM calls this script. This situation is true if any of the following items calls the event:
The NewRecord method
Another Siebel VB or Siebel eScript script
A Siebel object interface
An event is available only with Siebel VB or Siebel eScript.
Adding and Inserting Records
You can use Siebel VB or Siebel eScript to mimic one of the following commands in the context of a many-to-many relationship:
Add New Record. Associates a new child record.
Insert Record. Creates a new record in the child business component.
You can use one of the following methods to associate a new child record:
GetAssocBusComp
Associate
You can use one of the following methods to create a new record in the child record:
The NewRecord method in a child business component
The GetMVGBusComp method and the NewRecord method
How Siebel CRM Saves a Record to the Siebel Database
Siebel CRM saves a record to the Siebel database in the following situations:
Explicitly by using the BusComp.WriteRecord method.
Navigating away from the current record by any of the following object interface methods:
BusComp.Associate.
BusComp.DeleteRecord. It moves the cursor to another record, so this method automatically saves the record.
BusComp.FirstRecord.
BusComp.LastRecord.
BusComp.NextRecord.
BusComp.PreviousRecord.
Closing a business component by setting the BusComp method to Nothing.
Example of Accessing Data from an Existing Business Component Instance
If Siebel CRM starts an event, then the code in this example calls an object interface method that resides on an existing business component instance. The term instance describes the current, run-time state of an object. For example, a business component instance is a run-time occurrence of a business component. It includes all of the run-time data that the business component currently contains, such as the values for all business component fields and the values for all properties of this business component. For example, an instance of the Contact business component includes the current, run-time value of the City field that resides in this business component, such as San Francisco. You can configure Siebel CRM to get a business component instance, and then modify this data or call the methods that this business component references.
In the following example, the VB script resides in the SetFieldValue event of the business component:
Sub BusComp_SetFieldValue (FieldName As String)
Dim desc As String
Dim newDesc As String
TheApplication.TraceOn "c:\temp\trace.txt", "Allocation", "All"
If FieldName = "Type" Then
newDesc = "Any valid string that contains the new description."
desc = Me.GetFieldValue("Description")
TheApplication.Trace "The previous description is " & desc
Me.SetFieldValue "Description", newDesc
TheApplication.Trace "The new description is " & newDesc
End If
TheApplication.TraceOff
End Sub
Example of Accessing Data from a New Business Component Instance
The example in this topic describes how to create a new business object instance and a business component instance. It uses the PreSetFieldValue event of the Opportunity business component. If the user updates the Sales Stage to 07 - Verbal Agreement, then Siebel CRM requires the user to associate a decision maker with the opportunity. Otherwise, Siebel CRM resets it to the previous value. To determine if a vice president or president is associated with the opportunity, Siebel CRM searches the contacts that it associates with the opportunity.
The following steps describe the logical flow of object interface methods that Siebel CRM uses to create a new business component instance:
GetBusComp.
SetViewMode. This method is optional. You can use it to modify the default value of the view mode.
ActivateField.
ClearToQuery.
SetSearchSpec or SetSearchExpr.
It is not necessary to activate a field that includes a search specification and a search expression, unless the GetFieldValue method or the SetFieldValue method also references this field.
ExecuteQuery.
Example of Using Siebel VB to Access Data from a New Business Component Instance
The following example uses Siebel VB to access data from a new business component instance:
Function BusComp_PreSetFieldValue (FieldName As String, FieldValue As String) As
Integer
Dim RetValue As Integer
RetValue = ContinueOperation
Select Case FieldName
Case "Sales Stage"
If FieldValue = "08 - Negotiation" Then
' Do not allow the sales cycle to be changed to this value
' if the decision-maker is not a contact for the Oppty.
' Decision-maker defined as anyone with rank VP and above
Dim oBusObj As BusObject
Dim sRowId As String
Dim iViewMode As Integer
sRowId = GetFieldValue("Id")
iViewMode = GetViewMode
Set oBusObj = TheApplication.ActiveBusObject
' Parent-child relationship is established if
' BusComps are instantiated from the same BusObject.
' The ContactBC has all contact records for the
' current Oppty record.
Set ContactBC = oBusObj.GetBusComp("Contact")
With ContactBC
.ClearToQuery
.SetSearchSpec "Job Title", "*VP*"
.ExecuteQuery ForwardBackward
If (.FirstRecord = 1) Then
TheApplication.RaiseErrorText "Found a decision maker"
Else
RetVal = ContinueOperation
End If
End With
Set ContactBC = Nothing
Set oBusObj = Nothing
End If
End Select
BusComp_PreSetFieldValue = RetValue
End Function
Example of Using Siebel eScript to Access Data from a New Business Component Instance
The following example uses Siebel eScript to access data from a new business component instance:
function BusComp_PreSetFieldValue (FieldName, FieldValue)
{
var RetValue = ContinueOperation;
switch (FieldName)
{
case "Sales Stage":
if (FieldValue == "08 - Negotiation")
{
//Do not allow the sales cycle to be changed to this value
//if the decision-maker is not a contact for the Oppty.
//Decision-maker defined as anyone with rank VP and above
var oBusObj;
var sRowId;
var iViewMode;
sRowId = this.GetFieldValue("Id");
iViewMode = this.GetViewMode();
oBusObj = TheApplication().ActiveBusObject();
//Parent-child relationship is established if
//BusComps are instantiated from the same BusObject.
//The ContactBC has all contact records for the
//current Oppty record.
ContactBC = oBusObj.GetBusComp("Contact");
with (ContactBC)
{
ClearToQuery();
SetSearchSpec("Job Title", "*VP*");
ExecuteQuery(ForwardBackward);
if (FirstRecord())
{
TheApplication().RaiseErrorText("Found a decision maker");
}
else
{
RetVal = ContinueOperation;
}
}
ContactBC = null;
oBusObj = null;
}
break;
}
return(RetVal);
}
Methods That Get Data From Business Components
The following object interface methods get data from a business component:
Methods That Get and Display Information About the Current State
The following object interface methods allow your configuration to use the application object to get information about the current state of properties and functions. This information is useful if your configuration must process rows of data or create query criteria:
Methods That Control Debug Tracing
The following object interface methods allow your configuration to control debug tracing: