IBM Support

Examples of Bean Scripting Framework usage in IBM Rational Change

Technote (FAQ)


Are there any examples of Bean Scripting Framework usage in IBM Rational Change?


External listboxes can use Bean Scripting Framework scripts. The Rational Change TRELATION functionality is being phased out in favor of the Bean Scripting Framework.

In Rational Change 5.0 and later, TRELATIONS are replaced by a more powerful Bean Scripting Framework In-Process triggers implementation. There has always been some crossover in functionality between the Perl triggers and the TRELATIONS and the same is true of the newer BSF In-process triggers.

The way that TRELATIONS worked in Rational Change was that a TRELATION condition or rule was pre-defined in the ptcli.cfg and then called (by name) in the transition pre/post conditions. In the new system an In-process script is called instead of a TRELATION. The script is executed through the BSF API and, as such can be written as python, java or whatever your preferred language might be. It is fully documented as part of the Admin online help.

During the upgrade process to Rational Change 5.0 and later, all the default TRELATIONS (for example, "create associated task") are automatically converted to their equivalent BSF trigger scripts. This is done when an old process is loaded into the lifecycle editor.

Unknown, custom TRELATIONS are not automatically upgraded however. Instead they are replaced with the BSF trigger "warn_about_missing_trelation.js" which does nothing but print a warning message with the name of the missing TRELATIONS into the log. This is to both point out that the TRELATION is no longer in use, and act as place holder in the process to easily spot where the missing TRELATION goes, as opposed to just deleting the TRELATIONS.

If you call your script with the beginning...

bsf my_trigger.js  

Then the "bsf" is interpreted as "Use BSF to run in-process". The file extension (eg .js in the example) determines what language to use when executing the script.

The BSF API is documented more exactly in "...cs_app/webapps/synergy/trapeze/help/javadoc/com/telelogic/cs/api/ChangeTriggerApi.html"

Effectively there are now three APIs in Rational Change. That is, the Perl API, The Web Services API and the in-process trigger API (which uses BSF).

This is exposed as a special Trigger API using BSF to eliminate the overhead of starting a new process for each trigger. This is packaged as a class collection com.telelogic.cs.api and is usually addressed through the class com.telelogic.cs.api.ChangeTriggerApi

Standard TRELATIONS are repackaged as scripts by the upgrade processes but any customer-defined or customized TRELATIONS may have to be rewritten as BSF scripts



All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

External Listbox Example:

External listbox values can be retrieved by running a script from the CS_HOME/WEB-INF/wsconfig/scripts/listbox directory. The scripts, which may be written in either JavaScript or Python, can be written to fetch listbox values from any source. They run within the server process (via Rhino and Jython, respectively) and allow direct scripting of Java (server-side) code.

The browserinfo.js script provided out of the box is commented in such a way that it should provide some insight as to how external listbox scripts can be used. External listbox scripts can obtain information from any source your desire, so long as you can access it via a script running in the CS_HOME/WEB-INF/wsconfig/scripts/listbox directory.

The external listbox feature uses the Bean Scripting Framework (BSF) to run a JavaScript file for fetching the listbox values. The BSF supports Python and javascript. Rational Change 4.7 bundles the Apache Bean Scripting Framework 2.3.0 (including Rhino 1.5R3 and Jython 2.1). See the readme documents for the versions of these products bundled with later versions of Rational Change.

Thus the scripts should run within the server process (using Rhino for javascript and Jython for python) and therefore allow direct scripting of Java (server-side) code.

Rhino is a Java implementation of JavaScript which has all the features of JavaScript 1.5 and allows direct scripting of Java code.

Here is a psuedo-code example. It is supplied here 'as is' and for information only. We do not expect it to work without modification and it is not supported code.

Dependent listbox lookup script in Jython --

    ##### Listing #####

    from java.lang import *
    from java.sql import *

    attr_name = bsf.lookupBean("attributeName")
    db = bsf.lookupBean("database")
    results = bsf.lookupBean("results")


    url = "jdbc:mysql://"
    con = DriverManager.getConnection(url)
    stmt = con.createStatement()

    #Get the name of the parent attribute from the lookup database
    sql = "SELECT  ParentName FROM listbox.attributes WHERE AttributeName='%s'" %attr_name
    rs = stmt.executeQuery(sql)
    parent_attribute = rs.getString(1)

    #This is the ParentValue of the Highest Level attribute
    parent_value = "-"
    #For all child listboxes, get the value stored in it's parent attribute
    if ( parent_attribute != "-"):
       parent_value = bsf.lookupBean("ancestors").get(parent_attribute)

    sql = "SELECT AttributeValue FROM listbox.%s WHERE ParentValue='%s'" % (attr_name,parent_value)
    rs = stmt.executeQuery(sql)

    list = []
    while (

    uniqueList = []
    [uniqueList.append(item) for item in list if not uniqueList.count(item)]

    for s in uniqueList:


    ##### end listing #####

This is a general purpose script without attribute names hard coded inside the script itself. The script uses Mysql JDBC driver to connect to a database named listbox. The listbox database is assumed to contain the following tables:

attributes : has columns ParentName and AttributeName.

ParentName is the name of the parent attribute. AttributeName is the name of the dependent attribute. If the attribute has no parent, use a "-" (dash) as the parent name. The first row just shows the column names.

    ParentName  AttributeName  
    -  product_name  
    product_name  product_subsystem

One table per attribute, with the table name same as the name of the attribute. Two columns ParentValue and AttributeValue

As an example here is a table named product_name. The first row just shows the column names.

    ParentValue  AttributeValue  
    -  DOORS  
    -  SYNERGY

and an example for the table named product_subsystem. The first row just shows the column names.

    ParentValue  AttributeValue  
    DOORS  Database  
    SYNERGY  Change

If the table structure reflects more levels of dependencies, edit SQL statement within the script to get the values.

To connect to MS SQL database, change the JDBC driver line in the script to: driverName=""

and the URL to something like:


url = "jdbc:microsoft:sqlserver://servername:1433;DatabaseName=TelelogicTest;user=Telelogic;password=change"

Note: You will need to install drivers to connect to MS SQL.

Document information

More support for: Rational Change
General Information

Software version: 4.6, 4.6.1, 4.7, 5.0, 5.1, 5.2,

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 1416700

Modified date: 05 April 2011