AR System® Filter Scripting Plug-Ins

Version 2
    Share This:

    This week's theme:  Cool Tech Tips
    This week's topic was recommended by a member of the AR System Developer Community.

     

    AR System® Filter Scripting Plug-Ins

    In this Tips and Tricks article, we revisit the idea of embedding a scripting capability into Action Request System. The initial Tips and Tricks article, entitled "Perl and the AR System Filter API," asserted the following:

    "Some scripting languages are well suited to tackle what would otherwise be tedious tasks with very little effort. Even though AR System enables you to create critical applications without writing code, you may come across tasks where a line or two of powerful scripting code works wonders. Examples of such tasks include text manipulation, flexible data validation, and third-party integration."

    This article introduces two new AR System Filter (ARF) API plug-ins that offer a much-improved scripting solution, as compared to the sample source code of the Perl plug-in. With the Perl plug-in, you compile it yourself, but the new plug-ins are ready to run out-of-the-box.

    Strong Microsoft Integration

    The AR System Filter Scripting Plug-In for Windows allows you to write scripts in JScript, VBScript, C#, or Visual Basic .NET. JScript and VBScript code is executed by Windows Script Host, and C# and Visual Basic .NET code is executed by compiling an in-memory .NET assembly and executing it. The plug-in takes care of all of these details for you. Scripts developed in any of these four languages are specific to the Windows platform. Although the plug-in only supports AR System servers on Windows, this plug-in offers a tremendous integration path, leveraging Microsoft languages and programming interfaces.

    Flexible, Cross-Platform Capabilities

    The AR System Filter Scripting Plug-In for Java allows you to write scripts in Java. Java code fragments are interpreted and executed by the plug-in and an embedded Java Virtual Machine (JVM). Note that this is not JavaScript, but rather run-time interpreted Java that can leverage standard Java classes and libraries (i.e. "jar" files) available throughout the Java and the Open Source community. The plug-in handles all of the details for you. This plug-in runs on all supported AR System server platforms.

    Examples

    The following examples cover a few tasks that you may want to implement in a script, such as performing complex data validation or string manipulation. Further examples and documentation are included with the plug-ins; refer to the plug-in documentation for additional examples.

    Complex Data Validation

    Credit Card numbers all follow a standard checksum algorithm. This algorithm enables a system to easily check whether or not a credit card number is valid. Although it does not check whether the credit card number has expired, or whether the purchase is approved, it does protect against data entry errors. The following C# code validates a credit card number. If the number is not valid, the script throws an exception, which results in a meaningful error message for the end user.

    System.String creditCard = (System.String) values[0];
    // strip out non-numeric characters
    System.Text.RegularExpressions.Regex re = new System.Text.RegularExpressions.Regex("[^0-9]");
    System.String numbers = re.Replace(creditCard, "");

    // Return the credit card number with only the digits in the string
    result = numbers;

    // The algorithm to validate a credit card is this
    // 1) Start from the right, and remove every second digit
    // 2) Double each of these values
    // 3) Add each digit in each doubled value together (12 becomes 3, for example)
    // 4) Add these values back to the remaining digits in the credit card number
    // 5) Verify that the result is a multiple of 10

    int total = 0;
    for (int i = numbers.Length - 2; i >= 0; i -= 2)
    {
    int num = System.Convert.ToInt32(numbers[i] + "");
    // double it
    num *= 2;
    // add the digits
    while (num >= 10)
    {
    total += (num % 10);
    num = num / 10;
    }
    // add to total
    total += num;
    }
    // now add on the unused digits
    for (int i = numbers.Length - 1; i >= 0; i -= 2)
    {
    total += System.Convert.ToInt32(numbers[i] + "");
    }
    if ((total % 10) != 0)
    {
    throw new System.Exception("Credit card number " + creditCard + " is not valid. The checksum is incorrect.");}

    At this point, you may be wondering how input values are passed into the script and how you return values from the script. Values from the Set Fields filter action appear in the array named "values" in the above script. The first value in the array, "values[0]", is the first value following the script, language, and referenced assemblies. In this case, the first value in the input array is the credit card number (See Figure 1).

    Note: Click images for full screen view.

    Figure 1 – Specify the Input Values to the Script in the Input Value List of the Set Fields Filter Action.

    Assign return values from the script to a variable named "result." If multiple values must be returned, "result" can be assigned an array of values. The Set Fields filter action references the returned value (or first value in the results array) with $1$. $2$ would reference the second value in the array. Figure 2 highlights how the value of the Credit Card Number field is set to the first value in the results array.

    Figure 2 - Use One or More of the Return Values from the Script to Change Data in Filter Set Fields Actions.

    String Parsing and Manipulation

    In addition to data validation, the scripting plug-ins provide a powerful solution for complex string parsing and manipulation needs. The following Java script performs a simple regular expression replacement. The arguments to the script are the regular expression that matches a sub-string, the value that will replace each sub-string, and the string upon which the script will operate. The returned result will hold the new string.

    import java.lang.String;
    import com.remedy.arsys.api.Value;

    String regularExpression = values[0].toString();
    String replaceWith = values[1].toString();
    String oldString = values[2].toString();

    String result = oldString.replaceAll(regularExpression, replaceWith);

    Note that the above Java script is not a Java class or something that you would normally compile. A Java script, in this sense, is a Java code fragment and does not require a surrounding "class" or "main." The code fragment is interpreted from beginning to end. The Java scripting plug-in documentation goes into more detail.

    The Filter Script Library

    Both the Windows and Java plug-ins make use of the Filter Script Library form. This form, shown in Figure 3, provides a convenient central repository for scripts. Additionally, by storing the scripts within a form and referencing them dynamically at run-time you can share scripts and provide flexible, secure access to the scripts by application authors. By restricting access to the Filter Script Library form, using AR System permissions, you can secure your script code so that only privileged users can define the code run in your application.

    Figure 3 - The Filter Script Library Form is a Convenient Place to Store Your Scripts.

    Availability

    The AR System Filter Scripting Plug-in for Windows and the AR Filter Scripting Plug-In for Java are available today in the AR System Developer Community. Select Community Downloads in the left side navigation, enter your Single Sign On (or create one), and search Utilities under the Development category.

    Summary

    The enormity of the capabilities offered by the Microsoft and Java communities goes without question. With the two new plug-ins discussed in this issue of Tips and Tricks, extending AR System into these technologies is easily within your reach. Download the AR Filter Scripting Plug-In for Windows and the AR Filter Scripting Plug-In for Java from the AR System Developer Community Community Downloads page.

    ~ Rich & Dan
    Principal Product Developers, Remedy Product Development
    Joined Remedy in 1997 and 1994, respectively