Siebel’s Extended Function for RTF Template

Has anyone noticed some funky functions after you converted the BAS (Actuate) files to BI Publisher’s RTF template ? These functions look confusing especially for some of us coming from pure BI Publisher side. And even worse, they are most likely throwing errors at you when you try to preview with the MS-Word Add-in Template Builder!

So what are these? Well, these functions are there to help you to provide easier way to achieve some of the Siebel specific requirements. However, there are many functions that now we can just use BI Publisher’s out-of-box functions instead. And some functions just simply don’t work due to some defects with the conversion utility.

So it’s important to identify what functions we can use, when to use them, and how to use them.

What Functions Can We Use ?

There are about 30 or so of the Siebel extended functions in total. But most of them are actually either not really useful or duplicate of already existing BI Publisher’s functions. I couldn’t get an approval to share the list with public so I can’t list them here. But again, most of them are not really useful so I’ll list only those that are useful for the Siebel reports development at the next section.

When to Use Them ?

Among all the Siebel’s extended functions here is a list of the functions that I personally find useful.

Function Name	Description	Example
DivIntZero(int div, int divisor)	Method returns a 0 if the divisor is a zero.	<?psfn:DivIntZero(10, 0)?>
now()	Method to return the current time in the native time format.	<?psfn:now()?>
phoneFormat(java.lang.String inp)	Method to returns a String, which is the usual way to display the phone or fax number i.e. (XXX)AAA-BBBB	<?psfn:phoneFormat(ssPhone)?>
totext(java.lang.String d,java.lang.String f,java.lang.String e)	Method to return the date "d" the format "f" of the input date, which is in format " e ". format yyyy-MM-dd.	<?psfn:totext(ssCreated,"yyyy-MM-dd","MM/dd/yyyy")?>
Val (java.lang.String input)	Method to Returns the numeric value of a string expression.	<?psfn:Val(ssAccountName)?>

Now, you might have the following two questions.

• Ok, those look useful and I want to use them. But is there any pre-configuration or pre-requisite steps ?
• I see bunch of functions in my RTF template that was generated by the conversion utility, what should I do with them ?

So let’s talk about what pre-requisite steps required to use the Siebel extended functions. Then later I’ll discuss about what to do with the automatically generated functions in the RTF template.

What are the Pre-Requisite Steps to Use Siebel Extended Functions ?

There are three steps to ensure in order for you to use the Siebel extended functions.

• Configuration at Siebel Server
• Configuration at BI Publisher Enterprise Server
• Configuration at Client (BI Publisher MS-Word Add-in)
• Declare the Siebel Extended Function in each RTF template

Configuration at BI Publisher Enterprise Server

There are a couple of JAR files that come with the Siebel server installation. And you need to make these JAR files available to your BI Publisher server instance so that at the runtime the BI Publisher Server can use the JAR files to execute the Siebel’s extended functions. So make sure you have those JAR files, which are listed below, under the BI Publisher’s Server’s Java library folder. (e.g. OracleAS_HOME/j2ee/home/applications/xmlpserver/xmlpserver/WEB-INF/lib)

• XSLFunctions.JAR
• SiebelCustomXMLP.JAR
• SiebelCustomXMLP_SIA.JAR

Then you need to enable ‘External File Reference’ from the BI Publisher Server UI.

1. Log in to the Oracle BI Publisher Server with administrator privileges.
2. Click the Admin tab, and then select Runtime Configuration and Properties.
3. Change the default value for the Disable External Reference attribute to FALSE, click Apply, and then verify the changes were made.

The detail configuration for BI Publisher Enterprise Server is documented here.

Configuration at Siebel Server Side - Adding an Explicit Reference to JAR Files for the Oracle BI Publisher Server

This requires for the scheduling functionality to work with the functions. You can find the detail setup from here.

Configuration at BI Publisher client (MS-Word Add-in Template Builder) side

If you want to use the Siebel’s extended functions in your RTF template and preview with the MS-Word Template Builder you will get an error without the steps I’m going to talk about here. There are two things to do. You need to configure your Template Builder environment, which requires only for the first time, and need to declare the Siebel function name space in the RTF template for these functions to work.

Create a Batch File to Launch MS-Word Associating with the Siebel’s JAR files

Basically, you need to add a set of Siebel jar files to ‘_JAVA_OPTIONS’ variable and call MS-Word for these functions to work in your Template Builder instance. Here is an example script that you can use to launch MS-Word with the variable setting. 

echo %1 set _JAVA_OPTIONS=-Xbootclasspath/a:C:\81DQSSIA\client\classes\SiebelXMLP.jar;C:\81DQSSIA\client\classes\XMLP.jar;C:\81DQSSIA\client\classes\siebel.jar;C:\81DQSSIA\client\classes\XSLFunctions.jar;C:\81DQSSIA\client\classes\SiebelCustomXMLP.jar;C:\81DQSSIA\client\classes\SiebelCustomXMLP_SIA.jar "C:\Program Files\microsoft office\Office\Winword.exe" %1

Note that the above ‘set _JAVA_OPTIONS’ line must be a single line, no return key. You can find the detail of this configuration here from the configuration guide.

Once you have created the above script as a .bat file then you can double click this .bat file to start MS-Word and open your RTF template. In order for this configuration to work you need to shutdown all the MS-Word documents first and start MS-Word by clicking this bat file.

Declare Siebel’s Extended Function Name Space in RTF Template

Before you start using the extended function, first you need to declare a name space called ‘psfn’ as below in your RTF template.

<?namespace:psfn=http://www.oracle.com/XSL/Transform/java/com.siebel.xmlpublisher.reports.XSLFunctions?>

You need to declare this in every single RTF template file where you want to use the extended functions.

Now you’re ready to start using the Siebel’s extended functions!

How to Use Siebel Extended Functions?

You can use the Siebel’s extended functions as the same way you use other BI Publisher’s functions. Here is some example.

<?psfn:DivIntZero(10, 0)?> <?psfn:now()?> <?psfn:phoneFormat(ssPhone)?> <?psfn:totext(‘ssCreated’,"yyyy-MM-dd","MM/dd/yyyy")?>

You just need to start with ‘psfn:’ name space before the function. And you can preview the report output with a sample data that you have downloaded from the Siebel server UI (Web Client).

When you preview it you should be able to see the values from your sample XML data being calculated or formatted by the functions.

Troubleshooting:

1. I’m getting an error with ‘Namespace prefix 'psfn' used but not declared.’

Caused by: oracle.xdo.parser.v2.XPathException: Namespace prefix 'psfn' used but not declared.

As mentioned above you need to make sure that you have declared the Siebel’s extended function’s namespace in the RTF template. 2. I’m seeing an error with ‘method not found’ when trying to preview

2. I’m getting an error with ‘method not found’ when trying to preview.

If you are still seeing an error saying ‘method not found’ then you should make sure that you close all the MS-Word document completely then double click the custom MS-Word launch program (.bat) and open the RTF template file.

Conclusion

Once your RTF template is ready now you can upload it to the server and run it from the Web client. But you want to make sure that the server side configuration, which was mentioned above, has been done properly for these functions to work.

Hopefully now you understand how to use the Siebel’s extended functions within both the runtime and the development sides.

I still haven’t answered to one of the questions I raised above.

‘I see bunch of functions in my RTF template that was generated by the conversion utility, what should I do with them ?’

The Actuate to BI Publisher Conversion utility generate the RTF templates with many of the Siebel’s extended functions. So I will discuss about what to do with them tomorrow. Stay tuned!