Schedule Activities Based On External Events

[pranav-super]

• Tickets addressed: MPS-124
• Review: By commit
• Merge strategy: Merge (no squash)

Description

Following the introduction of External Events in #1513, this PR introduces the ability to schedule Activities based off of External Event occurrences, using the procedural scheduler.

This PR introduces 4 new types which users can use in their definition of scheduling procedures to narrow down the external events they would like to schedule off of and which properties they would like to access:

• an ExternalEvent type, which contains event-specific properties,
• an ExternalEvents type, which represents a filterable collection of said events,
• an EventQuery type, which can be used to filter the set of all ExternalEvents associated with a given plan by their ExternalSource, derivation group, or event type.
• and an ExternalSource type, which can be used by EventQuerys to narrow down the set of events being examined by a procedure to those contained in specific sources.

To make this more explicitly clear, we will illustrate an example, based on the tests in ExternalEventsTests.java under the e2e-tests directory.

Consider this set of events:

Consider scheduling the Banananation activity BiteBanana off of these events.
This can mean a variety of different things, depending on the exact behavior we desire:

• schedule the activity coincident with all events
• schedule the activity coincident with events belonging to derivation group "TestGroup"
• schedule the activity coincident with events belonging to the second source
• schedule the activity based on events of type "Test_Type"
• schedule the activity based on events with the substring "01" in their key.

For the sake of brevity, we will explore just one case - events belonging to the second source with the substring "01" in their key. This case makes use of all of the types described above.

@SchedulingProcedure
public record ExternalEventsSourceQueryGoal() implements Goal {
  @Override
  public void run(@NotNull final EditablePlan plan) {

    // extract events belonging to the second source
    EventQuery eventQuery = new EventQuery(
        null,
        null,
        List.of(new ExternalSource("NewTest.json", "TestGroup_2"))
    );

    for (final var e: plan.events(eventQuery)) {
      // filter events that we schedule off of by key
      if (e.key.contains("01")) {
        plan.create(
            "BiteBanana",
            // place the directive such that it is coincident with the event's start
            new DirectiveStart.Absolute(e.getInterval().start),
            Map.of("biteSize", SerializedValue.of(1)));
      }
    }
    plan.commit();
  }
}

This goal does the following:

1. create an EventQuery to select events belonging to the second source. To specify that selector, we create an ExternalSource object, whose properties are the two properties necessary to uniquely identify two ExternalSources in AERIE: a key and a derivation_group_name.
2. Call plan.events(eventQuery). This returns all external events associated with a plan (based on the associated derivation groups), and filters them according to the passed-in query.
3. Filter by key. We directly access the properties of each event (namely, key) now to further match our requirements.
4. Create the activity, placing it coincident with the event's start, accessed via getInterval().start.

After running it, we get the following result in AERIE:

As expected, there is a single activity, scheduled off of an Event_01 from the second source.

Verification

The changes were verified both by testing with our own models, and subsequent testing of the 4 new types listed above in a few end-to-end tests (see ExternalEventsTests.java under the e2e-tests directory).

Documentation

Documentation will need to be added to aerie-docs to describe how scheduling using external events work. As this feature is solely an addition, no existing documentation is invalidated; the documentation is simply expanded.

Future work

The next steps for External Event work are:

• additional cleanup and optimization of External Events in the front and backend
• adding properties to events and sources, and exposing those to the scheduler
• integration with the procedural constraint system
• introduction of a formal JSON schema for events and sources and support of said schema in the database

[JoelCourtney]

Rebased to clean up the git history

[skovati]

Looks great so far! Nice work. Just have a few questions about streamlining the filtering API we're exposing to users to simplify things.