Tuesday, August 14, 2012

Access to Siebel Message Elements

Four different ways exist to read Siebel Message elements:
  •  Dot notation
  • The standard PRM ANI Utility Service BS, GetProperty method
  • The standard FINS Industry XML Query Service BS, Execute method
  • The "Alias" type process properties
Dot notation

To retrieve Siebel Message child elements, the Dot Notation must make use of the IO, IC and IC Field names that the Siebel Message represents.

For example in the Sample Contact IO, structured as shown below:







To retrieve the Comment element, the Dot Notation will be: "SiebelMessage.ListOfSample Contact.Contact.Comment" The easiest way to find the correct Dot Notation is to query the IO in a WF
and to use the Watch window to inspect the structure of the Siebel Message, as shown below.









                                                                                     
Please note that there are the following limitations for the usage of the Dot Notation:
  •  The maximum length of the Dot Notation string is 75 chars, so if the IO hierarchy is too deep, or the names are too long, then Dot Notation cannot be used. As a workaround try to keep the names as short as possible (note that the XML Tag do not need to be equal to IC field names).
  • If multiple instances of the child IC are present in the Siebel Message,then it is not possible to reach the second instance.
PRM ANI Utility Service

A different solution allows one to overcome the 75 char limitation is to use a different standard BS called PRM ANI Utility Service, GetProperty method. There are three input parameters to the Business Service:
  • Hierarchy Path: (String)  
  • Property Name (String) 
  • Siebel Message (Hierarchy)
The Hierarchy Path: parameter should be set to the path of the Integration Component containing the required field, in the form IC1.IC2.IC3…, where IC1, IC2, IC3, and so on, are Integration Component Names (including spaces) that tell the method how to traverse the Object definition.The Property Name parameter should be the Integration Component Field name (including spaces).

For example, the Dot Notation shown above:
"SiebelMessage.ListOfSample Contact.Contact.Comment" Will become:

  •  Hierarchy Path: = Contact
  •  Property Name = Comment
  •  Siebel Message = SiebelMessage

Note that the IO name is not passed in, because it is defined in the SiebelMessage (in the IntObjectName attribute). The difference with the Dot Notation is that it is possible to define a Process Property of type string (which can be of any length) and pass this as reference to the Hierarchy Path: input argument (which is not possible with the Dot Notation).

For example, defining a process property as string and initializing it as:

Name :  FullPath
Default String : IntegrationComponentName1.IntegrationComponent  Name2.IntegrationComponentName3.IntegrationComponentName4.IntegrationComponentName5 

Then the input parameter will be:

Hierarchy Path: = [&FullPath]
 
Note that the PRM ANI Utility Service offers also other useful methods like
  •  GetSystemPreference
  •  RemovePropSet
  •  QueryBusComp
  •  SetProperty
  •  AppendPropSet
  •  CreateEmptyPropSet 
FINS Industry XML Query Service

To extract multiple values in one call, it is possible to use the FINS Industry XML Query Service BS, Execute method, but this approach requires that the IO instance is first transformed into a XML Hierarchy. The conversion can be done via the EAI Integration Object to XML Hierarchy Converter BS, IntObjHierToXMLHier method. 
For example, the Dot Notation shown above:
"SiebelMessage.ListOfSample Contact.Contact.Comment" (XML tags must be used now)



  



 The disadvantage of this approach is that the IO structure must be first converted to XML Hierarchy, adding processing overhead.
Alias

Lastly it is possible to use process properties of type "Alias".
 
To use the alias process property, add a step like

                                                                                                         

 
To ease understanding, it is recommended to use the name of the process property holding the Siebel Message in the value (Default String) for the Alias property ("SiebMsg" in the example above), even if this is not strictly necessary, as it only must match the value given in the "Input Argument" for the Siebel message.

It is possible to provide multiple aliases in a single call.