Simple tricks to manipulate PropertySets

Siebel provides good tools for working with Siebel Hierarchies, e.g. a developer can query Siebel data using the EAI Siebel Adapter business service, transform the queried data into an instance of external integration object using the EAI Data Transformation Engine business service, and then send the result to an external system. If there are no complicated requirements, and the transformations are straightforward, most of Siebel developers can implement outbound or inbound web service in a couple of hours.

However, in case of complicated integration scenarios and order management implementations, you may need to perform non-standard manipulations with instances of integration objects and property sets, e.g. merge property sets, sort a property set, or delete duplicates in a property set. In such cases scripting often comes to the rescue; still, if you’ve spent a lot of time with Siebel, chances are that you can do a lot without scripting. Yes, that’s true, even removing duplicates by some properties or sorting the property set is possible to implement without any scripting at all. But does it make sense to work several hours in a row – or even a full day – just to implement a single requirement? What’s the point? Is it only for the joy of implementing a “scriptless” solution? Maybe it sounded reasonable and you went this way. It might have taken longer than anticipated, but finally you have finished your workflow, and you are proud of yourself. You definitely deserve it – your workflow in Siebel Tools process designer doesn’t fit your wide monitor with huge resolution, it has a lot of decision points, a couple of nested cycles, and many calls to Row Set Transformation Toolkit (RSTT), Product Manipulation Toolkit (PMT), and other mysterious services. But what happens if after several months, a junior developer will be assigned to modify your workflow? Anyway, isn’t your life too short for building such huge and complicated workflows? If it is, why not consider some scripting?

For some simple requirements though, it still makes sense to consider Siebel declarative alternatives to scripting, e.g. you really don’t need a script to create a property set and populate it with some properties there. In this article I will demonstrate some simple “scriptless” tricks for working with hierarchies using out-of-the-box Siebel capabilities. But I will not be touching one of the most famous out-of-the-box business service designed to manipulate property sets - Row Set Transformation Toolkit, as it is an exciting story that deserves to be told separately.

Also, I will not be explaining what the integration objects and property sets are; however, one thing that needs to be casually mentioned is how an instance of an integration object (often referenced as Siebel Message) is different from a property set. Actually it is almost the same, Siebel Message is a property set also, often of type SiebelMessage, with some specific properties, including IntObjectName and IntObjectFormat, and, optionally, MessageId and MessageType. The fact that Siebel Message is a property explains why if a trick works for property set, it is going to work also for an instance of an integration object. However, you have to keep in mind that the opposite isn’t always true!

Creating a property set

There are two ways to create a property set, and both involve the famous Workflow Utilities business service:

This is a relatively rarely used way – invoking TextToPropSet, a hidden method of the Workflow Utilities business service. Only one input parameter, Text, should be populated, and the expected value is a property set in its string representation; such string-encoded property sets can be observed in Siebel log files quite often. E.g., passing an input string such as @0*0*0*1*0*0*0*1*7*PropSet0*0*0*6*Header0* returns a property set of PropSet type with one nested empty property set of Header type. The output argument name will be the same as the type of the property set – PropSet. This is a good option to create an empty property set without populated properties, and there’s also a trick for creating a property set with populated properties!
Invoking the Echo method of the Workflow Utilities business service. Define a new workflow variable Context of type Hierarchy. Add a new business service step and specify input and output parameters, like this:

It can be any other literal name in input arguments instead of used X, however the same name should be taken as output argument.

This approach could be helpful to wrap an instance of an integration object or property set into another property set, e.g. it could be useful for calling SetInstance method of the Remote Complex Object Instance Service business service (RCOIS). The input and output parameters can be seen below, and the Context passed as an input parameter is the property set created earlier:

And we end up with the property set specified as an input being added as a child to another property set:

Creating an instance of an integration object

An instance of an integration object is a property set, too; therefore the ways described above work for them as well. In addition, there are two more options for creating an instance of an integration object:

Invoking the Execute method of the EAI Create SearchSpec IntObj business service. This is an out-of-the-box business service, but anyway it is written in eScript. Here’s an example of input parameters:

This business service allows populating properties on the root integration component specifying property names as input parameters; e.g., the Account input argument on the picture above. Names of such input parameters should be the same as field names in the definition of root integration component in Siebel Tools. The SiebelMessage output argument returns an instance of an integration object that contains only a root integration component with the properties that were specified in input parameters:

Keep in mind though that this business service doesn’t validate input parameters against the definition of integration object in Siebel Tools!
Invoking the CreateEmptyPropSet method of the PRM ANI Utility Service business service. Only one input parameter named "Hierarchy Name" is required and it accepts the name of the integration object to be created as the name is defined in Siebel Tools. The SiebelMessage output argument returns an empty instance of an integration object. The returned instance contains a full structure of the requested integration object: every integration component defined in Siebel Tools is created, and every integration component field defined in Siebel Tools is created with an empty value. Removal of redundant properties or redundant integration component could be achieved, for by invoking the Execute method of the EAI Data Transformation Engine business service.

Converting an instance of an integration object into a property set and back

In some circumstances instances of integration objects are needed to be converted into property sets and back. One scenario could be, for instance, to convert an instance of an integration object into a property set, modify the property set with RSTT, and then convert the property set back into an instance of integration object.

There are several ways of converting the an instance of an integration object into a property set, and the way to be used depends on the desired result, in most cases the EAI Integration Object to XML Hierarchy Converter business service works just fine. It provides two methods with self-descriptive names that could be used – IntObjHierToPSHier and PSHierToIntObjHier. The only thing that should be mentioned here is that PSHierToIntObjHier has a hidden argument IgnoreUndefinedFields that is helpful to avoid an error being thrown when property set contains a property that doesn’t match the definition of the integration object.

Extracting property values from integration object instance or a property set

There are five ways to do it:

Dot notation and the Echo method of the Workflow Utilities business service.
Workflow variables of the Alias type.
Execute method of the FINS Industry XML Query Service business service.
GetFieldValue method of the CMU External Integration Service business service.
GetProperty method of the PRM ANI Utility Service business service.

The first four are universal approaches, i.e. those work for both property sets and instances of integration objects, but the last one works only with instances of integration objects. Let’s have a quick look at each of the available options.

Dot notation

This is, perhaps, the most well-known method of extracting property values. To extract the values of Order Type and Order Status properties from the PropSet created earlier, specify the following input and output arguments:

The dot notation method could be used to extract several values in a single workflow step. However, be careful extracting multiple property values like this – if one of the properties being extracted is missing, the extracted value could be … value of randomly chosen property extracted at the same step! Such a confusing behavior has been noticed in different Siebel 8.1 implementations. Also, in earlier Siebel versions the error was thrown trying to extract the value of a non-existing property. Finally, if there are several property sets of the same type traversing the path specified in output argument being found, the extracted value will be returned from the first of those.

In the Siebel Tools process designer the maximum length of an output argument is 75 characters, therefore the method should quite often be invoked several times, e.g. first step extracts the intermediate hierarchy, this hierarchy is provided as an input to the second step, and it then extracts the value of the needed property. Note that this approach doesn't work if integration object’s name or integration component’s name contains a dot, e.g. looks like this: “7.7 Order Entry Integration Object”.

Workflow variable of the Alias type

You might think of Alias type workflow variables as of pointers to a specific property in a property set. To extract the value of the Order Status property from the property set created earlier, create a new workflow variable of the Alias type, and then set the default string for it to “PropSet/Context/Header/@Order Type”. The maximum length of a default string is 250 characters – that should be sufficient for most of the cases. Pay attention that the default string for variables of the Alias type doesn’t support all XPath capabilities, e.g. predicates with search specifications.

If there are several property sets of Header type underneath a Context property set, the "Evaluation of Process Property Alias '<?>' returns multiple values.(SBL-BPR-00271)" error will be thrown.

The values of the variables of the Alias type are not displayed in the watcher window when simulating the workflow in Siebel Tools and in the Workflow Instance Monitor Logs. Also, the value of the variable of the Alias type returned as workflow output argument is not visible by the parent process. You can tackle this by assigning the value of a variable of the Alias type to a variable of the String type.

FINS Industry XML Query Service

Examples of input parameters can be seen below:

The notation looks quite promising, however only limited capabilities of XPath are supported, e.g. there’s no support for predicates with search specifications. The XMLHierarchy input parameter is mandatory, but you can use any names for query input arguments instead of MyQuery1 and MyQuery2 given as example, the extracted values will be returned by output arguments with the same names as those of the input arguments:

This approach allows extraction of several values in one call, but if the path is incorrect or property doesn't exist at the given path, an empty value is returned.

CMU External Integration Service

This service also allows extracting several values in one step, the number of extracted values is defined by the value of MaxFieldNames. The value of Hierarchy Node input argument is the type of property set, if the property set with the given type is not found, empty values are returned; and if there are several hierarchies with this specified type, the values from the first one found are returned.

PRM ANI Utility Service

Here the input parameters are given to extract the value from the instance of a PDS Order integration object:

Hierarchy Path: this input parameter contains path to the needed property, this path should be correct according to the definition of the integration object in Siebel Tools. It is specified in the form of IC1.IC2.IC3..., where IC1, IC2, IC3, etc. are the names of integration components. Business service throws an exception if traversing the path results in several components with the same name being found. Therefore the input parameters shown above work when Siebel Message has exactly one order with a single line item only; and an exception is thrown, when the order doesn’t have any line items or has more than one line item. Using the Alias variable to get the same value the default string should be Siebel Message/ListOfPDS Order/Header/ListOfLine Item/Line Item/@Status.
ReturnBlankIfNull is an optional input parameter; if the value of this input parameter is set to Y, exception will not be thrown when the requested property doesn’t exist in the instance of the integration object.

Output argument name that contains the extracted value is Property Value. Therefore in this case only one property value could be extracted in one step.

As you have already learned, all of these methods are quite straightforward, but are not very helpful when you need to do a more sophisticated extraction – e.g., extract the value of the Quantity property from the 3^rd line item, or extract the quantity value of the line item with a specific product. When something like this is needed, things are getting complicated, and one of the options could be to iterate over the property set or Siebel Message in a workflow: there are several ways how to do it, but this broad topic requires a dedicated article. In most scenarios having a cycle in a workflow really isn’t a very good option, and it is better to consider something else.

Setting property value in an instance of an integration object or a property set

There are, again, 5 ways of doing this:

Dot notation and the Echo method of the Workflow Utilities business service.
Workflow variables of the Alias type.
SetProperty method of the PRM ANI Utility Service business service.
Set Header Field Value, Set Field Value and Set Multiple Field Values methods of the SIS OM PMT Service business service.
SetFieldValue method of the CMU External Integration Service.

The first two are universal methods, i.e. those work with both property sets and instances of integration objects, the third works with instances of any integration object, and the last two work only with the instances of Order Management integration objects, i.e. having Header and Line Item components. Now let’s review all of these five approaches one-by-one.