REQUEST A DEMO

Having RuleManager invoke command line scripts

I’ve received a few questions on this recently, so I decided a post is in order.

 

One of the features in Rulemanager (both the Clarify/Amdocs Rulemanager and the Dovetail Rulemanager) is the ability to have it invoke command line scripts/executables via a business rule action.

 

For example:

 

  • if a case has been in a status of “waiting on customer” for more than 30 days, run a script that will close the case
  • when a new contact is created, run a script that will send the contact data to another system (such as an ERP system)
  • when a case is closed, run a script that will send the customer a satisfaction survey
  • etc.

 

What kind of scripts can Rulemanager run? Basically, any kind of script or executable, as long as no UI activity or user input is needed.

 

It’s very common that the script needs to communicate with the Clarify database. So, a scripting language or framework that “knows” Clarify is useful. Traditionally, cbbatch scripts were used. cbbatch is a command-line interpreter for ClearBasic code. ClearBasic (CB) code is Clarify’s proprietary Visual-Basic like scripting language.

 

Today, it’s common to use more modern technologies:

 

  • .NET code (C#, VB.NET, etc.) + the fcSDK
  • JavaScript or VBScript + the fcSDK
  • Powershell + the fcSDK
  • Java + Clarify Business Objects

 

 

This functionality really opens up the integration capabilities of your system.

 

Let’s walk through an example, using multiple languages and technologies to accomplish a relatively simple task:
When notes are logged to a case, update the site_time on the case record with the current date time. It’s a good example because it demonstrates not only calling a script, but also passing parameters to the script, and communicating with the Clarify database.

 

We’ll work through this same example in three different technologies:

 

  • cbbatch + Clearbasic code
  • JavaScript + fcSDK
  • PowerShell + fcSDK

cbbatch + ClearBasic code

 

1. Create the update_site_time_for_case.cbs CB script:

 

' Update the site time on the case to DateTime.now 

Sub UpdateCase ( caseIdNumber as String ) 

Dim br as New BulkRetrieve
Dim bs as New BulkSave
Dim caseList as List
Dim caseRecord as Record 

br.SimpleQuery 0, "case"
br.AppendFilter 0, "id_number", cbEqual, caseIdNumber
br.RetrieveRecords 

Set caseList = br.GetRecordList(0)
Set caseRecord = caseList.ItemByIndex(0)
caseRecord.SetField "site_time", App.CurrentDate 

bs.UpdateRecord caseRecord
bs.Save 

End Sub

 

2. I typically create a update_site_time_for_case.bat BAT file as a wrapper, which simplifies the actual business rule message.

 

cd C:\clarify\11.5\Server\rulemgr
C:\clarify\11.5\Server\rulemgr\cbbatch -db_server localhost -db_name fcclient -user_name sa -password sa -f C:\temp\cbbatch_testing\update_site_time_for_case.cbs -r UpdateCase -as “%1”

 

 

The above code could use a little explanation.

 

First, it does a “cd” (change directory) to the Clarify rulemgr directory. This is because cbbatch.exe is dependent on additional DLLs which reside in the rulemgr directory. You could also modify your system path to include this directory, if you so desire.

 

Next, we call the CB script. I always use full paths for cbbatch.exe and for the CB script, which reduces any confusion.

 

The -f parameter is the CB script

 

The -r parameter is which subroutine within the CB script to run. Note: don’t use “main” as a sub name here; it causes problems.

 

The -as parameter is a string parameter to the routine. Notice that the UpdateCase sub takes one parameter – the caseIdNumber.

 

We’ll open a DOS prompt, and make sure the script works.

 

update_site_time_for_case

 

Verify the script did its thing by looking at the site_time in the database. I use the SQL query capabilities within BOLT:

 

bolt1

 

Our script has now updated the case, just as we expect.

 

3. Next, we’ll use Dovetail Admin (or the Clarify Client, if you’re so inclined) to create a business rule that calls our script.

 

Rule Name: Update Site Time On Case When Logging Notes
Object Type: Case
Start Event: Log Notes
Conditions: None
Action Title: Run cbbatch Script
Create Activity Log Entry: Yes
Message Type: Command Line
Message: C:\temp\cbbatch_testing\update_site_time_for_case.bat [Object ID]
Repeat: No

 

4. Finally, we log a note to a case (using fcClient or the Clarify Client). Looking at the activity log, we see that the business rule action did fire:

 

activity_log

 

Again, using BOLT, we can also look in the database to see that it was indeed updated:

 

bolt2

 

So, our business rule is now properly firing, executing a script, and the script is communicating with the database.

JavaScript + fcSDK

 

We’ll use cscript.exe (a Windows command line interpreter for JavaScript and VBScript) to handle the JavaScript, and use the fcSDK’s COM interface to update the case.

 

First, we’ll create the update_site_time_for_case.js JavaScript script:

 

var FCApp = WScript.CreateObject('FCFLCompat.FCApplication');

var caseIdNumber = WScript.Arguments(0);

FCApp.Initialize();
var FCSession=FCApp.CreateSession(); 
FCSession.LoginFromFCApp();

var caseRecord = FCSession.CreateGeneric(); 
caseRecord.DBObjectName = 'case'; 
caseRecord.AppendFilter('id_number','=',caseIdNumber);
caseRecord.Query();
caseRecord('site_time') = -999; //-999 is a shorthand way of specifying DateTime.Now
caseRecord.Update();

 

 

Again, I typically create a update_site_time_for_case.bat BAT file as a wrapper:

 

cd C:\temp\fcsdk

 

cscript.exe C:\temp\fcsdk\update_site_time_for_case.js “%1”

 

 

 

We’ll also create an C:\temp\fcsdk\fc.env file to hold the database connection parameters:

 

db_type=MSSQL
db_server=localhost
db_name=fcclient
db_password=sa
login_name=sa

 

 

Next, we’ll modify the message of the business rule so that it calls our script:

 

Rule Name: Update Site Time On Case When Logging Notes
Object Type: Case
Start Event: Log Notes
Conditions: None
Action Title: Run fcSDK Script
Create Activity Log Entry: Yes
Message Type: Command Line
Message: cscript.exe C:\temp\fcsdk\update_site_time_for_case.js [Object ID]
Repeat: No

 

 

Log a note to a case, view the activity log to see that the action fired, and examine the SQL to confirm that the case record was updated.

 

All good, so we can move on to a final example.

PowerShell + fcSDK

 

PowerShell is my favorite new programming environment, so I had to throw in a PS example as well.

 

Create the UpdateSiteTimeForCase.ps1 script:$connectionString = “Data Source=localhost;Initial Catalog=fcclient;uid=sa;pwd=sa”

$databaseType = "MSSQL"

$caseIdNumber = [string] $args[0];

[system.reflection.assembly]::LoadWithPartialName("fcsdk") > $null

$config = new-object -typename System.Collections.Specialized.NameValueCollection
$config.Add("fchoice.connectionstring",$connectionString);
$config.Add("fchoice.dbtype",$databaseType);
$config.Add("fchoice.disableloginfromfcapp", "false"); 

$ClarifyApplication = [Fchoice.Foundation.Clarify.ClarifyApplication]

if ($ClarifyApplication::IsInitialized -eq $false ){
   $ClarifyApplication::initialize($config) > $null;
}

$ClarifySession = $ClarifyApplication::Instance.CreateSession()

$dataSet = new-object FChoice.Foundation.Clarify.ClarifyDataSet($ClarifySession)
$caseGeneric = $dataSet.CreateGeneric("case")
$caseGeneric.AppendFilter("id_number", "Equals", $caseIdNumber)
$caseGeneric.Query();
$caseRecord = $caseGeneric.Rows[0];
$now = get-date;
$caseRecord["site_time"] = [string] $now;
$caseRecord.Update();

$ClarifySession.CloseSession();

 

Next, we’ll modify the message of the business rule so that it calls our script:

 

Rule Name: Update Site Time On Case When Logging Notes
Object Type: Case
Start Event: Log Notes
Conditions: None
Action Title: Run Powershell Script
Create Activity Log Entry: Yes
Message Type: Command Line
Message: C:\WINDOWS\system32\WINDOW~1\v1.0\powershell.exe C:\temp\powershell_testing\UpdateSiteTimeForCase.ps1 [Object ID]Repeat: No

 

 

Log a note to a case, view the activity log to see that the action fired, and examine the SQL to confirm that the case record was updated.

Troubleshooting

 

Of course, things rarely work the first time out of the gate, so I’ll offer up the following troubleshooting tips:

 

  • Make sure your scripts work from the command line before having Rulemanager try to execute them.
  • Don’t forget that the account you’re logged onto is probably not the same account that Rulemanager is executed under. This especially affects your path and permissions.
  • Turn on Rulemanager debugging. For Clarify Rulemanager, set the logging level to Verbose. For Dovetail Rulemanager, set it to DEBUG.
  • Examine the Rulemanager log file(s) to verify that the command line script is executed.
    • For example, the Dovetail Rulemanager will not only show you the command, but the directory in which its executed from (which can be important!)
    • A Dovetail Rulemanager example log entry:
      2007-06-26 14:41:54,224 [Consumer1] DEBUG FChoice.RuleManager.ProcessExecutor – Executing process: “C:\WINDOWS\system32\WINDOW~1\v1.0\powershell.exe C:\temp\powershell_testing\UpdateSiteTimeForCase.ps1 453” in directory “C:\WINDOWS\system32”
  • If using the fcSDK, turn on fcSDK logging. (in PowerShell, in JavaScript)