From 1a6b2e3f0e42d56728471454fb236e919a57f623 Mon Sep 17 00:00:00 2001
From: dandelany <dan.delany@gmail.com>
Date: Tue, 5 Nov 2024 16:29:58 -0800
Subject: [PATCH] small edits to events docs: comments on examples, update
 External Events page to link to scheduling docs and remove from 'coming soon'
 section

---
 docs/planning/external-events.mdx             | 21 +++++++------------
 .../procedural/scheduling/examples.mdx        |  6 ++++--
 2 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/docs/planning/external-events.mdx b/docs/planning/external-events.mdx
index 4a3871c..52b3df9 100644
--- a/docs/planning/external-events.mdx
+++ b/docs/planning/external-events.mdx
@@ -531,6 +531,13 @@ As a final note on the frontend, it is worth briefly detailing what parts of the
 - _External Event Type filters_ - the External Event Type filters selected in the timeline editor,
 - _External Event options_ - the options in the timeline editor filter.
 
+## Scheduling Activities from Events
+External events associated with a plan are accessible from the [Procedural Scheduling](../../scheduling-and-constraints/procedural/introduction/) API, just like resources and activities. This allows users to write scheduling goals which create activities based on the presence (or absence) of external events - for example, "create a downlink activity 5 minutes after the start of every 'DSN Contact' type event".
+
+To access events in a procedural goal, you must create an External Events timeline object - see [Timelines: External Events](../../scheduling-and-constraints/procedural/timelines/basics/external-events/). A full example of a scheduling goal using events can be found on the [Procedural Scheduling Examples](../../scheduling-and-constraints/procedural/scheduling/examples/#scheduling-based-off-of-external-events) page.
+
+Currently, external events are **not accessible from the [Declarative Scheduling EDSL](http://localhost:3000/aerie-docs/scheduling-and-constraints/declarative/scheduling/introduction/)** - but we may implement support for this in the future.
+
 ## What Remains
 Here, we discuss briefly everything that is not currently implemented but that we do plan to in the future.
 
@@ -554,17 +561,3 @@ It might make sense to add ownership, i.e. a given user owns an External Source
 
 That being said, as we move forward with more features relating to External Events, more nuance may come to the problem of ownership and roles. Once plans start actually depending on these plans, the rules surrounding ownership and permissions may need to change or be entirely rethought. Ultimately, we need something that justifies the implementation of such a scheme in that it provides more than the status quo.
 
-### Scheduling/Constraints
-
-This is the biggest "coming-next" feature, but also the least explored. It is planned to be part of the next batch of work relating to External Events. We would like External Events to get the same visibility that activities and resources get in the scheduling and constraints EDSLs and engines. Ideally, we could define a scheduling goal (or constraint), like the following:
-
-```
-export default () =>
-  Goal.CoexistenceGoal({
-    forEach: ExternalEventExpression.ofType(ExternalEventTypes.Eclipse),
-    activityTemplate: ActivityTemplates.SolarDisable({ rate: 0.5 }),
-    startsAt: TimingConstraint.singleton(WindowProperty.START)
-  });
-```
-
-which might be how one could write a scheduling goal to place an activity disabling a solar panel whenever an eclipse occurred.
diff --git a/docs/scheduling-and-constraints/procedural/scheduling/examples.mdx b/docs/scheduling-and-constraints/procedural/scheduling/examples.mdx
index 866dd9c..53afd76 100644
--- a/docs/scheduling-and-constraints/procedural/scheduling/examples.mdx
+++ b/docs/scheduling-and-constraints/procedural/scheduling/examples.mdx
@@ -28,6 +28,7 @@ public record ActivityRecurrenceGoal() implements Goal {
     for (final var time: plan.totalBounds().step(Duration.hours(2))) {
       if (!existingActivities.sample(time)) {
         plan.create(
+          // use NewDirective() to specify names/arguments for activities
           new NewDirective(
             // parameters
             new AnyDirective(Map.of(
@@ -115,6 +116,7 @@ public record ActivityCoexistenceGoal() implements Goal {
                 "quantity", SerializedValue.of(growQuantity)
             )
         );
+        // mock the effect of new activity on fruit resource, so we don't need to resimulate
         mockedFruit = mockedFruit.plus(Real.step(biteInterval.start, growQuantity));
       }
     }
@@ -124,7 +126,7 @@ public record ActivityCoexistenceGoal() implements Goal {
 }
 ```
 
-## Scheduling Based off of External Events
+## Scheduling From External Events
 
 Consider this set of events:
 
@@ -157,7 +159,7 @@ public record ExternalEventsSourceQueryGoal() implements Goal {
         null,
         new ExternalSource("NewTest.json", "TestGroup_2")
     );
-
+    // look for events where key contains "01"
     final var events = plan.events(eventQuery).filter(false, $ -> $.key.contains("01"));
 
     for (final var e: events) {