Bookshelf Home | Contents | Index | Search | PDF

Product Administration Guide > Technical Reference > eConfigurator API >

About the Instance APIs

---

Instance APIs follow these general concepts:

The Remote Complex Object Instance Service is a business service. It can be accessed by anything in the Siebel architecture that can use a business service. As a business service, it is 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 quotes, 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.
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.

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

LoadInstance

This method loads the complex object into memory. This is the starting point for all configurations.

Input Arguments:

ObjId—the unique identifier of the complex object header (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
IntObjName—the name of the integration object specified in Siebel Tools.
TriggerEvent—the flag that determines if script events are triggered. Normally, it should be set to Y. Set it to N for special uses of the API where script events are not desired.
(Optional) Version—version arguments are used only when testing a customizable product version that is different from the currently released version.
(Optional) NewRecord—if set to Y, the instance will be populated with default values. The default is N.
(Optional) AutoSync—if set to Y, the instance will be synchronized to the database immediately after loading. The default is N.
(Optional) SearchSpec—set this parameter to filter out all other hierarchical instances in the child buscomp. The default is an empty search specification. This parameter must have the following format:

"[Header Buscomp.Id] = 'Id' AND [Item Buscomp.Root Id] = `Root Id'"

ex. [Quote.Id] = '10-4FR6D' AND [Quote Item.Root Id] = '10-81DUX'

(Optional) ExternalScript—set this parameter to Y when running headless configurations (for example, through Siebel COM Data Server). Anything other than the Cfg Web UI Service is considered headless configuration. The difference is based on who resolves the linked items. The default is N.

Output Arguments:

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

CreateSession—if this property is set to Y the method CreateSession must be called after LoadInstance.
(Optional) IsConfig—if this property is present and set to Y the configuration model has configuration rules defined.
(Optional) Links—if this property is set to Y the model has linked items.
(Optional) UnresolvedLinks—if this property is set to Y the model has unresolved linked items that must be calculated by the caller.
If NewRecord is set to Y in the input property set and CreateSession is set to N in the output property set, the output will have the instance property set returned as a child of type CxObj (see the output example below). Here is an example of a return property set:

< IsConfig='Y' UnresolvedLinks='Y' CreateSession='Y' Links='Y'>

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

</Links>"

<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.

Handling Links. A child property set of type Links is 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 version 7.0.4 this changed to the INPUT property set for CreateSession. Configuration rules may have been defined for these linked items, 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, as in this example:

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

A child property set of type UnresolvedLinks is returned if the model has linked items that the business service could not 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 as headless configurations. The programmer must resolve all other links.

NOTE:  Make sure the unresolved links are calculated and their IDs and values are 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

This method initializes a configuration session, which is necessary for customizable products that have constraint rules. It is called immediately following LoadInstance where required.

Input Arguments:

ObjId—the unique identifier of the complex object header (for example, Quote Id).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
IntObjName—the name of the integration object specified in Siebel Tools.
TriggerEvent—the flag that determines if script events are triggered. Normally, it should be set to Y. Set to N for special uses of the API where script events are not desired. LoadInstance and CreateSession should have the same setting.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
(Optional) NewRecord—if set to Y, the instance will be populated with default values. The default is N.
(Optional) AutoSync—if set to Y, the instance will be synchronized to the database immediately after loading. The default is N.
(Optional) ExternalScript—this parameter must be set to Y when running headless configurations (for example, through Siebel COM Data Server). The default is N.

Output Arguments:

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

SetInstance

This method 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 that is indicated by the integration object specified.

Input Arguments:

Same arguments 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.

Output Arguments:

Same arguments as LoadInstance.

SyncInstance

This method saves the complex object instance where it originated.

Input Arguments:

ObjId—the unique identifier of the complex object header.
RootId—the unique identifier of the complex object root (for example, Quote Line Item row Id).
IntObjName—the name of the integration object specified in Siebel Tools.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.

Output Arguments:

None

UnloadInstance

This method removes the existing configuration session from memory. It should be called after synchronizing the instance at the end of the configuration session.

Input Arguments:

ObjId—the unique identifier of the complex object header.
RootId—the unique identifier of the complex object root.
IntObjName—the name of the integration object that was used to load the instance.

Output Arguments:

None.

GetAllPorts

This method retrieves a list of all ports and (possibly) their contents for a product. It gets all ports for a product but not for its child products. It retrieves the basic definition of the product and does not consider any current configuration session state, so every possible port is retrieved.

Input Arguments:

Product Id—the ID of the product in Internal Product.
(Optional) Version—version is used only in validate mode.
GetPortDomain—the flag that determines whether or not to also retrieve the domain of each port. Use Y or N to get the domain or not.

Output Arguments:

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

<Output>

   <Port>

      Port Information here

   </Port>

</Output>

EnumObjects

This method 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.

Input Arguments:

ObjId—the unique identifier of the complex object header (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
IntObjName—the name of the integration object specified in Siebel Tools.
Parent Path—the path to the parent object whose child objects you want to enumerate. The path is the object's Integration ID.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
(Optional) Port Item Id—the ID of a specific port (for example, ORIG_ID of the port in S_PROD_ITEM table). If specified, only the items in this port are enumerated; otherwise, all items in all immediate ports are returned.

Output Arguments:

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

<Output>

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

...

</Output>

GetAttribute

This method retrieves the value of an attribute.

Input Arguments:

ObjId—the unique identifier of the complex object root.
RootId—the unique identifier of the complex object root.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
Path—the path of the item where you are retrieving an attribute.
Name—the attribute name.

Output Arguments:

The value is returned as a property of the output property set, as follows:

<Output Value="value">

</Output>

GetFieldValues

This method retrieves field values for a product that exists in the complex product.

Input Arguments:

ObjId—the unique identifier of the complex object root (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row Id).
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
Path - the path to the item.

Output Arguments:

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

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

GetInstance

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

Input Arguments:

ObjId—the unique identifier of the complex object root.
RootId—the unique identifier of the complex object root.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.

Output Arguments:

The entire property set output is the complex object instance.

GetParents

This method retrieves all the parents of an item.

Input Arguments:

ObjId—the unique identifier of the complex object root.
RootId—the unique identifier of the complex object root.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
Path—the path of the item.

Output Arguments:

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

This method retrieves selectable items from the configuration engine for a port

Input Arguments:

ObjId—the unique identifier of the complex object root (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
Parent Path—the item parent path.
Port Item Id—the item port id.

Output Arguments:

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

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

GetPossibleValues

This method retrieves selectable values from the configuration engine for an attribute.

Input Arguments:

ObjId—the unique identifier of the complex object root (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
IntObjName—the name of the integration object.
Path—the Integration ID of the port to which this attribute is attached.
XA Id—the ID of the attribute for which the values need to be determined.

Output Arguments:

The property set returned will have the possible values as the property names, as follows:

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

GetProductId

This method gets the root Product ID of the complex object instance.

Input Arguments:

ObjId—the unique identifier of the complex object header (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row Id).
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.

Output Arguments:

The product Id is returned as a property of the output property set, as follows:

< Product Id="value" />

GetRootPath

This method returns the path of the complex object instance root.

Input Arguments:

ObjId—the unique identifier of the complex object header (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row Id).
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.

Output Arguments:

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

< Path="value" />

HasGenerics

This method 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.

Input Arguments:

ObjId—the unique identifier of the complex object root (for example, Quote ID).
RootId—the unique identifier of the complex object root (for example, Quote Line Item row id).
IntObjName—the name of the integration object.
(Optional) Version—Version arguments are used only when testing a customizable product version that is different from the currently released version.
Port Item Id—the ID for the port item that will have either children or generics.
Path—the path to the parent item of interest.

Output Arguments:

HasGenerics—Y is present if it does, not present if it does not.
HasChildren—Y is present if it does, not present if it does not.

Bookshelf Home | Contents | Index | Search | PDF