A few more tricks to manipulate PropertySets

In my previous article I described some basic tricks that are helpful for working with property sets. Here I am going to describe a few more tricks, which are still simple enough to quickly incorporate those in your daily routine. For doing something more complex, you can consider scripting, just as we did when we decided that workflows with huge number of steps are quite difficult and time consuming to develop and maintain.

Convert an instance of an integration object to a property set and back

I already mentioned this topic previously, however maybe it makes sense to discuss it more in regards to Siebel Order Management implementations, in which the developer is usually working with hierarchical integration objects, e.g. with the instance of the SIS OM Order integration object, and it means that line item components are not always siblings, but it could be a whole hierarchy built out of those. For us it took some time to discover the correct way, and finally the solution was found in Siebel out-of-the-box workflow, but let’s starts from the beginning...

When we started working with the Row Set Transformation Toolkit business service (RSTT), we realized that it can be used as a replacement for some scripts manipulating property sets that we’ve implemented before. To take full advantage of the RSTT power, we started to look for a way to convert an instance of an integration object into a property set, which could be used as the Row Set input parameter for RSTT.

The first option was quite obvious – call the EAI Integration Object to XML Hierarchy Converter business service – and it works most of the time. This business service allows converting an instance of an integration object to a property set and back. However, this way only the root line items are made available for the RSTT methods in case we are converting an instance of a hierarchical integration object. In most cases this should be sufficient, but not always.

Therefore when we needed to make child line items also available for the RSTT transformations, we came across another way that we figured out checking the PSP Driver Workflow Process – call the GetRowSetData method of the Context Service business service. This method has a lot of parameters, but most of them are optional, and in a most common scenario we have to provide only three input parameters: the instance of the integration object, the name of the variable map, and the PSPMode input parameter. The last one could have one of the following values: External, External Order, or External Quote. The last two values allow using specific mode for the given variable map – Order or Quote. If the extracted property set was modified, the changes made could be synchronized back to the instance of the integration object using the same business service, however with a help of another method – SyncRowSetData. One drawback of this method is a need to have a variable map that defines the fields used in the current implementation, but for a typical Order Management project it should not be that of an issue. There is also another, more serious drawback: the attributes are not available for the RSTT transformations.

Therefore if there is a need to manipulate all the line items, as well as their attributes, the vanilla solution that we found later comes to the rescue. I will not be providing all the details on input and output parameters here, as you can always check them in the Web Channel Pricing Driver Workflow, which provides an example of how to convert an instance of an integration object to a property set, modify values in a property set, and synchronize the changed values back to the original instance of an integration object.

So in this story we’ve spent a lot of time to implement what we have already had in our repository all along, and basically I have to admit that this was a classic case of reinvention of a wheel. Rounding up this story I would like to repeat this quite obvious and common thing that probably everybody of you have heard many times – always try to find out whether there is an out-of-the-box example implementing exactly what you need.

Also, an unusual transformation that utilizes the EAI Integration Object to XML Hierarchy Converter business service is described in the next chapter.

Convert an instance of an integration object with several root components to an instance of an integration object with a single root component

The first time I was asked about such a transformation was back in 2006, when I was on my first Siebel project. And the only option that I was able to suggest was scripting. This kind of transformation was asked for several times over the following years on different projects, and one day this scriptless solution has been discovered.

The input to this transformation and the desired output is shown on the picture below:

The above input and output are given just for example, as output doesn’t have any populated field on the Header component that will likely be required for most cases. However, we will not discuss how to add some custom fields on the Header component in this transformation, as it is possible to use the EAI Data Transformation Engine business service or techniques described in my previous article.

In the simplest scenario, the transformation could be done in just two steps:

1. The first step is converting the input instance of the integration object into a property set. But, for an instance with several root components, the EAI Integration Object to XML Hierarchy Converter business service cannot be used without a scripted wrapper. Therefore, in order to implement the scriptless solution, we can remove the “ListOf” container component from the input instance of the integration object using the Echo method of the Workflow Utilities business service. Note that in this case that means that the input instance of the integration object cannot contain any child components of another type, but a hierarchy of components of the same type, e.g. Line Items, is acceptable. Take a look at the pictures below to see the examples of input and output parameters: In addition, it makes sense to mention that the property set created at this step could be also used as the Row Set input parameter for RSTT transformations.

2. Call the PSHierToIntObjHier method of the EAI Integration Object to XML Hierarchy Converter business service to convert the property set from the previous step to the instance of the required integration object. If we are implementing transformation as on the picture above, the name of the integration object will be PDS Order. Also, the optional usage of the IgnoreUndefinedFields input parameter could be considered, if there is a chance that the property set contains properties that don’t match to the definition of the integration object.

As I already mentioned, this simplest approach works only when the input instance of an integration object doesn’t have any child components, for example the instance contains only line items without attributes.

If, on the other hand, the input instance contains some child components, those could be removed using the EAI Data Transformation Engine business service or the RSTT business service before using this approach. The Conditional Action Transform method of the RSTT business service works pretty nicely to create the output property set without child components. Have a look at the picture below to see the sample input parameters for this RSTT transformation, and pay attention to the On Default 1 input parameter. Actually, it takes some parameters from every row in the Row Set input parameter, and creates a new Line Item row in the Output Row Set parameter.

But again, there are some disadvantages as it doesn’t work well enough with hierarchical integration objects instances and you have to mention all the needed properties in the value of the On Default 1 input parameter.

As this is the very first time I showed an example of calling a method of the Row Set Transformation Toolkit business service, so it makes sense to give short RSTT introduction. If you are already familiar with RSTT and have used it in your workflows, the things mentioned below will be well known for you – feel free to skip the next section!

Brief RSTT introduction

The Row Set Transformation Toolkit is a business service that provides methods for manipulating and transforming row sets. Key things to know about RSTT:

1. The Siebel Tools Watcher is not helpful, when you are simulating the workflow calling the methods of the RSTT business service in Siebel Tools, as the results of any RSTT transformation are not displayed in the watcher. Therefore, don't try to use watcher for inspecting the results of calling the RSTT methods. While you are not very familiar with RSTT yet, you can use the WritePropSet method of EAI XML Write to File business service to inspect the results of the RSTT transformations.

2. All property sets that you input to the RSTT method should be retrieved in the output arguments. In addition, the output arguments should be retrieved in the same workflow variables as used for input. If these conditions are not met, the confusing "Requirements for combined IO mode not met in step '<?>'(SBL-BPR-00272))" error will be generated. For our example above, the output parameters should be as on the picture below, even if Row Set was not modified by executed transformation, and it is not going to be used for subsequent steps. Please also pay attention to the fact that the property names should be exactly the same as the property names for the input parameters:

3. You can use the "Validate Step" menu item from the context menu. It is enabled for steps that call the RSTT business service. Not all the errors could be caught this way, but it is still useful, since you can catch at least some of the syntax errors.

4. Value referenced as {Row.PropertyName} in PSP expressions will be taken from Context if it has the specified property and if this property is missing in the processed row of Row Set. The Context parameter was not used in the example above, but to make things easier you can think of the Context property set as a quote’s or order’s header, and of the Row Set property set as a property set with quote’s or order’s line items.

Before starting to work with RSTT, it would also be helpful to spend some time reading the Siebel Bookshelf about RSTT, especially the “Row Set Transformation Toolkit Business Service” and “Conditions and Actions for PSP Procedures” sections in the Siebel Order Management Infrastructure Guide. With that I am rounding up this short RSTT intro, so let’s get back to our transformations – namely to converting an instance of an integration object with several root components to an instance of an integration object with a single root component .

If there is a need to perform this kind of transformation with the instance what contains not only root components, but also child components, which need to be taken in the output, the instance of the hierarchical integration object could be mapped onto the instance of a non-hierarchical integration object using the Execute method of the EAI Data Transformation Engine business service before this transformation. However, this way the output instance of the integration object also doesn’t have a hierarchy – even if the target integration object is hierarchical.

Therefore the only scriptless solution that processes all components with child components and keeps the hierarchy I know is implementing a loop in the workflow, and then calling the methods of PRM ANI Utility Service business service inside the loop. If it makes sense to consider such a complicated solution, it is too early to discuss it now anyway – as we have not covered implementing loops in the workflows yet...

Iterations in workflows

I personally don’t like having a loop in the workflow and try avoiding that. But if it is the only way to implement the requirements, the iterations could be done over a property set and over root components in an instance of an integration object quite easily.

Iterate over a property set

The main idea is using the Conditional Action Transform method of the RSTT business service that for each invocation creates an output row set with an only child:

It is implemented at the "Extract 1 Child into the Temp PropertySet" step; have a look at the picture below to see the input parameters:

And here there are some explanations for input arguments:

• Condition 2 – this condition is always evaluated to true, but it will be reached only one time per each invocation for the first row in Row Set, because the second action for this condition specified as the On True 2_2 input parameter makes the first condition always true. And for the conditional action transformation if the condition is evaluated to true, the subsequent conditions are not analyzed.

• On True 1_1 – this action is here just because we need to have at least one action for each condition.

• On True 2_1 – this action moves one child from the Row Set property set into the Output Row Set property set.

• On True 2_2 – this action makes the first condition to be always evaluated to true as already mentioned before, so that the action specified by the On True 2_1 input parameter is not executed anymore, therefore for each invocation only one child is moved to the Output Row Set property set.

The check for something being extracted is done by "Extracted?" decision point; it checks the value of the variable of the Alias type; the only thing that needs to be considered is that the variable should point to a property that exists in all components, Id or Asset Integration Id are good candidates. If the value is empty, it means nothing was extracted, output row set is empty, and the looping should not be continued.

The "Empty the Temp PropertySet" step empties the Output PS variable that stores the extracted row. It is needed to ensure that the Output PS property set doesn’t have more than one child and avoid infinite loops.

Iterate over the root components in an instance of an integration object

There are three options that allow achieving the desired result, let’s have a look at those one-by-one:

Using the Siebel Datamapper service

The first option is to use the Execute method of the EAI Data Transformation Engine business service to invoke the workflow process (or business service) for each component in the instance of an integration component using data map expression with the InvokeServiceMethod function. Such approach doesn't provide good execution control and requires the EAI Data Map to be created, but it doesn’t require controlling a loop in the workflow.

Using the Siebel Converter Service and the RSTT

The second option is convert an instance of an integration object into the property set, and iterate over the property set as described above.

Using the SIS OM PMT Service

There are two methods of the SIS OM PMT Service business service that could help implement a loop:

1. Retrieve Next Object From List

2. Update Multi Object List

The picture below illustrates the approach:

The “Retrieve Next Object From List” step accepts the SiebelMessage input parameter that contains the instance of the integration object, over which the iteration is performed, and returns the following output arguments:

• Remaining Number of Objects - number of the remaining components after calling this method; this value could be checked by a condition at the “Continue?” decision point to determine, whether looping should be continued or not.

• Integration Id - the value of Integration Id property of the retrieved component.

• Object Id - the value of Id property of the retrieved component.

• SiebelMessage - according to Siebel Bookshelf, it is expected that it returns the instance with just the retrieved root component and its children, however actually it returns the input Siebel Message. Therefore an additional step could be implemented to create the instance with a single root component from the input Siebel Message, based on the values of returned Integration Id or Object Id.

The “Update Multi Object List” step doesn’t accept any input parameters, and returns the only output argument, a SiebelMessage that contains the updated instance without already retrieved root component. The output of this step should be used as the input parameter for the “Retrieve Next Object From List” step at the following iterations.

This option has its limitations, as it works only with the instances of the Order Management integration objects, e.g. SIS OM Order, PDS Order Item, or PDS Order during prototyping. In other words, the used integration object should have at least Line Item and XA components, as well as (optionally) Header integration component.

The conclusion

That’s it for now. This and the previous article were intended to show some not-so-obvious scriptless tricks. Hopefully more articles on this topic will follow.

The amount of code lines is a quite often used criterion of the quality and complexity of a Siebel implementation. I don’t think that it is a perfect criterion; however it does make some sense. On the projects I worked on memory leaks and crashes happened quite frequently in the scripts, even if these scripts were implemented according to Oracle Scripting Best Practices. On the other hand, the scripting solution is often easier to understand and maintain by new joiners, so it shouldn’t be dismissed altogether either.

Remember that the final decision on the approach to use should always be made considering future maintenance and configuration efforts. But if you need help with your Siebel project – don’t hesitate to get in touch!