Writing custom automations with Groovy

Custom automations give you power to implement almost any workflow using the onCourse Domain Scripting Language (DSL). The onCourse DSL provides an interface you can use to interact and edit with your onCourse data. You can interact with the onCourse DSL using the Apache Groovy scripting language.

Break down of an automation

Let’s pull apart a sample automation. This one sends an email when an invoice is created.

Groovy

def i = args.entity

if (i.confirmationStatus == ConfirmationStatus.NOT_SENT) {
    def m = Email.create("Tax Invoice")
    m.bind(invoice: i)
    m.to(i.contact)

    m.send()

    i.setConfirmationStatus(ConfirmationStatus.SENT)
    args.context.commitChanges()
}

In that variable "args" you will get access to important objects to help you write your script. The most important two are:

args.entity
This is the object which caused the script to run. It is null if this script was triggered by a cron event.

args.context
This is the Cayenne context within which the script runs. You’ll use this to perform searches for other records or to commit changes back to the database.

args.loggedInUser
This object contains data about the user that triggered this script. It can only be used in scripts that are triggered by hand. The most useful fields are loggedInUser.email, loggedInUser.firstName, loggedInUser.lastName.

Groovy

def i = args.entity
def userEmail = args.loggedInUser.email

For convenience we’ve assigned this object to a variable with a nicer name. This just makes the rest of our script easier to read.

Groovy

if (i.confirmationStatus == ConfirmationStatus.NOT_SENT)

So our invoice has an attribute confirmationStatus. We can find these attributes documented in the onCourse javadocs. In this case we just want to check to see that we still need to send this email. We don’t want to send it if the invoice was part of a failed payment and reversal, or if the user already received it.

Groovy

def m = Email.create("Tax Invoice")

So let’s make a new email and call it "m".

Groovy

m.bind(invoice: i)

That email template has a property called "invoice" and we’ll bind our invoice object to that property.

Groovy

m.to(i.contact)

The invoice has a property called 'contact' and we’ll make sure the message will be sent to that person.

Groovy

m.send()

And we are done. This will finish all the work of creating the message.

Groovy

i.setConfirmationStatus(ConfirmationStatus.SENT)

We better now set the invoice to sent so that we don’t send this email again. For example, this script might be triggered because we edit the invoice to change the due date. In that case, the script will be triggered.

Groovy

args.context.commitChanges()

This last step is very important. All the changes we made (including the email we created) exist only in memory and not saved to the database until this step. Unless we save it, no email will go out and no other user will see our changes. When we commit, all the validation will run. For example, onCourse will prevent you from sending an email which has no 'to' contact and so the commit will fail. onCourse will also synchronise any objects with your onCourse website. This allows you to programmatically modify website content directly from these scripts.

For full details of the groovy language consult the official documentation here http://groovy.codehaus.org/ Groovy has very nice support for iterating through collections (such as a big list of database objects), regular expression matching and much more. Plus you get to use all the Java libraries already included inside of onCourseServer plus the full Java JRE.