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.

7 comments:

  1. Thank you, this article helped me out :)

    ReplyDelete
  2. Very good article. This serves as a one stop reference to know different ways while reading the IO hierarchy

    ReplyDelete
  3. Wonderful! Can you tell me how to read property value if there are multiple IC instances?
    Regards,
    Abu

    ReplyDelete
  4. Hello Abu,

    There is no possibility of reading values from multiple IC instances using Business Services.
    There is no solution yet.
    Only way is to go for scripting.

    Regards,
    Vignesh

    ReplyDelete
  5. This comment has been removed by the author.

    ReplyDelete
  6. This comment has been removed by the author.

    ReplyDelete
  7. no luck...again:

    The limitation of 75 chars in dot notation can be easily solved, by redefining the type of one or several child property sets using the "type" system property in the input arguments of the echo call (so called - "on the fly" of your echo call). You type this after the child PS name, then a "." and then the "type" word in sharpened/angle brackets ("<" and ">"). But IMPORTANT, you have to REALLY take care about the sequence property of the input arguments, otherwise you easily "destroy" or "recreate" the whole PS from scratch, by loosing your data.

    Example to shortening the type of child property sets:

    In this example we want to read the "Name" field of the Account:

    Input arguments:
    --------------------
    Input Argument: sm.ListOfAccount
    Type: Literal
    Value: LOA
    Sequence: 1

    Input Argument: sm
    Type: Process Property
    Property Name: .. your siebel message hierarchy...
    Sequence: 2

    Output arguments:
    ---------------------
    Property Name: your string property to store the results
    Type: Output Argument
    Output Argument: sm.LOA.Account.Name

    So instead of typing
    SiebelMessage.ListOfAccount.Account.Name
    we end up with
    sm.LOA.Account.Name

    In the similar way can be shortened any PS-tyle on any level of the hierarchy. Multiple re-typings in one call are supported. The sequence, as you see above, might seems not logical (first re-typing and then "sending" the hierarchy into the input), but this is the way how it works. Internally the c++ class works in "a kind of reverse order" comparing to the expected human logic :-)
    If you want to retype several PS level in the same call, then do it just at the beginning, i.e. with the lowest sequences. For example: sequence 1 retypes the "ListOfAccount" into "LOA", sequence 2 retypes the "Account" into "A", etc.

    Complex transforms using "echo" method needs a lot of practice until you'll get the feeling how the engine behinds that class works. But i can assure you that apart from reading single properties, even complex transformations using echo calls are possible. Well...almost. The only tricky thing is the deletion of child property sets and properties --> as i remember, i wasn't able to achieve clean deletion without "corrupting" other parts of my hierarchy instance. But maybe i still need to practice more on that. But for example, moving one Child PS on another level, i.e. restructuring - is feasible...in one or several echo calls...it depends on specific exercise. Often, several transforms are doable in one single echo call, like retyping on several levels, setting/changing values.

    Hope this extension to the good post above helps further for those who want to get more expert skills into this "hidden" undocumented area (well: documented is just the simple .dot notation, but not the transformations, retyping, etc.). The only disadvantage is, that these kind of manipulations are officially not supported by Oracle, so use this on your own risk.

    ReplyDelete