Sectioning Sandbox Update Rules XML interface

Overview

Introduced with release 7.5.13, this functionality allows external rules to be applied to section records at the end of Sectioning Split sandbox runs.  These custom rules can be implemented without the need for source code changes to the Astra application. The rules are implemented using Astra Script XML language.

Interface Functions

The entry points into this Astra Script interface are:

InitSectioningUpdate(Term)

This function is called once at the end of the sandbox run. It is intended to allow one-time setup of global Astra Script variables that will be used in subsequent UpdateSandboxSection function calls.  This function takes one argument - the Term used in the sandbox run. This is a Term entity used by the Astra system. The details of this entity are provided here, in the Term.js sample file.

UpdateSandboxSection(SandboxSection)

This function is called once for each section in the sandbox run.  It takes one argument of type SandboxSection.  The purpose of the function is to allow the fields of the SandboxSection record to be modified according to customer specific rules.  Any changes made to the entity are saved to the database at the end of the sandbox run.  The details of the SandboxSection entity are outlined here, in the SandboxSection.js sample file.

Enabling the Interface

The external interface can be activated by placing an Astra Script XML file named SectioningUpdateRules.xml in the Files\Sectioning folder of the Astra Task Agent installation. A sample file called SectioningUpdateRules1.xml is shipped with the standard installation. The Astra Task Agent will parse the file and invoke the calls at the end of the sandbox run. A sample Astra Script XML file is provided here, in the SectioningUpdateRules1.xml sample file.  In this example, a "part of term" value is assigned to each section after sectioning has occurred, based on a custom set of rules.

Troubleshooting and debugging the Astra Script XML file

The Astra Script language includes robust logging to help troubleshoot runtime issues.  The syntax for logging is:

 

<log level="info">Logging text here ${runtime variable evaluation here}</log>

 

The logger supports log levels of debug, info, warn and error. Info log level logs all the time. This is the recommended setting while testing your code. The output of the logger goes to the log of the sandbox run. The best way to troubleshoot is to use extra logging during development to make it clear what is occurring in your code. After the code is working as planned, delete or comment out the extra logging.

 

The Astra Script XML file is parsed every time the sectioning split sandbox is run. This allows changes to be made to the script and tested by running a new sandbox run. The Task Agent will not need to be restarted to pick up script changes.

Writing Astra Script XML code

The Astra Script language is defined by the XML Schema Definition in Script.xsd. The most effective way to write the code is with an XML aware editor such as Visual Studio. By making your XML editor aware of the Script.xsd file, it will show help and auto completion as the code is created. The elements in the XSD file are documented to explain the usage of the various features. The Astra Script language supports:

 

•Conditional execution

•Looping

•User defined macros (functions)

•Global variables

•Local variables

•Stack variables (function arguments)

•Return values

•Complex expression evaluation

•Access to Astra entities and related entities through dot notation

 

Examples:

 

•PartOfTerm.Term.Name

•SandboxSection.CourseDeliveryMethod.Course.CourseNumber

 

The Astra Script XML Schema Definition is here, in the Script.xsd file.