Events

Publishing & listening-for Study Tracker events.

Capturing the changes that studies undergo over the course of their life is key to managing projects and preserving records for later reference. Study Tracker logs various study-altering events and their metadata in the activity table of the database, as well as publishes this activity as events to internal or external event managers (such as AWS EventBridge). The publishing of events in real-time allows you to integrate Study Tracker with other applications, which it would otherwise be unable to directly interface.

Events publishing allows you to add to the core functionality of Study Tracker in a number of ways, including:

• Sending notifications to users (eg. AWS SNS, Microsoft Teams, Slack, etc)

• Publishing reports

• Pushing data to other applications

Configuration

Study Tracker event publishing happens in one of two general modes: internal or external.

Internal Event Publishing

Internal event publishing is the default configuration. In this mode, the application will use Spring Boot's pre-configured ApplicationEventPublisher to publish events formatted as StudyTrackerEvent objects, within the scope of the application context. You can define event listeners by adding beans that implement the ApplicationListener interface, or have the @EventListener annotation attached to event-handling methods. For example:

@Component
public class NewStudyEventListener implements ApplicationListener<StudyTrackerEvent> {
    @Override
    public void onApplicationEvent(StudyTrackerEvent event) {
      Activity activity = event.getActivity();
      if (activity.getEventType().equals(EventType.NEW_STUDY)) {
        // Do something 
      }
    }
}

External Events

When explicitly configured, Study Tracker will publish events to external brokers. At the moment, the only supported event manager is AWS EventBridge. To use EventBridge as your broker, add the following parameters to your application.properties file, replacing my-event-bus with the name of the event bus you want to receive events from Study Tracker:

events.mode=eventbridge
aws.eventbridge.bus-name=my-event-bus

Study Tracker will publish events to EventBridge with the following format:

{
   "version": "0",
   "id": "dbbcde85-5ed0-6edd-b4d7-c69981b654ea",
   "detail-type": "NEW_STUDY",
   "source": "study-tracker",
   "account": "12345",
   "time": "2020-09-07T00:11:36Z",
   "region": "us-east-1",
   "resources": [],
   "detail": {
     "eventType": "NEW_STUDY",
     "triggeredBy": "woemler",
     "date": 1631130439566,
     "data": {
       "study": {
         "owner": "Will Oemler",
         "code": "DB-12345",
         "legacy": false,
         "externalCode": null,
         "keywords": [],
         "endDate": null,
         "lastModifiedBy": "Will Oemler",
         "description": "<p>This is a test</p>",
         "active": true,
         "program": "Example Program",
         "users": [
           "Will Oemler"
         ],
         "createdAt": 1631130439525,
         "createdBy": "Will Oemler",
         "name": "Test Study X",
         "attributes": {},
         "id": 10001,
         "startDate": 1631073600000,
         "status": "IN_PLANNING",
         "updatedAt": 1631130439525
       }
     }
   }
}

Most of the top-level attributes will be automatically defined or generated based on your local AWS CLI/SDK configuration, with exception of the following:

• detail-type will be equivalent to the EventType value of the published activity

• source will always be equal to study-tracker, making it easy to distinguish its events from

• other applications

• detail will contain the full Activity object that was published.

Activity objects have the following format:

{
  "eventType": "NEW_STUDY",
  "triggeredBy": "woemler",
  "date": 1631130439566,
  "data": {}
}

The contents of the data object will differ by event type, but will usually contain a JSON view of the record being manipulated by the event. The triggeredBy value refers to the signed-in user who triggered the event.

The next step is to define a rule within EventBridge that will match your desired incoming events and then trigger downstream services (such as Lambda). To create a rule for matching NEW_STUDY events, provide the following JSON to the Event Pattern input:

{
  "source": [
    "study-tracker"
  ],
  "detail-type": [
    "NEW_STUDY"
  ]
}

You can define what portion of the input data is passed to each individual event target by setting 'Configure input' parameter to 'Part of matched event' and providing a JSON selector as input. For example, to pass only the detail portion of the event to the downstream service, use $.detail as the input.

For more information on setting up event publishing to EventBridge, see the configuration document.