SBM ModScript, Part 1 - An introduction to ModScript

over 3 years ago

SBM has had a scripting engine for two decades now called AppScript. It is powerful and fast. It is also based on VBScript, and was crying out for a refresh. SBM gained a new scripting engine in 11.3 named ModScript. AppScript is still supported.

So, what is ModScript? ModScript is based on the ChaiScript engine. When reading about ChaiScript, it is important to separate in your mind the documentation meant for C developers from the documentation about the scripting language. The C commentary and documentation is there for the implementers of languages like ModScript, not for you, the consumers of the scripting language. In order to get some visibility into ChaiScript, you can peruse the unit tests and samples, again, be sure to view ".chai" files, not ".hpp" or ".cpp" files. However, this series will have example scripts, so you don't necessarily need to dive too deeply into those long lists of files at the moment. For now, know that ChaiScript is a modern style script language with keywords like "for", "while", "continue", "break", "if", "else", "switch", etc, and it allows the script writer to create functions, classes, variables, global variables, global constants, function pointers, lambdas, and more. Much of the syntax is similar to JavaScript; however, the variables are strongly typed (once they are assigned a value of type "int", they cannot become a "string"). ChaiScript also has the concept of a Vector (array which can grow) and a Map (a binary search tree which stores key-value pairs, the key is a "string"). Furthermore, it has many utility functions including to_json() and from_json(), which know how to interact with Vector, Map, string, int, and double data types to create and parse valid JSON.

ModScript is more than ChaiScript; a scripting engine can't do much without an API for interacting with the host program. We added all the functionality of AppScript and more. We also created a conversion tool that converts scripts from AppScript to ModScript. As we already had a scripting engine in place, we were able to piggyback off of AppScript to create identical integration points for ModScript:

  • Pre-Transition
  • Post-Transition
  • Pre-State
  • Post-State
  • Notification
  • Self Registration
  • HTML Template
  • Direct URL
  • Database Import.
  • SOAP - In 11.4, we add a SOAP entry point, allowing ModScripts to be invoked by SOAP callers (including the Orchestration Engine and the new Scheduler).

With all these integration points, scripts can be invoked in nearly all aspects of SBM. In fact, developers who are familiar with AppScript Contexts will find that the ModScript runtime contexts are identical, providing the same information and access. All of AppScript's Ext functions are available in ModScript, such as Ext.CreateAppRecord() and Ext.TableId(). All of AppScript's classes are available, such as AppRecord, VarRecord, ProjectBasedRecord, and User, and all those classes have the same (or more) methods available in ModScript.

What we added to ModScript, above and beyond the functionality we copied from AppScript, is what I am very excited about:

  • Time zone awareness
  • Locale awareness
  • Date/time string formatting and parsing using time zone and locale rules
  • Regular expressions
  • REST call-outs (improved in 11.4)
  • Logging to files
  • Logging to Active Diagnostics (11.4)
  • ModScript can execute transitions on items from primary tables (AppScript could only Update, not Transition).
  • ModScript is available in a limited, read-only capacity in SaaS, as it is written from the ground up to be namespace safe.

Not only is ModScript feature rich, the features are growing. Almost every question from early adopters has lead to an enhancement to ModScript. For instance, a question about how to generate a temporary file name using the current time led the the creation of the TimeMillis class, which can interact with time down to the millisecond, as will as the TempFile class, which creates a temporary file and provides the file path name (the temp file gets deleted when the TempFile object goes out of scope). These enhancements are coming in 11.4, along with the ability to format and parse date/time strings using custom formats and more.

As an example of the features available in ModScript, consider REST interaction. ModScript can handle direct call-ins via the direct URL usage, and the script has the HTTP body available to it, making it possible to POST data to ModScript as JSON and have ModScript parse it, act on it, and write JSON back to the caller. In addition to that, ModScript can invoke REST calls using GET and POST, with all other HTTP verbs available in 11.4. ModScript gives you the ability to publish a single REST endpoint from Composer, which can be customized per-runtime in AR, and ModScript can modify the URL path and URL parameters so that one endpoint can serve any number of REST entry points from a REST API. It can send custom headers and see the HTTP headers from the response (11.4). As it can use the SBM Proxy, ModScript call-outs can take advantage of the OATH2 token exchange in order to fully support OATH2 end points. Opening up REST in this way completely opens the doors of what is possible.

From the hints above, it is clear that ModScript is still growing. Many features were added in 11.4 to extend functionality, improve usability, and fill gaps. The documentation coming in 11.4 is an overhaul of what was available previously, making the functionality much more understandable. We included many more examples, and corrected bad examples, to help get you going. Also in 11.4, the Composer Validate button becomes useful again, checking for missing variable/function declaration (which helps catch misspelled variable/function names). We are dedicated to helping you be successful with scripting and removing any frustration from the SBM experience.


SBM ModScript Table of Contents

Comment List
Related Discussions