Setting the SSA Primary Field

When I started configuring Siebel, I was mostly self-taught, which means that I usually settled for the first way I found of accomplishing my goal. Setting the primary record on a multi-value group through script is one example.

My method: query for the record I needed in the child buscomp, obtain the row id, and then use that row id to update the primary id field of the parent. For example, if I needed to set the primary position on the Account buscomp, I would begin by looking up the position id, then I would use a SetFieldValue statement to set the Primary Position Id with the id I had retrieved.

Wrong approach! That is the dangerous way. A scripting error will potentially corrupt your database in the same way direct sql could, by breaking its referential integrity. Directly setting a primary id field is not supported by Oracle.

The feature I didn't understand, which makes the process much easier and safer, is a system field called SSA Primary. You may have noticed this field in MVG Applet configurations. It's a system field, much like Created or Id, but it is different in two important ways:

1. The SSA Primary field does not correspond directly to a database column.
2. The SSA Primary field is editable.

Like other system fields, it is not listed in the Fields object in Tools, and you don't have to explicitly activate it in scripting.

Using the SSA Primary field, here is the correct way to use script to set the primary on an MVG, as recommended by Oracle:

1. Get the MVG business component using the BusComp.GetMVGBusComp method.
2. Use BusComp.SetSearchSpec and BusComp.ExecuteQuery methods to locate the correct record on the MVG business component.
3. Set the SSA Primary field with the statement BusComp.SetFieldValue("SSA Primary Field", "Y"), substituting the actual business component variable name.
4. Use BusComp.WriteRecord on the parent business component. This is because the Primary Id field is on the parent.

Some versions of Siebel Tools will give a semantic warning when you check the syntax after you try to set the SSA Primary field. This is a Siebel bug, and this warning can be safely ignored.

Update - Fixed a typo caught by commenter Duarte: Above instructions previously contained BusComp.SetFieldValue("SSA Primary", "Y") instead of BusComp.SetFieldValue("SSA Primary Field", "Y"). Thanks Duarte!

New Gadget from Impossible Siebel

Jason at Impossible Siebel has developed the ImposSiebel Toolbar Beta, which is definitely worth a look. As he writes:

...this is a program which allows developers to hook into any Siebel session, in anyenvironment, and get quick access to the Siebel objects without going into Tools.

Who doesn't want that? I can see this as being especially helpful for developers working with the SI client, where there is no Help -> About View feature. From the screenshots, it looks great!

Using a Randomizer to Split EIM Batches

EIM runs best when it imports data in batches of 5,000 to 10,000 records. There are potentially many techniques for dividing a large number of records into batches of this size. Here is my favorite:

Imagine the EIM_CONTACT table has 300,000 records that you want to import, but all of them contain the number 1 in the IF_ROW_BATCH_NUM column. Ideally, you would prefer to load the data in 60 batches of 5,000 records each, numbered 101 - 160. Use the following SESSION SQL step in the process to split the batches:

[SPLIT BATCHES]

TYPE = IMPORT

BATCH = 0

TABLE = EIM_CONTACT

SESSION SQL = "UPDATE SIEBEL.EIM_CONTACT SET IF_ROW_BATCH_NUM = floor(dbms_random.value(101, 160)) WHERE IF_ROW_BATCH_NUM = 1

The above EIM step is separated from all other functionality for clarity, but your own process will probably contain some differences. For example, the SESSION SQL could be part of your EIM IMPORT step, or the UPDATE statement could contain more columns.

Part of the guarantee of a randomizer is that generated numbers will spread equally across the available range, so you can assume that your data will be distributed evenly across the 60 batches.

Please notice that I'm assuming there are no records in batch number 0. Otherwise, they would be imported during this step. Also notice that I'm using functions specific to the Oracle database. Different databases have different functions for generating random numbers, but the technique is largely the same for any database you use.

The CancelQueryTimeOut Parameter

Long-running queries can be the most aggrevating problem that Siebel users face, and the ability to cancel them is often highly valued. The Siebel High Interactivity client has this capability. When a query has been running for a few seconds, a little pop-up box appears with a "Cancel" button, allowing users to stop the query.

In Siebel 7.7 and 7.8, the parameter to enable this was in the [SWE] section of the application config file (such as fins.cfg). To enable the functionality, change the parameter in the file:

CancelQueryTimeOut = timeout

If timeout is 3, for example, the popup button will appear after 3 seconds. If the value is -1, the popup is disabled.

Unfortunately, many Siebel administrators may believe the CancelQueryTimeOut parameter simply doesn't work in Siebel 8.0. It does work, but it is incorrectly documented. Siebel Bookshelf erroneously says the functionality is enabled in the [SWE] section of the config file, but there is no [SWE] section in Siebel 8.0. In Siebel 8.0, CancelQueryTimeOut is available as an Object Manager parameter.

To enable the functionality in Siebel 8.0:

1. Go to Administration - Server Configuration -> Enterprises -> Component Definitions
2. Query for your Object Manager component and select it
3. In Component Parameters, ensure that "Advanced" parameters are displayed
4. Query for the CancelQueryTimeOut parameter
5. Update the parameter to the amount of time, in seconds, you would like to wait before the pop-up button appears on a long-running query (the default is -1, which means the functionality is disabled)
6. Restart the object manager component

I find that this parameter is very useful for improving user satisfaction and also reducing the number of orphan tasks on the object manager, which can occur when a user closes the browser before a query returns.

Manager Visibility

Manager-based visibility is one of the toughest concepts for Siebel users to understand, and it also is a little tricky to simulate in a SQL-based query tool, so I thought I would post a summary of some of the basic concepts.

If I open a view with position-based team access control, such as one based on the Account business component, Sales Rep visibility returns all records where my position is on the sales team. By default, Manager visibility returns all those records, and also all records where one of my reports, direct or indirect, is primary on the sales team.

With single-position access control like with the Quote Bus Comp, Manager visibility returns all records associated with my position or with any of my reports positions.

With a business component such as Action, with person-based access control, records must be associated with my employee record or with the employee record of one of my reports. The reporting relationship is based on my currently active position. Subordinate positions must be the Primary Held Position of the subordinate's employee record for the employee to be included in the query. If the record has multiple owners, default functionality is to show only those records where the subordinate employee is the primary owner.

Views with Manager visibility can be based on business components that have a Person or Position type view mode. No special "Manager" view mode is required. Such views usually have names beginning "My Team's".

Person-based and position-based access control are based on a single relationship: between a position and it's parent position. Position is a party-based business component, and this relationship is defined on the S_PARTY table, with the column PAR_PARTY_ID joined to the parent record. Although every position can have only one parent, a position is subordinate to multiple positions for the purpose of manager visibility, because a position is subordinate to parent position's parent position, and etcetera. Therefore, manager visibility is actually based on an indeterminate number of iterations of the position/parent position relationship.

It would be extremely difficult to describe an unknown number of iterations of the position/parent position relationship with a single SQL statement. Siebel solves this problem by writing each position's reporting relationships to a table called S_PARTY_RPT_REL. A reporting relationship record is created for each related record, following the reporting chain through all iterations. This results in a many-to-many relationship, as each position can have many subordinate positions and each position can have a chain of parent and grandparent positions. Records in the S_PARTY_RPT_REL are created when a new record is inserted in S_POSTN, or when a user clicks on the "Generate Reporting Relationships" button in the Position administration view.

In a query to populate the My Teams view with data, S_PARTY_RPT_REL.PARTY_ID is set equal to the user's active position id. S_PARTY_RPT_REL.SUB_PARTY_ID joins to the applet's business component table and/or the sales team intersection table, depending on the business component.

For more about Manager visibility see the Siebel Security Guide in Siebel Bookshelf.

Get Rid of Dead Code

How many Siebel developers believe that the best way to remove lines of code from an existing script is to put some comment characters in front of the un-needed code, preventing it from executing. Many developers will copy an existing line of code to change an operation or add a condition, "commenting" the original version instead of deleting it. -- Added 5/3

Good coding practice tells us to diligently and carefully comment and annotate changes to scripts, right? Lets take a step back for a moment and think it through. I'm not certain that the commented lines of script are very helpful, at least in most cases.

First of all, commented script rarely helps to trace the historical changes made in a script. If the commented changes are dated, as they often are, you might find the date helpful. But script comments don't lend themselves to historical analysis nearly as well as versioning. Comparing a previous version of a script with the current version, in a source control repository for example, is much easier than trying to decipher the versions from comments in the script itself. Especially considering that the comments from several changes are often mixed in together.

Secondly, commented script doesn't help much in understanding how the current version of the script works. Lets face it: when you examine a script, you are not looking at the code that is commented. You skip the comments and focus on the code that is still active. If the developer happened to leave some actual words among all the dead code, you might stop to read it, but you certainly won't spend much analysis to find out how the script used to work.

Thirdly, and perhaps most importantly, dead code can cause significant overhead on the Siebel server. Every development team that habitually comments unused blocks of script will soon find that an entire event handler has been commented. In fact, it is common to find Siebel repositories with multiple event handlers entirely commented out. Also common are scripted event handlers where no script is present at all. Event handlers are marked as scripted even if the script contains no executable code except the application-provided stub:

function WebApplet_PreCanInvokeMethod (MethodName,
&CanInvoke)
{
return (ContinueOperation);
}

These event handlers cause a measurable increase in CPU load, especially when the event is frequently encountered. The empty scripts also become a maintenance issue, increasing the time required to compile an srf.

So, get rid of all that dead code. If a scripted event handler is empty, completely delete the script record in the Tools list applet. If you are removing individual lines of script, make sure you fully document your changes in design documents, and use a source control system to keep previous versions of the script. But keep the script itself clean. A clean repository will be easier to maintain and provide less overhead on your Siebel server.

A Regular Expression Validation

Data Validation Manager is great, but what would validation be without Regular Expressions? Here's how I used both to meet a business requirement.

The requirement arose from some errors logged when Siebel would attempt to send email to invalid addresses. We wanted to notify a user who entered invalid characters in the email address field. Of course, this edit wouldn't guarantee that addresses entered would actually exist, but it would at least ensure that people wouldn't separate two addresses with a colon (':') instead of a semicolon (';'), which is what was happening.

Step 1: Create a Business Service

Create a new Business Service with a method containing the following code snippet:

var sPattern = Inputs.GetProperty("Pattern");
var sSample = Inputs.GetProperty("Sample");
var rExp = new RegExp(sPattern);

if(rExp.test(sSample))
{
    Outputs.SetProperty("Result", 1);
}
else
{
    Outputs.SetProperty("Result", 0);
}

Step 2: Create a Data Validation Rule

Our Data Validation Rule Set is called "Employee Email Validation". In the data validation rule, use the new business service to test a business component field against a regular expression pattern. Use the following syntax for the pattern:

InvokeServiceMethod("ABC Validation Service", "Validate", "Pattern='^(([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([a-zA-Z]{2,5}))+([;,](([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([a-zA-Z]{2,5}))+)*$', Sample=eval([EMail Addr])", "Result")<>0

The regular expression pattern above was adapted from one available on the website http://www.regular-expressions.info/, where you can quickly learn how to get started with regular expressions. Also note the use of the eval() function, which will result in the contents of the Business Component Field being passed to the business service instead of the literal field name. See Metalink Doc ID 782338.1 (login required) for Oracle's How-To article for using eval() with InvokeServiceMethod() for a very similar application.

Step 3: Create a Runtime Event

Your next step is to create a Runtime Event manually through the Administration - Runtime Events screen. For our data validation, we created an Action Set for the Employee WriteRecord event.

• Action Type: BusService


• Business Service Name: Data Validation Manager


• Business Service Method: Validate


• Business Service Context: "Rule Set Name", "Employee Email Validation", "Enable Log", "Y"

Please note that although we did our validation on the Employee BusComp, it doesn't work on the Administration - User -> Employees. We have a custom view created on the Employee BusComp that exposes the email field. I'm not actually sure why it doesn't work in the vanilla view, but I'll post an update if I find out.

Step 4: Update Enterprise Parameter

A security feature introduced with Siebel 7.7 restricts the InvokeServiceMethod function to only business services that are registered on the Query Access List. The parameter can be set at the enterprise level or the component (e.g., Object Manager) level. However, since component-level settings always override enterprise settings, setting the parameter at the component level would preclude the use of any other business services that are registered at the enterprise.

• Enterprise Parameter Name: Business Service Query Access List


• Enterprise Parameter Value: ABC Validation Service

A common Siebel software limitation applies here. Only a maximum of 100 characters can be used to specify business service names in this parameter. You should carefully plan which business services you want to use with InvokeServiceMethod. Do not leave spaces between multiple business service names, but separate names with commas, and do not use quote marks.

Conclusion

After setting up a very simple business service to evaluate regular expressions, we can create any number of complex validations to display a message when a pattern is matched, with no additional scripting at all. For example, another requirement to validate the format of an identification number in a free text field was accomplished with a second data validation using the same business service.

If you are new to regular expressions, take a look. They are incredibly useful.

Two-Track Development: Part 1 - Establish a Process

Siebel projects often have lengthy development cycles, and enterprises often find that they need to manage overlapping releases where a development cycle is not complete before work begins on the next effort. Faced with such a requirement, project teams find themselves in the unenviable position of maintaining two Siebel development repositories at once, one for each project.

In the image to the left, you can see two development paths, one for Q1 and one for Q2. The Q1 path has an active development effort, with ongoing test cycles in QA and UAT. The Q2 path does not have a UAT environment, because only the Q1 path will be migrated to production. After the Q1 path deploys, Q2 will become the primary path, including DEV 2, TEST 2, and UAT. A new Q3 path can be created with the DEV 1 and TEST 1 environments.

To allow development to proceed on the Q2 path, the Q2 team must always be working with the latest version of the code from the previous project. The latest changes from the Q1 path must be merged to the Q2 path so that Q2 developers are working with an environment that looks like the one they will ultimately release. In other words, the Q2 repository includes a superset of Q1 and Q2 changes, just as the production repository will after Q2 deploys.

To successfully manage the process, it helps to have a regular merge schedule. At a pre-specified interval, such as once per week, a dedicated team member can discover changes to the DEV 1 environment, mediate conflict resolution between those changes and required configurations in the DEV 2 environment, and propagate those changes into the DEV 2 environment.

Once all changes have been merged into DEV 2, they will follow the normal promotion process to system test and, ultimately UAT and production.

How can this work? Over the next several posts I'll discuss some of the issues involved, along with some technical hints. I'll be relying especially on a process developed by a colleague of mine, Ashutosh Nigam.