4Business Services
Business Services
This chapter outlines the basic concepts of a business service, its structure and purpose, and how you can customize and create your own business service. This chapter also describes how to test your business service before it is implemented. The following topics are included:
About Business Services
A business service is an object that encapsulates and simplifies the use of some set of functionality. Business components and business objects are objects that are typically tied to specific data and tables in the Siebel data model. Business services, on the other hand, are not tied to specific objects, but rather operate or act upon objects to achieve a particular goal.
Business services can simplify the task of moving data and converting data formats between the Siebel application and external applications. Business services can also be used outside the context of Siebel EAI to accomplish other types of tasks, such as performing a standard tax calculation, a shipping rate calculation, or other specialized functions.
The business service can be assessed either directly by way of workflows (business processes) or by way of a scripting service written in Siebel VB or Siebel eScript.
The following topics are also covered:
About Creating Business Services
A Siebel application provides a number of prebuilt business services to assist you with your integration tasks. These services are based on specialized classes and are called Specialized Business Services. Many of these are used internally to manage a variety of tasks.
In addition to the prebuilt business services, you can build your own business service and its functionality in two different ways to suit your business requirements:
In Siebel Tools. Created at design time in Siebel Tools using Siebel VB or Siebel eScript. Design-time business services are stored in the Siebel design time repository, so you have to compile the repository before testing them. When your test is completed, deliver the changes. The business services stored in the repository automatically come over to the new repository during the upgrade process. General business services are based on the class CSSService. However, for the purposes of Siebel EAI, you base your data transformation business services on the CSSEAIDTEScriptService class. For information, see Creating Business Services in Siebel Tools.
In Siebel client. Created at run time in the Siebel client using the Business Service Administration screens. Run-time business services are stored in the Siebel run-time database, so they can be tested right away. The run-time business services have to be migrated manually after an upgrade process. For information, see Creating Business Services in Siebel Business Applications.
Business Service Structure
Business services allow developers to encapsulate business logic in a central location, abstracting the logic from the data it might act upon. A business service is much like an object in an object-oriented programming language.
A business service has properties and methods, and maintains a state. Methods take arguments that can be passed into the object programmatically or, in the case of Siebel EAI, declaratively by way of workflows.
Property Sets
Property sets are used internally to represent Siebel EAI data. A property set is a logical memory structure that is used to pass the data between business services. The following figure illustrates the concept of a property set.
The property set consists of four parts:
Type. Used to describe what type of object is being represented.
Value. Used to hold serialized data, such as a string of XML data.
Note: In Siebel Tools, a Value argument to a method is shown with the name of <Value> , including the angle brackets. You can also define a Display Name for the Value argument in Siebel Tools. This Display Name appears in the Siebel Business Process Designer when you are building integration workflows. In this guide, the Display Name Message Text is shown when referring to the Value argument, and the Name <Value> is shown when referring to the Value of the Value argument.Properties. A table containing name-value pairs. You can use the properties to represent column names and data, field names and data, or other types of name-value pairs.
Children. An array of child-level property sets. You can use the array to represent instances of integration objects. For example, a result set might contain an Account with some set of contact records from the database. Each contact record is represented as a child property set.
It is recommended that you treat input property sets in business services as constants. If you must modify the inputs, then make a copy first. Otherwise, there might be interference between business service scripts and workflows that also modify the inputs, leading to unpredictable application behavior.
For example, when creating the XMLHierarchy property set using a custom business service in a workflow, if the input property set is modified without making a copy, then the following error occurs:
Argument 'XMLHierarchy' in step 'Convert XMLHierarchy' is not correctly initialized or does not return valid data.(SBL-BPR-00107)
Creating Business Services in Siebel Tools
The following procedures explain how to create business services and business service scripts in Siebel Tools:
.
Defining a Business Service in Siebel Tools
You declaratively define the business service in Siebel Tools, and then add your scripts to the business service in the Siebel Script Editor within Siebel Tools.
To define a business service in Siebel Tools
In Siebel Tools, select and lock the project with which you want to associate your business service.
Note: Each business service must belong to a project, and the project must be locked. For more information, see Using Siebel Tools.Select the Business Services object in the Tools Object Explorer.
The list of predefined business services appears in the farthest panel.
Right-click, and then choose New Record.
Type a name in the Name field of the new business service.
From the pull-down menu in the Project field, pick the project you locked in Step 1.
Choose the appropriate class for your business service from the Class picklist:
Data transformation business services must use the CSSEAIDTEScriptService class.
Other business services will typically use the CSSService class.
Step off the current record to save your changes.
Defining Business Service Methods
Business services contain related methods that provide the ability to perform a particular task or set of tasks.
To define a business service method
With your business service selected in Siebel Tools, expand the Business Service tree in the Object Explorer, and then select Business Service Method.
The Business Service Methods list appears in the Object List Editor. If you have already defined methods for the selected business service, they appear in the Business Services Methods list.
Right-click, and then choose New Record.
Type the name of the method in the Name field of the new method.
Defining Business Service Method Arguments
Each method can take one or more arguments. The argument is passed to the method and consists of some data or object that the method processes to complete its task.
To define business service method arguments
With your business service method selected in Siebel Tools, expand the Business Service Method tree in the Object Explorer, and then select Business Service Method Args.
The Business Service Methods Args list appears in the Object List Editor.
Right-click, and then choose New Record.
Type the name of the argument in the Name field of the new method argument record.
Note: If you plan to use this business service in a Siebel Business Application, then specify the Display Name as well.Enter the data type in the Data Type field.
Check the Optional check box if you do not want the argument to be required for the method.
Choose a Type for the argument. Refer to the following table for a list of different types and their descriptions.
Argument Description Input
This type of argument serves as input to the method.
Input/Output
This type of argument serves as both input to the method and output from the method.
Output
This type of argument serves as output from the method.
Writing Business Service Scripts
Business service scripts supply the actual functionality of the business service in either Siebel VB or Siebel eScript. As with any object, the script you provide is attached to the business service.
To write business service scripts
In Siebel Tools, select the business service for which you want to write a script.
Right-click, and then choose Edit Server Scripts.
The Siebel Script Editor appears.
Select either Siebel eScript or Visual Basic for your scripting language.
Select Service_PreInvokedMethod as the event handler.
Note: To write any Siebel VB script in the Business Services, the operating system you are using must support Siebel VB. Siebel VB is not supported in the UNIX environments.Type your script into the Script Editor.
Note: Write your business service in Siebel eScript if you want to use the DTE scripts. For information on scripting, see Using Siebel Tools.
Defining Business Service User Properties
User properties are optional variables that you can use to define default values for your business services in Siebel Tools. When a script or control calls your business service, one of the first tasks the service performs is to check the user properties to gather any default values that will become input arguments to the service’s methods.
To define business service user properties
With your business service selected in Siebel Tools, expand the Business Service tree in the Object Explorer, and then select Business Service User Prop.
The Business Service User Props list appears in the Object List Editor.
Right-click, then choose New Record.
Type the name of the user property in the Name field of the new record.
Type a value in the Value field.
The value can be an integer, a string, or a Boolean.
Creating Business Services in Siebel Business Applications
You can define business services in Siebel Business Applications using the Business Service Administration screens. The business services you create in the client are stored in the Siebel Database. This topic illustrates the creation of business services using the Business Service Methods view, which includes applets to create and display the business service.
To define a business service in the Siebel application
Navigate to the Administration - Business Service screen, Methods view.
Click New to create a new record in the Methods form applet:
Name. Name of the business service.
Cache. If checked then the business service instance remains in existence until the user’s session is finished; otherwise, the business service instance will be deleted after it finishes executing.
Inactive. Check if you do not want to use the business service.
Define methods for the business service in the Methods list applet:
Name. Name of the method.
Inactive. Check if you do not want to use the method.
Define method arguments for the methods in the Method Arguments list applet:
Name. Name of the method argument.
Type. The type of the business service method argument. Valid values are Output, Input, and Input/Output.
Optional. Check if you do not want this argument to be optional.
Inactive. Check if you do not want to use the argument.
From the link bar, select Scripts.
Write your Siebel eScript or VB code in the Business Service Scripts list applet.
Note: To write any Siebel VB script in the Business Services, the operating system you are using must support Siebel VB. Siebel VB is not supported in UNIX environments.Click Check Syntax to check the syntax of the business service script.
Deploying Business Services as Web Services
You can deploy business services, which you have created in Siebel Tools, as Web services. The Web services can then be consumed by other applications.
To be deployed, a business service must have at least one accessible method that is supported in Siebel inbound Web services. The business service must include a valid integration object name for any hierarchical argument.
For more information on Web services, see Web Services.
To deploy a business service as a Web service
In the Object Explorer in Siebel Tools, select the Business Service object.
The Business Services list appears.
In the Object List Editor, right-click the business service to deploy, and then choose Deploy as Web Service.
The Expose Business Service as Web Service dialog box appears.
Specify the following in the dialog box, and then click Finish:
Business service methods to expose. The operation names for the business service methods are system generated. To edit an operation name, click it in the list.
URL for the Web service. Replace
<webserver>with a valid host name and<lang>with a valid language code, such asenu.Generate WSDL check box. To generate a Web Services Description Language (WSDL) file, select the check box, and then choose a location to save the WSDL file.
The business service is deployed. Deployed business services are shown in the Administration - Business Services screen in the Siebel client. Deployed Web services are shown in the Administration - Web Services screen, Inbound Web Services view.
You can also remove (undeploy) deployed business services from the Siebel run-time database.
To undeploy a business service
In the Siebel client, navigate to the Administration - Business Services screen.
The Details list appears.
Query for the deployed business service, and then select it.
Click Delete.
The business service is undeployed.
Exporting and Importing Business Services in Siebel Tools
You can export business services into an XML file by clicking Export in the Business Services list in the Object List Editor. This writes the definition of the business service, including every method, method argument, and script, into the XML file.
You can import a business service from an external XML file by clicking Import in the Business Services list in the Object List Editor.
Importing Business Services into Siebel Business Applications
You can import business services, which you have created in Siebel Tools and exported as XML files, into the Siebel run-time database. This saves time by allowing you to modify business service definitions without having to shut down your production environment, edit the business services in workspace of Siebel Tools or Web Tools, and then deliver the workspace.
To import a business service into Siebel Business Applications
Navigate to the Administration - Business Service screen, Details view.
From the Menu pull-down, choose Import Service.
The Business Service Import dialog appears.
Browse for a business service XML file, and then click Import.
Testing Your Business Service in the Simulator
You can use the Business Service Simulator to test your business services in an interactive mode.
To run the Business Service Simulator
Navigate to the Administration - Business Service screen, Simulator view.
Note: The contents of the Simulator view are not persistent. To save the data entered in the applets, click the Save To File button. This will save the data for the active applet in an XML file. The data can then be loaded into the next session from an XML file by clicking on the Load From File button.In the Simulator list applet, click New to add the business service you want to test.
Specify the Service Name and the Method Name.
Enter the number of iterations you want to run the business service:
Specify the input parameters for the Business Service Method in the Input Property Set applet. Multiple input property sets can be defined and are identified by specifying a Test Case #.
If the Input Property Set has multiple properties, then these can be specified by clicking on the glyph in the Property Name field. Hierarchical property sets can also be defined by clicking on the glyph in the Child Type field.
Click Run to run the business service.
The Simulator runs the specified number of iterations and loops through the test cases in order. If you have defined multiple input arguments, then you can choose to run only one argument at a time by clicking Run On One Input.
The result appears in the Output Property Set applet.
Note: When the Output arguments are created, you can click Move To Input to test the outputs as inputs to another method.
About Accessing a Business Service Using Siebel eScript or Siebel VB
In addition to accessing a business service through a workflow, you can use Siebel VB or eScript to call a business service. The following Siebel eScript code calls the business service EAI XML Read from File to read an XML file, and produces a property set as an output. The EAI Siebel Adapter uses the output property set to insert a new account into the Siebel application:
var svcReadFile = TheApplication().GetService("EAI XML Read from File") ;
var svcSaveData = TheApplication().GetService("EAI Siebel Adapter");
var child = TheApplication().NewPropertySet();
var psInputs = TheApplication().NewPropertySet();
var psOutputs = TheApplication().NewPropertySet();
var psOutputs2 = TheApplication().NewPropertySet();
var svcSaveData = TheApplication().GetService("EAI Siebel Adapter");
psInputs.SetProperty("FileName", "c:\\NewAccount.xml");
psOutputs.SetType "SiebelMessage";
psOutputs.SetProperty "IntObjectName","Sample Account";
psOutputs.SetProperty "MessageId", "";
psOutputs.SetProperty "MessageType", "Integration Object";
svcReadFile.InvokeMethod("ReadEAIMsg",psInputs, psOutputs);
svcSaveData.InvokeMethod("Upsert",psOutputs,psOutputs2);
The following Siebel VB sample code shows how to call the EAI File Transport business service to read an XML file. It also shows how to use the XML Converter business service to produce a property set:
Set Inp = TheApplication.NewPropertySet
Inp.SetProperty "FileName", "c:\test.xml"
Inp.SetProperty "DispatchService", "XML Converter"
Inp.SetProperty "DispatchMethod" , "XMLToPropSet"
Set svc = theApplication.GetService("EAI File Transport")
Set XMLOutputs = theApplication.NewPropertySet
svc.InvokeMethod "ReceiveDispatch", Inp, XMLOutputs
TheApplication.RaiseErrorText Cstr(XMLOutputs.GetChildCount)
Business Scenario for the Use of Business Services
Consider an example of a form on a corporate Web site. Many visitors during the day enter their personal data into the fields on the Web form. The field names represent arguments, whereas the personal data represent data. When the visitor clicks Submit on the form, the form’s CGI script formats and sends the data by way of the HTTP transport protocol to the corporate Web server. The CGI script can be written in JavaScript, Perl, or another scripting language.
The CGI script might have extracted the field names and created XML elements from them to resemble the following XML tags:
First Name = <FirstName></FirstName> Last Name = <LastName></LastName>
The CGI script might then have wrapped each data item inside the XML tags:
<FirstName>Hector</FirstName> <LastName>Alacon</LastName>
To insert the preceding data into the Siebel Database as a Contact, your script calls a business service that formats the XML input into a property set structure that the Siebel application recognizes.
Code Sample Example for Creating a Property Set
The following is an example of the Siebel eScript code that you must write to create the property set:
x = TheApplication.InvokeMethod("WebForm", inputs, outputs);
var svc; // variable to contain the handle to the Service
var inputs; // variable to contain the XML input
var outputs; // variable to contain the output property set
svc = TheApplication().GetService("EAI XML Read from File");
inputs = TheApplication().ReadEAIMsg("webform.xml");
outputs = TheApplication().NewPropertySet();
svc.InvokeMethod("Read XML Hierarchy", inputs, outputs);
The following functions could be called from the preceding code. You attach the function to a business service in Siebel Tools:
Function Service_PreInvokeMethod(MethodName, inputs, outputs)
{
if (MethodName=="GetWebContact")
{
fname = inputs.GetProperty("<First Name>");
lname = inputs.GetProperty("<Last Name>");
outputs.SetProperty("First Name",fname);
outputs.SetProperty("Last Name", lname);
return(CancelOperation);
}
return(ContinueOperation);
}
Function Service_PreCanInvokeMethod(MethodName, CanInvoke)
{
if (MethodName="GetWebContact")
{
CanInvoke ="TRUE";
return (CancelOperation);
}
else
{
return (ContinueOperation);
}
}