Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Understanding onCourse workflow - scripts and templates

edited April 2015 in News
As part of onCourse 7.0 (released December 2014), a very powerful scripting and template engine for business workflow automation was made available to all onCourse customers.

Here at ish we have been having lots of interesting discussions with customers about processes they'd like to automate in onCourse, and in many instances, we are developing new scripts and templates that all users can implement.

However, with great power comes great responsibility (and also a fair bit of complexity). For all the non-techy people out there here's the lowdown on how all the puzzle pieces fit together.

What is a script?

In a nutshell, a script is a piece of code that says "do this thing, when this thing happens". For example, send an email confirmation when an new enrolment record is created.

A script can be triggered to do its thing either when an event happens in the database (i.e. enrolment created) or at a set time (known as a 'Command Run ON' - CRON - trigger)

Unlike most of the code that drives the onCourse product, these scripted instructions are visible to you as an onCourse user, and for users with the appropriate permissions, editable.

At the most basic level, scripts can be enabled and disabled. Almost all of the scripts included as part of the onCourse standard installation are turned off by default. Why? Because most of them send automatic emails to people, and we don't want onCourse spamming your contacts without your say so.

If you understand what the script does, and want to switch it on, please do so but before you do make sure you check the templates it calls on..... leading us to.....

What is a template?

An email template is a pre-configured email that is used to send custom messages.

For the most part, onCourse scripts send email templates to onCourse contacts, like students. The name of the email template the script calls on is in the script code.

Before you enable a script, you need to make sure its email template(s) contain all the information you want to provide to the person who is going to receive it.

There are two parts to every email template - a plain text and an HTML version. What version the recipient sees is based on their email client settings. You can't control which version people choose to see, so it is important you have the same information in both versions of the email. The HTML version should just be a visually more pleasing version of the plain text content. If HTML email design is not your thing, just leave this field blank and everyone will get a plain text email.

So now you know what the pieces of the puzzle are, what should you do with them?

An example script, Send Application Decision

By default, this script is disabled. You need to enable it if you want it to run automatically.

This script is set to run on an entity event - it runs whenever an Application record is created or updated.

Now to look at the tricky part, the actual script code. I've added my own //comment annotations to explain what is happening


//define how and when the script runs, in this case when an application is created or edited
def run(args) {
def application = args.entity

//if the application has not already had a confirmation status email sent, send a message to them now
if (application.confirmationStatus == ConfirmationStatus.NOT_SENT) {
def m = null

//If the application status has been sent to offered, send the email 'Enrolment application accepted'
if (application.status == ApplicationStatus.OFFERED) {
m = Email.create("Enrolment application accepted")

//If the application status has been sent to rejected, send the email 'Enrolment application rejected'
} else if (application.status == ApplicationStatus.REJECTED) {
m = Email.create("Enrolment application rejected")
}

//send the defined email to the email address in the contact record of the student who applied
if (m) {
m.bind(application: application)
m.to(application.student.contact)

//now actually send the email
m.send()

//update the application to having a sent confirmation (so it doesn't get picked up next time the record is edited)
application.setConfirmationStatus(ConfirmationStatus.SENT)

//save all the changes to the database
args.context.commitChanges()


An example email template, Enrolment application accepted

This email template is linked to the 'Application' entity in onCourse. This defines how the email template can be sent manually, outside of the scripted process and I'll explain how this works in a future blog post.

I've added my own //comment annotations to explain what the template is doing.


//insert the default email header template at the top of the email.
${render("Header")}

//Address to the student
Dear ${application.student.contact.firstName},

//Remind them what course they applied for
Your application for enrolment in ${application.course.name} has been successful.

//If the application has had a fee override value supplied, tell the student what their enrolment fee will be.
//If there was no fee override, then this piece of text is not sent.
<% if (application.feeOverride) { %>
Your eligibility has been assessed and the fee applicable to your enrolment is ${application.feeOverride}.
<% } %>

//If a reason was supplied in the application, insert it here, otherwise do nothing
<% if (application.reason) { %>
${application.reason}
<% } %>

//This is a unique code that takes the student to the course page in your website, and shows either
// their fee override value or the default class fee if no override was set.
// They can click 'enrol now' on this page to complete the usual enrolment process.
To accept this position, please go to ${Preferences.get("web.url")}/course/${application.course.code} ?student=${application.student.contact.uniqueCode} and complete the online enrolment process.

//If you set an expiry date in the application, it will display in this line. If not, then this piece of text is not sent.
<% if (application.enrolBy) { %>
To accept this position, your enrolment must be completed before midnight on ${application.enrolBy.format("d/M/yy")}
<% } %>

//This is just some plain text. Feel free to add more conditions or information about your
// application acceptance or withdrawal requirements here
If you wish to withdraw your application, we would appreciate you notifying us by phone or email.

//insert the default footer template email
${render("Footer")}


So how do I create my own scripts and templates?

The best place to start is by copying an existing script and/or template and making changes. You can get the most up to date copies of these files in GitHub. Just copy and paste the Raw versions of the files from the web browser into a new onCourse record. Additional information you'll need for creating the new script and/or templates can be found in the properties file of the same name.

Remember all the API documentation for onCourse (stuff you can call on in a script or template) is publicly available here

You are also very welcome to create your own branches on GitHub for our developers to provide advice on your scripts (or fix them as needed!)

This coding business is all beyond my paygrade

No worries, that's what we are here for! Send us an email and tell us what process you'd like onCourse to automate for your business. We'll have chat to you about what you'd like to achieve and evaluate it for adding to the development list.





Sign In or Register to comment.