Technical Note 515: Siebel Configurator Instance API

Last Modified: Area(s): Release(s): Database(s): App Server OS(s): Latest release tested against: Keywords: 31 March 2004 eConfigurator / Siebel Product Configurator V7 (Enterprise) All Supported Databases All Supported Platforms V7 (Enterprise) Configurator, API

Background API methods are a set of well-defined and exposed methods that provide the ability to use the eConfigurator and manipulate or validate a configuration session without using the customizable runtime UI (CPRUI). They are methods of the business service Complex Object Instance Service and Remote Complex Object Instance Service and are used extensively by other services (Configurator UI services) within the Siebel application. They can be accessed by external applications or via script Note that these methods should not be used as a substitute for the CPRUI as it provides considerable out of the box functionality that permits significant changes to the UI with minimal administrative work. Disregarding the CPRUI would not be taking advantage of a significant portion of the value of the Siebel Configurator. Summary This document contains general information regarding API concepts and provides a .zip file that includes examples of how to use the API methods available to the Siebel eConfigurator versions 7.5.x. The examples are in the form of workflows that can be run within a standard Siebel environment and will demonstrate the manner in which the API can be used to accomplish some common business processes. It will also describe how to implement script within API-related business services to determine the API methods that are being called and the arguments that are being passed to them while invoking the eConfigurator. Such sniffers can be used as educational tools to gain further understanding of eConfigurator APIs and how they work. This technical note is intended only as an introduction to APIs for advanced users and assumes knowledge of the eConfigurator and Siebel server architecture. Implementing an API solution also requires proficiency in the following areas: Siebel Business Process Designer Runtime Events (personalization) if invoked from the UI Siebel Object Interfaces A Siebel scripting language (Siebel VB or Siebel eScript) Recursive programming techniques Constraint satisfaction theory Underlying behavior of the Siebel eConfigurator Siebel product definition data model Siebel Property Set representation of data (creation and transformation) EAI Transports and Interfaces

The above list requires underlying fundamental knowledge beyond what is available in the Siebel Bookshelf. Therefore, it is strongly encouraged that you consult with the Customer Order
page 1 of 9

Technical Note 515: Siebel Configurator Instance API

Management (C-OM) competency group, Expert Services, or Professional Services in order to assist with any API implementations. Note that this document does not provide extensive information about any single API (refer to the Product Administration guide in Siebel Bookshelf version 7.5 for information about each API specifically), nor does it discuss detailed criteria under which one API might be chosen in preference for another or what collection of APIs might be appropriate for a given business process. A consultant from the Siebel C-OM competency group, Expert Services, or Professional Services can assist you in deciding what the best approach would be to meet your business requirements. API Usage Scenarios There are two types of scenarios that the eConfigurator Instance API are typically used for: Batch Validation This is the process of verifying that a previously created instance of a product is still valid without viewing the customizable product runtime user interface. Batch validation can be useful when doing the following: Automating the process of validating large volumes of orders Reconciling customer Assets with the new product definition Automating updates to customer Assets to ensure their validity Ensuring the validity of repeat orders Ensuring that orders from external systems are validated or embellished in real time Ensuring that active Quotes and Orders are still valid

The examples in this technical note focus heavily on this functionality and were created as an underlying validation engine with various business processes on top of it, so that implementation would be fairly quick and painless. This generally represents a significant increase in business value for relatively low risk and implementation time and money. Also, if done within an external system, it needs to have only a cursory knowledge of Siebel eConfigurator in terms of the XML structure eventually required. Headless Configuration This is the process of interacting with the eConfigurator through its API for the purpose of manipulating an instance of a customizable product. In this approach, the external system interacts directly and deeply with the configurator and is therefore much more complex, time consuming, and expensive. The programming skill requirements are much higher and an understanding of how the configuration engine works is required. The API Demo #1 - Batch Quote Creation and Manipulation example included in the .zip file attached later on in this document demonstrates the general idea of this functionality at a very minor level. Groups of Available API There are 3 main groups of APIs for accessing the eConfigurator. These APIs are supported by the Complex Object Instance Service. Group 1: UI Customizable product runtime user interface (CPRUI) accesses the instance API to paint the Configurator UI. DOM API within the browser inherent in JavaScript and HTML Group 2: Model

page 2 of 9

Technical Note 515: Siebel Configurator Instance API

Scripts that execute in the context of the current session that are implemented as part of the configuration model in the Complex Product Script Designer View

Group 3: Instance API for using the eConfigurator or manipulating the configuration session from somewhere other than the CPRUI The Remote Complex Object Instance Service - this business service is available for accessing the Instance APIs and is described later in this document. This technical note focuses on the APIs that fall under Group 3. The diagram below illustrates where the different APIs act within the architecture of the Configurator.

Binary File

UI Business Service (application) UI Business Service (application)

UI

Object Object Broker Broker

Customizable Product Structure

Instance
Instance Instance Broker Broker

Complex Complex Product Product Structure Structure

Pricing Pricing Quote, Quote, Order, Order, Etc. Etc.

UI UI Frame Frame

Siebel Siebel Web Web Engine Engine

Current Selection

EAI EAI
Script Script

Model
ONLY when required

Config Config Services Services

Constraint Constraint Engine Engine

During normal configurator operation, the UI business service calls the Instance Broker for all configuration functionality. Because these can exist as separate object managers on separate physical servers, a clean business service API was created. The Instance APIs listed below are exactly the same APIs that are used by the UI service during normal configurator operation. The difference is that it will now be a custom process, rather than the UI service, that is manipulating the Instance Broker. Also, the UI Business Service, Instance Broker, and Pricing objects shown above are all business services. Their names in Siebel Tools are Cfg Web UI Service, Complex Object Instance Service (or Remote Complex Object Instance Service), and Pricing Manager. Complex Object Instance Services There are two complex object instance services declared in Siebel Tools that contain the eConfigurator APIs that are used to invoke the eConfigurator and manipulate its session. The Complex Object Instance Service (COIS) is used when the configuration is done within the same object manager as the Siebel application. The Remote Complex Object Instance Service (RCOIS) is used when the configuration is done on a separate physical server, using the
page 3 of 9

Technical Note 515: Siebel Configurator Instance API

Configuration Object Manager to handle the remote calls. The RCOIS does not execute the configurator logic. The purpose for the RCOIS is to accept a request and determine which server should process the request. This could either be the local server where RCOIS is running, in the case of a non-dedicated configuration server environment, or one of a pool of dedicated configurator servers. When using configurator APIs within scripts or workflows with the intent of enhancing the behavior of an interactive configuration session, you can either use the COIS or RCOIS. While the best practice is to always call RCOIS from workflows or scripts in order to be able to re-use them if a decision is made to move to a dedicated configuration setup, there are considerations that should guide a user to use one service or the other. For instance, in a dedicated configurator server environment, where the scripts are written will determine where the script is executed. Scripts written against COIS will run on the dedicated configuration server. Scripts written against RCOIS will run on the application server (object manager server). When calling the COIS directly within a workflow, the request will be processed by the COIS on the server running the workflow, even in a dedicated configuration server environment. This is because RCOIS was not called; it is this service that controls the passing of configuration API request to the dedicated configurator servers. This is only appropriate where the user wants the request from the workflow to go to the COIS on the same server as where the workflow is running. In an environment without dedicated configuration servers, any calls to RCOIS would also result in the request being processed by the COIS service on the same server as the workflow. Calling RCOIS within a dedicated configuration server environment would result in the request being processed by the COIS on the server the RCOIS determines should execute it. Note that a consultant from the Siebel C-OM competency group, Expert Services, or Professional Services can assist you in deciding what the best approach would be for your environment. APIs Supported by the Complex Object Instance Service Refer to Siebel Bookshelf version 7.5 > Product Administration guide > Technical Reference > eConfigurator API section for further details about each API. APIs to Load and Unload Instances LoadInstance CreateSession SetInstance SyncInstance UnloadInstance

APIs to Get Product Information The APIs in this list do not require a complex object instance to be loaded in order to work. They refer to the product definition and supplied property set information only. DeltaQuote GetAllPorts

APIs to Get Instance State Information EnumObjects GetAttribute GetFieldValues GetInstance GetParents GetPossibleDomain
page 4 of 9

Technical Note 515: Siebel Configurator Instance API

GetPossibleValues GetProductId GetRootPath HasGenerics

APIs to Interact with Conflicts and Messages These APIs only apply to customizable products with constraint rules. GetDetailedReqExpl GetExplanations GetSignals RemoveFailedRequests UndoLastRequest

API to Manipulate an Instance AddItem RemoveItem RepriceInstance SetAttribute SetItemQuantity CopyInstance ReplaceItem

Educational Tools This section discusses ways to develop systems that use the eConfigurator APIs while following good development practices. The best practice to follow when automating an existing business process is typically: Go through the process manually through the UI, making a note of every step that is taken. Record all underlying methods that were necessary for this process and their arguments. Determine which portions of the process are fixed and which must be flexible. Automate the process.

This practice is no different when automating configuration processes. The steps below detail how to tell what API are used with what arguments when performing a configuration process through the customizable product runtime user interface. Although the APIs are listed in the Product Administration Guide of the Bookshelf, this is the most effective way to determine specifically which APIs are appropriate for your business problem. The process described below also provides a live, interactive example of the API in action. As you make a change in the configurator UI, you can watch what methods get invoked and what arguments get passed in order to carry out the change, and then get the information required to re-draw the UI. Implement API Sniffers This section discusses how to implement script within business services to determine what methods are being invoked and what arguments are being passed. The example below is for the Complex Object Instance Service, and writes a log file to the /log directory. It is recommended that different log files for inputs and outputs be used for each service. For the four services mentioned below, this results in eight log files.

page 5 of 9

Technical Note 515: Siebel Configurator Instance API

1. Locate the business service in Siebel Tools. 2. Right-click and choose Edit Server Scripts. Choose eScript, as the examples below are written in this programming language. 3. Select the Service_PreInvokeMethod event on the explorer. Paste in the following script so that it completely replaces what is currently there. Alter log file name and descriptive note as appropriate. function Service_PreInvokeMethod (MethodName, Inputs, Outputs) { PropertySetToFile(Inputs, "..\\LOG\\CXServiceInputs.log", ("Inputs to: " + MethodName)); return (ContinueOperation); } function PropertySetToFile (PropSet, fileName, title) { try { var file = Clib.fopen(fileName, "at"); LogData(("\n--------------------------------------------------"), file); LogData(("Start Process " + Clib.asctime(Clib.gmtime(Clib.time()))), file); LogData(title, file); LogData("PROVIDED PROPERTY SET", file); WritePropertySet(PropSet, file, 0); Clib.fclose(file); return (CancelOperation); } catch (e) { // fail silently }

function WritePropertySet(PropSet, file, Level) { if ((Level == "") || (typeof(Level) == "undefined")){ Level = 0; } var indent = ""; for (var x = 0; x < Level; x++){ indent += "\t"; } try {

var psType = PropSet.GetType(); var psValue = PropSet.GetValue(); LogData((indent + "Type: " + psType + " Value: " + psValue), file); }
page 6 of 9

Technical Note 515: Siebel Configurator Instance API

catch (e) { LogData((indent + "BAD DATA IN PROPERTY HEADER")); } var propName = PropSet.GetFirstProperty(); while (propName != "") { try { var propValue = PropSet.GetProperty(propName); } catch (e) { LogData((indent + "BAD DATA IN PROPERTY DATA")); } LogData((indent + propName + " = " + propValue), file); propName = PropSet.GetNextProperty(); } var children = PropSet.GetChildCount(); for (var x = 0; x < children; x++) { LogData(( indent + "CHILD PROPERTY SET " + x), file); WritePropertySet(PropSet.GetChild(x), file, (Level + 1)); }

function LogData(DataString, file) { try { Clib.fputs((DataString + "\n"), file); Clib.fflush(file); } catch (e){ // no action } } 4. Select the Service_InvokeMethod event on the explorer. Paste in the following script so that it completely replaces what is currently there. Alter the log file name and descriptive note as appropriate. function Service_InvokeMethod (MethodName, Inputs, Outputs) { PropertySetToFile(Outputs, "..\\LOG\\CXServiceOutputs.log", ("Outputs from: " + MethodName)); } 5. Repeat steps 1 through 4 for each of the following business services: Remote Complex Object Instance Service Pricing Manager EAI Siebel Adapter

6. Compile locked projects or each business service that was modified.

page 7 of 9

Technical Note 515: Siebel Configurator Instance API

This will write a log file with a hierarchal view of the input and output property sets. If you prefer a different format, modify the script appropriately. NOTE: This technique is appropriate only in a design, development, or testing environment. Creating these files has a material performance impact and should never be used in a production environment. Use the Siebel Application to Perform Manual Steps Complete the following steps to perform the process you wish to automate manually through the UI: 1. In the Siebel application, create a quote, order, or asset. 2. Add a customizable product you will be working with. 3. Customize the product. 4. Make the changes you wish to automate. 5. Exit the application. Examine the Result 1. Open the log files created by the script at the business service events. 2. Note the methods invoked and the arguments passed. 3. Repeat as necessary to understand what is going on sufficiently to automate it. Hints Copy sections of the log files and keep them with notes about specific events to make it easier to de-construct the process. Separate the underlying process from the API calls necessary to support the UI by creating a UI that has as few items on a visible page as practical. Use a text editor that does not lock the file for writing when it opens a text file to view these log files.

Explanation of the Instance API This section presents some general concepts. The Complex Object Instance Service and the Remote Complex Object Instance Service are business services. They can be accessed by anything in the Siebel architecture that can use a business service. As a business service, they are used by invoking methods, passing in property sets with input arguments, and getting results from the Outputs property set. A session is uniquely identified by two ID values - the Object Id and the Root Id. In the case of a quote, the Object Id is the Quote Id, and the Root Id is the Quote Item Id for the top-level parent (the root). In assets, the Object Id and the Root Id are both the root Asset Id. A session is unique only within its own user session on a given object manager.
page 8 of 9

Technical Note 515: Siebel Configurator Instance API

A port is another name for a Relationship. A complex product is another name for a customizable product. The Port Id is the ID of the relationship as defined in the Complex Product Structure BusComp. The Prod Item Id is the ID of the relationship item as defined in the Complex Product Structure BusComp. The Path for an item is the Integration ID of the specific item. Version arguments are used only when testing a customizable product version that is different from the currently released version.

API Demos The example workflows detailed in the following .zip files help illustrate what the configurator instance API can be used for and are designed to be used for educational purposes. If you are using a Siebel HOR application, download the technote515-1_APIDemos_75HOR.zip file. If you are using a Siebel SIA application, download the technote515-2_APIDemos_75SIA.zip file. Within this .zip file, reference the eConfigurator API Demo Instructions for 7.5.x HOR.doc or eConfigurator API Demo Instructions for 7.5.x SIA.doc document for further instructions on how to run each of the six examples. technote515-1_APIDemos_75HOR.zip technote515-2_APIDemos_75SIA.zip

page 9 of 9