Skip to content

Custom Scripting Guide for Lithium FAF

Welcome to the Custom Scripting Guide for the Lithium FAF (Scripting filter). This document is designed to help you create your own scripts to extend and customize the functionality of the FAF. We will cover the supported scripting languages, the script interface contract, and provide examples to get you started.

Supported Scripting Languages

The Lithium FAF system currently supports the following scripting languages:

  1. Perl
  2. Python

Perl Version

The perl 5 is default installed in the all Lithium node.

Python Version

The system supports both Python 2 and Python 3. The version used depends on the system command python.

Prior to v24.03.07 OS release, python was NOT installed by default. Customers shall install the python2 via command yum install python2 manually, also create the link ln -sf /usr/bin/python2 /usr/bin/python

Ensure that the appropriate version of Python is installed and accessible via this command on your system.

Script Interface Contract

When creating custom scripts for the FAF filter, it is important to adhere to the defined script interface contract. This ensures that your scripts can communicate effectively with the FAF.

Script Argument(s)

Your script will receive arguments from the FAF system. These arguments are passed to the script at runtime and are essential for the script to perform its intended function. At the time of writing this guide, the script receives only one argument, which is the SMS content (The line break in the SMS content will be removed.). The FAF may provide more arguments for further extension in future releases.

Exit Codes

The exit code from your script is used by the FAF filter to determine the success or failure of the script execution. The expected exit codes are as follows:

  • 1: Match - Indicates that the given SMS content matches the specifications designed by the script. In this case the FAF filter condition returns TRUE to the filter chain.
  • Non-1: Mismatch - Indicate that the given SMS content does not hit the script specification. (Or any error occurred during the execution of the script. Including the script file missing or dependency issues.)

Getting Started with Custom Scripts

The following example script examines the given SMS content. If the SMS content contains any HTTP/HTTPS link, it returns 1 (indicating the filter condition is TRUE); otherwise, it returns 0.

Example: Python Script

import sys
import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(message)s'
)
logger = logging.getLogger(__name__)

def main():
    if len(sys.argv) < 2:
        logger.error("No input provided")
        sys.exit(1)

    arg = sys.argv[1]
    logger.info("Input: {}".format(arg))
    # Always return 1 if the input is contains any URL for demonstration
    if any(s in arg.lower() for s in ["http://", "https://"]):
        logger.info("URL found")
        sys.exit(1)
    else:
        logger.info("No URL found")
        sys.exit(0)

if __name__ == "__main__":
    main()

Example: Perl Script

#!/usr/bin/perl
use strict;
use warnings;
use Log::Log4perl qw(get_logger);

# Configure logging
Log::Log4perl->easy_init(
    {
        level => $Log::Log4perl::INFO,
        layout => '%d{ISO8601} - %m%n',
    }
);
my $logger = get_logger();

sub main {
    if (@ARGV < 1) {
        $logger->error("No input provided");
        exit(1);
    }

    my $arg = $ARGV[0];
    $logger->info("Input: $arg");

    # Always return 1 if the input contains any URL for demonstration
    if ($arg =~ /http:\/\/|https:\/\//i) {
        $logger->info("Found url");
        exit(1);
    } else {
        $logger->info("No url");
        exit(0);
    }
}

main();

Script Distribution

The script should be distributed to all server nodes where the FAF component is installed and running. Also, ensure that the system user "textpass" has ownership of the script file. If you have multiple server nodes running FAF, ensure that the script file path and name are consistent across all server nodes.

FAQ

  1. Do I need to ensure that Perl/Python is installed on all server nodes? No, only the nodes that have FAF components installed and running require Perl/Python to be installed.

  2. Does the script support any third-party dependencies? The usable third-party libraries indeed depend on the system-wide libraries installed on your FAF server nodes. Note that any Python virtual environments are not supported.

  3. How to debug the script executing? You can add log statements (examples as shown below). The log message will be available when you enable debug mode for Lithium. (Contact customer support to enable Lithium debugging.)

# Python
logger.info("Input: {}".format(arg))
# Perl
$logger->info("Input: $arg");
  1. Is the script capable of modifying the SMS content? No, the script itself should not modify the SMS content (i.e., have no effect); the SMS content should be modified by the FAF filter chain based on the return code of the filter condition.
  2. Is the script capable of modifying the SMS content?
  3. No, the script itself should not modify the SMS content (i.e., have no effect); the SMS content should be modified by the FAF filter chain based on the return code of the filter condition.

Conclusion

By following this guide, you can create custom scripts that integrate seamlessly with the Lithium FAF scripting filter. Ensure that you use the supported scripting languages and adhere to the script interface contract to achieve the desired functionality. With these tools and guidelines, you can enhance the capabilities of your FAF filter to meet your specific needs.