# 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](https://aws.amazon.com/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:

```java
@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:

```json
{
   "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:

```json
{
  "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:

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://study-tracker.gitbook.io/documentation/installation-and-configuration/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.