Oscar Triggers

Introduction

Oscar-Triggers is a new module in Caisi-Oscar which allows agencies to customize the basic behaviour of Oscar/Caisi through scripting events. The customization works with events triggered by user actions which will trigger scripts to run.

Process

Example

When a user clicks 'Save' on a note the system will trigger an event called "casemgmt.note.save". This will be picked up by a script called "On-save-note-add-tickler". This script is setup to add a tickler to the user that he/she needs to follow up on the note in 14 days. The Outcome of the script is thus a tickler was added to the user.

Process

So the process and participants are:

User action --> Event --> Script run --> Outcome

Deliverables by version

Version 1

This version of Oscar Triggers includes:

1. Triggers (actions which will throw events that triggers outcomes)
2. Outcome API's exposed for scripting
3. Ability for admin-users to edit and persist scripts into database with wild-cards for which events to trigger on.

The events

1. Tickler created
2. User added to program
3. Consultation-request note created
4. Prescription modified

The outcomes

1. Add tickler
2. Add case note
3. Create referal
4. Admit client to program

Version 2

This version of Oscar Triggers includes:

1. Ability to add triggers to form events and ask for user response on trigger outcomes
2. Advanced events with alot of different functionalities in Oscar exposed as outcome-API's for scripts

The Script concept

Definition

A script is a pre-defined sequence of code lines that will execute when specific events occurs.

Script attributes

In oscar-triggers the script object essentially has has three attributes.

1. Script-lines
2. Language
3. Event-pattern

The Script-lines attribute is the actual script that will execute. The Language attribute is the language in which the script is written. This is any language supported by BSF. The Event-pattern attribute is pattern defined in regular expression or wild-cards for which events are matched.

Event-pattern

There are two kinds of supported syntaxes for oscar-triggers event-patterns.

1. Regular expressions
2. Wild-cards

See the Java SDK java-doc for more details on the syntax of regular expressions.

The wild-cards only supports stars (*) as wild-cards. It is added for convenience to support easy matching.

 Example

The following two events

net.sf.test.Event1
net.sf.text.Event2

would be matched my the following wild-cards expressions

*
net.*
net.sf.*
net.sf.test.*
net.sf.test.Event*

but not this one

netsss*

Event / Outcome details

Event: Tickler created

Ticklers+ is a workflow sub-system for Oscar. The code is mainly in the OscarWAR project. Users add, update and remove ticklers. Tickler is a work-order that is written by someone for someone else. The data of the tickler needs to be exposed for scripting as a bean attribute on the event object. Tickler page in Oscar:

Event: User added to program

The program-management module records which clients are in what programs. When a client is admitted to the program, this event should be fired off. The event needs to expose client-information, user-information, program-information, and reason for admission.

Event: Consultation-request note created

This is part of oscar, please see Oscar Manual and the system for details of what data that needs to be exposed in the event.

Event: Prescription modified

This is part of oscar, please see oscar doc and the system for details of what data that needs to be exposed in the event.

Outcome: Add tickler

The ticker+ sub-system needs to expose an API for adding ticklers with all details. Please implement using existing managers from oscarWAR distro which includes tickler+.

Outcome: Add case note

The case-management plugin has manager beans that expose functionality to add new case notes for a client. Please reuse these managers to create an intuitive API for scripting new notes for a client.

Outcome: Create referal

The program-management plugin has manager beans that expose functionality to create a referral for a client. Please reuse these managers to create an intuitive API for scripting new referrals for a client.

Outcome: Admit client to program

The program-management plugin has manager beans that expose functionality to create program admission for a client. Please reuse these managers to create an intuitive API for scripting new admissions for a client.

Implementation

Case study

Please see a detailed case study of Intake A form saving leading to tickler created.

Requirements

• The event registry is implemented and running as an oscar-plugin.
• The events in the different modules are thrown out using Spring through the ApplicationContext.publishEvent(ApplicationEvent) method.
• All events extend Springs ApplicationEvent class
• Solution is implemented building on the basic code already checked in as "oscar-triggers" project in cvs.caisi.ca
• Scripts should be running through BSF so that language is pluggable (already in oscar-triggers project)
• Scripts are saved to the database (already in oscar-triggers project)
• Scripts are administrated through admin interface which is linked to from Oscar admin page (already in oscar-triggers project, but needs to be linked and integrated UI)
• Utilise existing manager beans from caisi plugins if possible, otherwise call DAO objects. Don't create new DAO's with beans and hibernate mappings, rather request extensions of existing DAO's to us on caisi-dev, we might ask you to do the extension on the DAO.
• The managers are registered into the scripting environment using Registry beans this way:

<bean id="registry" class="ca.macedo.events.Registry">
  <property name="beans"><map>
  </map></property>
  <property name="scriptProvider" ref="scriptProvider"/>
</bean>

Example:

<property name="beans"><map>
  <entry key="programManager" value-ref="programManager"/>
 </map></property>

This will make the programManager spring bean available as "programManager" bean in the scripting environment. I.e. a script could do the following:

programManager.addProgram("test");

As the programManager bean is available in the scripting environment.

Tasks

• Create new event classes and add them to the existing modules of Oscar and the Caisi plugins. These events should cover most common scenarios and expose the data of the event in an easy-to-use API for the script
• Identify and test scripting on managers in existing modules of Oscar and the Caisi plugins (caisi-core, case-management, program-management)
• Extend the event registry framework in oscar-triggers module as needed and make it deploy as a plugin for oscar using the plugin-framework
• Extend the admin interface for scripts in oscar-triggers as needed to fulfill user feedback and requirements

Oscar-triggers base implementation

The base implementation of oscar-triggers include libraries that registers scripts for events. The events are matched against scripts using regexpression with additional "ca.caisi.*" style express support for ease-of-use.

The base web-project is in CVS, view it using http://devel.caisi.ca:81/viewvc/oscar-triggers/.

You can check it out using anonymous access to cvs.caisi.ca, see http://www.caisi.ca/wiki/index.php/CAISI_CVS.

To test the project check out tag Beta_0_1 and register the WAR project for tomcat 5.

The demo includes a servlet, called /se which is the admin interface. Here you can add update and remove scripts for events.

The two test pages are test1.jsp and test2.jsp.

Database

You need to update the appctx.xml spring configuration with your hibernate database connection settings (schema, username & pwd). The demo is setup with hibernate hbm2ddl which will automatically create the required table.

Test1.jsp

This page demos how events can return values to the caller. In this case the script can return back a text that is displayed as an alert to the user.

Test2.jsp

This page demos how events can pass in additional beans to the script, in this case a java.util.Properties instance which displays back values that are editable to the user and the script.