Welcome to OnCourse Scripting

OnCourse offers a scripting feature that allows you to interact with and manipulate your student data in powerful and exciting ways. OnCourse scripts are written in Groovy. Groovy is a flexible and intuitive scripting language built for Java platforms.

Groovy Syntax

You don’t need to know a lot of Groovy to get started with scripting in OnCourse.

Defining new variables and functions

‘def’ is a Groovy keyword used to define new objects and functions. Variables are used to store information to be referenced and manipulated by a script. They also provide a way of labeling data with descriptive names so your script can be understood more clearly by a reader.

def to define variables

When you create a variable, you use the equals (=) symbol. The name of the variable goes on the left and the value you want to store in the variable goes on the right. Eg. making a variable called ‘year’ that stores the number 2018

def year = 2018 Eg. making a variable called ‘address’ that stores the street address of your College def address = ‘123 Example Street, Sydney 2000’ *Note: Strings need ‘quotes’ around then, numbers do not

def to define functions

Functions hold code to be executed. OnCourse scripts use a function called run() that you’ll need to define. You can think of the run() function as the body of your script. This is where you will write most (if not all) of the code that will make up your script.

OnCourse Script DSL and API

The onCourse Domain Specific Language (DSL) is how you can manipulate OnCourse data objects within your script. You can view the onCourse DSL and API here.

Working with OnCourse objects

Lets take a look at the CourseClass object. OnCourse database objects have a list of properties and methods that can be referenced in your script.

Properties of an object

In OnCourse, each Class must belong to a Course. So each CourseClass object must have a valid Course property. You can call the course property of a CourseClass to return the associated Course object

courseClass.course You can create a variable to store the course returned by calling courseClass.course. This variable can then be used later in your script. def myCourse = courseClass.course

Similarly, you may want to access all the enrolments in a class (for example, in the case where you want to send an email to all student enrolled in a specific class). You can do this by referencing the enrolments proptery of a CourseClass. Unlike ‘course’, this will not return a single object, but instead a list of Enrolment objects

courseClass.enrolments Similarly, we can make a variable to store our list of enrolments. A variable can store more then one object in a list. def myListOfEnrolments = courseClass.enrolment

Lets take a look at a current onCourse script and break down what is happening line by line. The script we are examining is send-student-class-commencement-notice.groovy. This is a default script that you can find in your OnCourse application under the name ‘send student class commencement notice’. If a class starts tomorrow, this script will send a reminder email to all students in this class.

def run(args) {     def tomorrowStart = new Date() + 1     tomorrowStart.set(hourOfDay: 0, minute: 0, second: 0)
    def tomorrowEnd = new Date() + 2     tomorrowEnd.set(hourOfDay: 0, minute: 0, second: 0)
    def context = args.context
    def classesStartingTomorrow = ObjectSelect.query(CourseClass)             .where(CourseClass.IS_CANCELLED.eq(false))             .and(CourseClass.START_DATE_TIME.ne(null))             .and(CourseClass.START_DATE_TIME.between(tomorrowStart, tomorrowEnd))             .select(context)
    classesStartingTomorrow.findAll { cc ->         cc.successAndQueuedEnrolments.size() >= cc.minimumPlaces     }*.successAndQueuedEnrolments.flatten().each() { enrolment ->         email {             template “Student notice of class commencement”             bindings enrolment: enrolment             to enrolment.student.contact         }     } }

The Script

The run() fucntion

def run(args) {     …. } In this first line, the run() fucntion is defined.
When a Groovy script is run in OnCourse, the OnCourse application looks for the run() function and execute what is in between the two braces { … }.

We also provide parameter to the script called ‘args’. ‘args’ is short for the arguments that are given to the script to be used. This argument allows the script to ‘talk’ (read and write) to your OnCourse database using an object called a Context (more on this later). You’ll notice that everything else in this script is enclosed in the braces after run(). We signify this by ‘tabbing’ over code inside of the run() braces.

Creating a date range

def tomorrowStart = new Date() + 1 In this line we are making a new variable that is a Date object represented by the name ‘tomorrowStart’. Creating a new Date() object assigns it the default valule of the current date and time. You can use the + and - operators on a Date() object to add or subtract days respectivley. If you executed this script at 6:00pm 01/01/2018, tomorrowStart would be 18:00 02/01/2018. So in this line we have created a new variable that represents tomorrows date.

tomorrowStart.set(hourOfDay: 0, minute: 0, second: 0) Next we need to set the time to 12:00am. We reference our date variable and execute the set() method to set the time of day. So after we this line our tomorrowStart variable = 00:00 02/01/2018 *Note: hourOfDay is 0 and not 12 as this function operates in 24 hour time. The following two lines are a similar operation, however it creates another variable named ‘tomorrowEnd’ that is set to 12:00am in two days time.

Retrieving OnCourse objects from your database

def context = args.context The ‘context’ is the mechanism that allows you to read from and write to your database. Remember when we learnt that ‘args’ is passed to the run function? Now we need to get the context out of the ‘args’ object. We define a new variable called ‘context’ and set it to the part of the ‘args’ that lets you communicate with your database.