Product Administration Guide > Technical Reference >

eConfigurator API


This section is intended to summarize the available API to the Siebel eConfigurator, version 7.0.x. It explores in some detail a segment of those API.

This is intended as an introduction to the topic for advanced users. This section assumes knowledge of the eConfigurator and Siebel server architecture. Implementing the API described in this section also requires proficiency in Siebel EAI and Siebel Object Interfaces.

In order to use these API, the user should be familiar with the following:

Available API

There are three main groups of API for accessing the eConfigurator. These API are supported by the Complex Object Instance Service.

Explanation of the Instance API

This section presents general concepts:

NOTE:  The parameters are property set and, unless indicated, all properties are on the root level property set.

LoadInstance

Loads the complex object in memory. This is the starting point for all configurations.

In:

Out:

The following properties will be returned from the output property set:

<UnresolvedLinks>"

<UnresolvedLink DispName='Quote Name' Definition='<CfgVariableDef BUS_OBJ = ""Quote"" BUS_COMP = ""Quote"" FIELD_NAME = ""Name"" SEARCH_SPEC = """" SORT_SPEC = """" DEFAULT_VAL = """" EXECUTE = ""N""/>' Description='' DefValue='' Name='Quote Name' BusObj='Quote' Field='Name' ID='1-1Z875' BusComp='Quote'>

</UnresolvedLink>

</UnresolvedLinks>

</>

Extracting the instance property set from LoadInstance. The instance property set can be extracted by first getting the child property set of type "CxObj" and then extracting its only child.

Links and what to do with them: A child property set of type Links will be returned if the model has linked items. The Links child property set must then be extracted and passed in to CreateSession's OUTPUT arguments as a child property set. In 7.0.4 this changed to the INPUT property set for CreateSession. It is possible that configuration rules have been defined for these linked items and so the configuration session must know the link values. The linked items are represented as property-value pairs with link IDs as properties and link values as property values.

For example:

<Links 1-19D0X='10/19/2001' 1-1Z876='SADMIN' 1-1Z771='SADMIN'>

A child property set of type UnresolvedLinks will be returned if the model has linked items which the business service was unable to resolve. The children of this property contain the information necessary to calculate the value of the linked item.

<UnresolvedLinks>"

<UnresolvedLink DispName='Quote Name' Definition='<CfgVariableDef BUS_OBJ = ""Quote"" BUS_COMP = ""Quote"" FIELD_NAME = ""Name"" SEARCH_SPEC = """" SORT_SPEC = """" DEFAULT_VAL = """" EXECUTE = ""N""/>' Description='' DefValue='' Name='Quote Name' BusObj='Quote' Field='Name' ID='1-1Z875' BusComp='Quote'>

</UnresolvedLink>

</UnresolvedLinks>

Only links that have the execute flag set or pull system parameters such as TODAY will be resolved by the configurator when used headless. All other links must be resolved by the programmer.

NOTE:  The unresolved links must be calculated and their IDs and values must be added to the Links child property set as properties with the link ID as the property and the link value as the property value.

CreateSession

Initializes a configuration session. This is necessary for customizable products that have constraint rules. This is called immediately following LoadInstance where required.

In:

Out:

If NewRecord is set to "Y" in the input property set the output will have the instance property set returned as a child of type CxObj. This is essentially the same output as what is returned from GetInstance.

SetInstance

Creates a configuration session with a supplied property set. This permits configuration without directly writing to the database. The structure of the input property set does not need to correspond to a Siebel object, such as a quote as indicated by the integration object specified.

In:

Same as LoadInstance but also requires the property set indicating the state to load. This property set must have the SiebelMessage object as the only first level child.

Out:

Same as LoadInstance.

SyncInstance

Saves the complex object instance from whence it came.

In:

Out:

None

UnloadInstance

Removes the existing configuration session from memory. Should be called after synchronizing the instance at the end of the configuration session.

In:

Out:

None

GetAllPorts

Retrieves a list of all ports and possibly their contents for a product. This gets all ports for a product but does not drill down to the ports of the child products. This retrieves the basic definition of the product and does not consider any current configuration session state so every possible port will be retrieved.

In:

Out:

All ports are returned as children of the output property set of type Port.

<Output>

<Port>

Port Information here

</Port>

</Output>

EnumObjects

Returns either all immediate objects under an object or all immediate objects under a specified port. This gets the items that are currently in the port, not the items that could be there.

In:

Out:

Child item information is returned as child property sets as follows:

<Output>

< Name="value" Product Id="value" Path="value" Sequence Number="value" />

...

</Output>

GetAttribute

Retrieves the value of an attribute.

In:

Out:

The value is returned as a property of the output property set.

<Output Value="value">

</Output>

GetFieldValues

Retrieves field values for a product that exists in the complex product.

In:

Out:

The output property set returned will have the field names as properties:

< Field="value" Field="value" ... Field="value"/>

GetInstance

Gets the loaded instance as a property set. This returns the full structure of products and attributes.

In:

Out:

The entire property set output is the complex object instance.

GetParents

Retrieves all the parents of an item.

In:

Out:

The property set returned will have child property sets, each with the following properties:

< >

< Product Id="value" Name="value" Sequence Number="value" Path="value"/>

...

</ >

GetPossibleDomain

Retrieves selectable items from the configuration engine for a port

In:

Out:

The property set returned will have the possible domain item product ids as properties, each with the value 0:

< ProdId1="0" ProdId2="0" ... ProdIdn="0" />

GetPossibleValues

Retrieves selectable values from the configuration engine for an attribute.

In:

Out:

The property set returned will have the possible values as the property names.

< [PossibleValue1]="Val1" [PossibleValue2]="Val2"/>

GetProductId

Gets the root Product ID of the complex object instance.

In:

Out:

The product id is returned as a property of the output property set:

< Product Id="value" />

GetRootPath

Returns the path of the complex object instance root.

In:

Out:

The root path is returned as a property of the output property set:

< Path="value" />

HasGenerics

Returns generics and children flags for an item. A port has generics if the required cardinality is greater than the current cardinality and no default product is specified.

In:

Out:

HasGenerics - Y if it does, not present if it does not.

HasChildren - Y if it does, not present if it does not.

API to Interact with Conflicts and Messages

NOTE:  The API in this section only apply to customizable products with constraint rules.

GetDetailedReqExpl

Retrieves conflict messages.

In:

Out:

Expl# - The explanations for the conflicts. Substitute a number for #, such as Expl0, Expl1, etc.

GetExplanations

Retrieves configuration explanations for an item.

In:

Out:

The property set returned will have child property sets, each with the property Value as the explanation:

<Output>

<Expl Value="Explanation"/>

<Expl Value="Explanation"/>

...

<Expl Value="Explanation"/>

</Output>

GetSignals

Retrieves configuration engine signals.

In:

Out:

The property set returned will have child property sets as follows:

< >

<Signal Expl="signal"/>

<Signal Expl="signal"/>

...

<Signal Expl="signal"/>

</ >

RemoveFailedRequests

Removes all failed requests sent to the configuration engine.

In:

Out:

None

UndoLastRequest

Removes the last request sent to the configuration engine.

In:

Out:

None

API to Set Product and Attribute Values

This section contains API used for setting product and attribute values.

AddItem

Adds an item to a specified port. This will create a new instance of an item. If you want to change the quantity of an existing instance of an item, use SetItemQuantity.

In:

Out:

None.

CopyInstance

Copies an instance.

In:

Out:

None.

RemoveItem

Removes an item from the instance.

In:

Out:

None.

RepriceInstance

Updates the instance with values from the Pricing Manager service. A call to the Pricing Manager service's CalculatePriceCX method returns a property set that is the input to this method.

In:

The input property set has child property sets containing the reprice information. The format of the input property set is as follows:

< ObjId="value" RootId="value" Version="value" >

< IntId="integration id" FieldName="value"... FieldName="value" >

< IntId="integration id" FieldName="value"... FieldName="value" >

...

< />

In this context, the Integration ID is used to retrieve the instance item.

Out:

None.

SetAttribute

Sets the value of an item's attribute.

In:

Out:

None.

SetItemQuantity

Sets the quantity of an item.

In:

Out:

None.

Object Broker Methods

The methods in this section call the Cfg Object Broker business service, which functions as a wrapper for the Object Broker.

GetProdStruct

This method returns the full structure of the customizable product.

In:

Out:

<ProdStruct> RootId

<ProdId> Name ClassId

<Port> Name ClassName ClassId OrigId Type MinCard MaxCard DefltCard LocalType InternalType

<Subobject Id/>

...

</port>

...

<Attribute> Name

<Domain Value />

...

</Attribute>

...

</ProdId>

...

</ProdStruct>

DeltaQuote

Performs a recursive tree comparison of two property sets to determine the difference between them based on a supplied criteria. This returns a copy of the destination product instance marked up to indicate changes. Out of the box, this API is called from an external service only in SIS Order Management so using that feature is the only way to see this API in action for the API Discovery.

Example: you start with a computer that has one hard drive and a 900 MHz processor. You upgrade it to add a second hard drive (quantity now = 2) and replace the processor with a 1000 MHz model. The result would be one hard drive existing, one hard drive new (the instance is split), one 900 MHz CPU removed, and one 1000 MHz CPU new.

If the output property set is empty and no error code is thrown, the cause is most likely that the instances were not recognized. Check the RootId parameters and the indenting of your source and destination SiebelMessages.

In:

Out:

The destination instance is returned as a SiebelMessage, modified and marked up with status information. The status (new, modified, existing, removed) is indicated in the Action Code field of each item and attribute.


 Product Administration Guide, Version 7.5 
 Published: 18 April 2003