Skip to content

Commit

Permalink
Update tutorial for event/source attributes
Browse files Browse the repository at this point in the history
  • Loading branch information
@JosephVolosin
JosephVolosin committed Dec 9, 2024
1 parent 1c41238 commit c6e9a79
Show file tree
Hide file tree
Showing 6 changed files with 131 additions and 121 deletions.
32 changes: 18 additions & 14 deletions docs/planning/external-events/introduction.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,22 +70,11 @@ The need for these became apparent after an exploration of External Events imple
<figcaption><i>Figure 2: External Events - External Events with resources and activities</i></figcaption>
</figure>

:::info Note

Currently, External Events are *not* accessible to the automated scheduler for purposes of generating activities based on events, satisfying constraints, or other interactions with other data in Aerie. However, this is in the planned scope for External Events, and future releases will add these capabilities

:::

### External Sources
**External Sources** represent a collection of External Events. When we upload External Events, we can only do so by uploading them in an External Source.

These sources are to be defined in `JSON`, following a general format that will be discussed below. Any data a user wishes to turn into an External Source/External Events should be converted to the `JSON` format to allow ingest within Aerie.

:::info Note
These sources are defined using [JSON Schema](https://json-schema.org/) format with a [meta-schema](https://github.com/NASA-AMMOS/aerie-gateway/blob/develop/src/schemas/external-event-validation-schemata.ts) enforced to ensure certain fields such as `key` and `start_time` are present and in the correct format. Additionally, the

There is currently no well-defined, official `JSON` schema for External Source input, however there are required fields which will be mentioned below, and any non-known fields included will be ignored during ingest. Additionally, no tool currently exists to provide the generic translation to the `JSON` format, however this is a feature planned for a future release.

:::

#### Schema
There are two parts to each External Source: 1) a `source` header and 2) a collection of `events`:
Expand All @@ -102,7 +91,7 @@ There are two parts to each External Source: 1) a `source` header and 2) a colle

##### Source

The `source` field includes the following fields:
The `source` field includes the following fields, where **all** are required:

* `key`
* Unique identifier for the External Source
Expand Down Expand Up @@ -147,6 +136,21 @@ The `source` field includes the following fields:
...
```

* `attributes`
* Defines the *values* for the attributes of the External Source - these attributes are *defined* or *schematized* by the External Source Type.
* **Example**
```json
"attributes": {
"version": "1.2.3",
"week": 2,
"isTestFile": true,
"relatedPeriod": {
"startTime": "2024-001T00:00:00Z",
"endTime": "2024-008T00:00:00Z"
}
}
```

##### Events

Events are represented as a set of objects contained in a list, and each event has the following fields:
Expand Down Expand Up @@ -518,7 +522,7 @@ The External Source Manager page handles the uploading & inspection of External
</figure>

#### Creating External Source Types and External Event Types
While derivation groups are automatically created when a user uploads a source file (detailed below), External Source and Event Types require special handling, as they specify allowable attributes as well.
While derivation groups are automatically created when a user uploads a source file (detailed below), External Source and Event Types require special handling, as they specify allowable attributes as well.

To create these types, navigate to the `Types` tab in the External Source Manager.

Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/external-events/assets/external_type_manager.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/tutorials/external-events/assets/external_type_manager_successful_upload.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
39 changes: 25 additions & 14 deletions docs/tutorials/external-events/associating-derivation-groups.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,13 @@ import externalEventsTutorialTimelineEditor from './assets/external_events_tutor
import externalEventsTutorialFilterShown from './assets/external_events_tutorial_filter_shown.png';

# Associating the Derivation Group with a Plan
Now that we have some External Sources uploaded, we can utilize them within a plan to see them on a timeline (and in the future, use them to power constraints, dictate scheduling goals, etc.).
Now that we have some External Sources uploaded, we can utilize them within a plan to see them on a timeline!

:::caution Note

Prior to creating a plan, a mission model must exist - currently, the mission model is not tied directly to any external event/source features, so any mission model can be used with any external sources/events.

:::

## Creating a Plan
Start by going to the Aerie **Plan** page:
Expand All @@ -26,18 +32,21 @@ Once there, create a new plan with the following parameters:

<figure>
<img alt="The example plan's parameters" src={externalEventsTutorialPlanParameters} />
<figcaption><i><b>Note</b>: The <b>start</b> and <b>end</b> times are important here, as they are bounds that contain all the external events in the sources we uploaded!</i></figcaption>
</figure>

To create this plan, make sure that there exists _some_ mission model that can be associated with the plan. The exact model is, at present, entirely unimportant as it has no bearing on External Events functionality. The mission model used here, arbitrarily, is that of Aerie's mission model template.
:::info Note

The `start` and `end` times are important here, as they are the bounds that contain all the external events in the source we uploaded!

:::

After the plan has been created, select the plan on the table to the right, and then select **Open plan** in the pane on the left. You should be presented with a plan view that resembles the image below:
After the plan has been created, select the plan on the table to the right, and then select `Open plan` in the pane on the left. You should be presented with a plan view that resembles the image below:

<figure>
<img alt="The plans page showing an empty timeline" src={externalEventsTutorialPlanSpecificIntroPage} />
</figure>

Select the `External Sources` tab on the left, and you should see the following:
Click the drop-down menu in the top-right (currently on `Activity, Resource, External Event Types`) and select the `External Sources` tab. You should see the following:

<figure>
<img alt="External Sources pane with no associations" src={externalEventsTutorialExternalSourcesEmpty} />
Expand All @@ -46,13 +55,19 @@ Select the `External Sources` tab on the left, and you should see the following:
This panel tells us that there are no derivation groups currently linked to our plan, meaning the external events we uploaded before are not yet associated with it.

## Associating the Derivation Group
There are currently no Derivation Groups associated with this plan! While we should have one created, there aren't any that this plan is aware of. To change this, we need to click `Manage Derivation Groups`, to open the Derivation Group management modal.
Previously we created and uploaded an External Source, however our plan is currently unaware of the source's events. To change this, we need to click `Manage Derivation Groups`, to open the Derivation Group management modal.

Once here, we can now look at all of our available (currently only one) Derivation Groups and select which ones to associate with our plan. Association implies that the plan or at least the plan page is in some way aware of the fact that this Derivation Group exists (details on what exactly association entails can be found [here](../../../planning/external-events/#derivation-group-management-modal) under 'Derivation Group Management Modal').
Once here we can now look at all of our available (currently only one) Derivation Groups and select which ones to associate with our plan. Association means that the plan is aware of the fact this Derivation Group exists and is able to use it's events.

In the `Manage Derivation Groups` modal, check the check-box for our Derivation Group (`DemoType Default`). The check-box itself does not do anything yet, it requires the `Update` button at the bottom of the modal to be clicked to 'save' the linked/un-linked derivation groups.
:::info Note

Click the `Update` button to link the derivation group.
Details on what exactly association entails can be found [here](../../../planning/external-events/) under `Derivation Group Management Modal`.

:::

In the `Manage Derivation Groups` modal, check the check-box for our Derivation Group (`DemoType Default`).

Click the `Update` button to save the current Derivation Group associations.

The modal should now appear as below, with a success toast in the bottom-right corner of the screen:

Expand All @@ -71,8 +86,6 @@ On the left-pane, we can see the breakdown of External Event Counts - where the
## Creating an External Event timeline row
Now that we have a derivation group associated with our plan, we can put those external events on the timeline to visualize them.

By default, a dedicated 'External Events Row' is **not** created *unless* the user loads a plan that already existed and has at least one derivation group previously linked. In our case, because this is a new plan we must create our own row to see the events. Alternatively, a filter for the event types can also be added to a pre-existing row.

First, switch to the `Activity, Resource, & Event Types` tab.

<figure>
Expand Down Expand Up @@ -124,6 +137,4 @@ External events appear in the same layer type as activities, and as such share o

[//]: # (Examples of the two different `Group By` modes, as well as visibility enable/disable can be seen in the [Plan]&#40;../../../planning/external-events/#plan&#41; section of the main External Events documentation.)

## Additional Resources

More detail on the topics discussed in this tutorial can be found under [External Events](../../../planning/external-events)
With a Derivation Group associated to our plan, we can now run scheduling goals that incorporate External Events!
157 changes: 73 additions & 84 deletions docs/tutorials/external-events/creating-an-external-source.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import externalEventsOverlappingSources from './assets/external_events_overlapping_sources.png';

# Creating External Source & Event Types
Before creating an External Source, we must define the Source & Event types that our External Source will use. The files we create will define 1) the name of the type and 2) the schema for the type's `attributes`. These files make use of the [JSON Schema](https://json-schema.org/) format and are additionally constrained by a meta-schema.
Before creating an External Source, we must define the Source & Event types that our External Source will use. The files we create will define 1) the name of the type and 2) the schema for the type's `attributes`. These files make use of the [JSON Schema](https://json-schema.org/) format and are additionally constrained by a [meta-schema](https://github.com/NASA-AMMOS/aerie-gateway/blob/develop/src/schemas/external-event-validation-schemata.ts).

Create the following `JSON` file in an editor:

Expand Down Expand Up @@ -55,104 +55,93 @@ Create the following `JSON` files in an editor:
`External_Events_Demo_00.json`:
```json
{
"source": {
"key": "External_Events_Demo_00.json",
"source_type": "DemoType",
"valid_at": "2024-01-01T00:00:00Z",
"period": {
"start_time": "2026-001T00:00:00Z",
"end_time": "2026-007T00:00:00Z"
},
"attributes": {
"SourceExampleAttribute": "this is an example attribute"
}
"source": {
"key": "External_Events_Demo_00.json",
"source_type": "DemoType",
"valid_at": "2026-001T00:00:00Z",
"period": {
"start_time": "2026-001T00:00:00Z",
"end_time": "2026-007T00:00:00Z"
},
"events": [
{
"key": "DemoType/SampleTypeA/1",
"event_type": "SampleTypeA",
"start_time": "2026-001T12:00:00Z",
"duration": "02:00:00",
"attributes": {
"EventExampleAttribute": 1
}
},

{
"key": "DemoType/SampleTypeA/2",
"event_type": "SampleTypeA",
"start_time": "2026-002T00:00:00Z",
"duration": "01:00:00",
"attributes": {
"EventExampleAttribute": 2
}
},

{
"key": "DemoType/SampleTypeA/3",
"event_type": "SampleTypeA",
"start_time": "2026-003T12:00:00Z",
"duration": "03:00:00",
"attributes": {
"EventExampleAttribute": 1
}
}
]
"attributes": {
"SourceExampleAttribute": "this is an example attribute"
}
},
"events": [
{
"key": "DemoType/SampleTypeA/1",
"event_type": "SampleTypeA",
"start_time": "2026-001T12:00:00Z",
"duration": "02:00:00",
"attributes": {
"EventExampleAttribute": 1
}
},
{
"key": "DemoType/SampleTypeA/2",
"event_type": "SampleTypeA",
"start_time": "2026-002T00:00:00Z",
"duration": "01:00:00",
"attributes": {
"EventExampleAttribute": 2
}
},
{
"key": "DemoType/SampleTypeA/3",
"event_type": "SampleTypeA",
"start_time": "2026-003T12:00:00Z",
"duration": "03:00:00",
"attributes": {
"EventExampleAttribute": 1
}
}
]
}
```

`External_Events_Demo_01.json`:
```json
{
"source": {
"key": "External_Events_Demo_01.json",
"source_type": "DemoType",
"valid_at": "2024-01-02T00:00:00Z",
"period": {
"start_time": "2026-003T00:00:00Z",
"end_time": "2026-010T00:00:00Z"
},
"attributes": {
"SourceExampleAttribute": "this is an example attribute"
}
"source": {
"key": "External_Events_Demo_01.json",
"source_type": "DemoType",
"valid_at": "2026-004T11:00:00Z",
"period": {
"start_time": "2026-004T11:00:00Z",
"end_time": "2026-010T00:00:00Z"
},
"events": [
{
"key": "DemoType/SampleTypeA/1",
"event_type": "SampleTypeA",
"start_time": "2026-003T20:00:00Z",
"duration": "02:00:00",
"attributes": {
"EventExampleAttribute": 3
}
},
{
"key": "DemoType/SampleTypeA/3",
"event_type": "SampleTypeB",
"start_time": "2026-004T12:00:00Z",
"duration": "01:00:00",
"attributes": {
"DifferentExampleAttribute": true
}
},
{
"key": "DemoType/SampleTypeA/4",
"event_type": "SampleTypeB",
"start_time": "2026-009T20:00:00Z",
"duration": "03:00:00",
"attributes": {
"DifferentExampleAttribute": true
}
}
]
"attributes": {
"SourceExampleAttribute": "this is an example attribute"
}
},
"events": [
{
"key": "DemoType/SampleTypeB/1",
"event_type": "SampleTypeB",
"start_time": "2026-004T12:00:00Z",
"duration": "01:00:00",
"attributes": {
"DifferentExampleAttribute": true
}
},
{
"key": "DemoType/SampleTypeB/2",
"event_type": "SampleTypeB",
"start_time": "2026-009T20:00:00Z",
"duration": "03:00:00",
"attributes": {
"DifferentExampleAttribute": true
}
}
]
}
```

We are now ready to upload our test External Source files to Aerie!

:::info Note

In each of these files, the exact formatting of event keys is currently not important.
In each of these files, the exact formatting of the `key` field is currently not important.

:::

Expand Down
16 changes: 11 additions & 5 deletions docs/tutorials/external-events/uploading-an-external-source.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,19 +16,19 @@ First, we must upload the schema we created for the External Source Type & the t
<img alt="Click 'External Sources' button" src={externalEventsTutorialUploadStep1} />
</figure>

Next, click the 'Types' button in the top-right to switch to the sub-page used for creating & managing External Source & Event Types.
Next, click the `Types` button in the top-right to switch to the sub-page used for creating & managing External Source & Event Types.

<figure>
<img alt="External Type Manager" src={externalTypeManager} />
</figure>

Click 'Choose File' and select the `External_Types_Schema.json` file we previously created. The new Source Type & the two Event Types should have their names shown on the left-panel.
Click `Choose File` and select the `External_Types_Schema.json` file we previously created. The new Source Type & the two Event Types should have their names shown on the left-panel.

<figure>
<img alt="Results from successfully parsing the file" src={externalTypeManagerFileParsed} />
</figure>

Clicking 'Upload' will create the listed types!
Clicking `Upload` will create the listed types!

<figure>
<img alt="External Source type created" src={externalTypeManagerSuccessfulUpload} />
Expand All @@ -48,15 +48,21 @@ Once here, we can now upload our new External Sources. Click the **'Browse...'**
<figcaption><i>Uploaded file form should become populated</i></figcaption>
</figure>

Go ahead and leave the `Derivation Group` as `DemoType Default`.
The `Derivation Group` field allows you to change the Derivation Group that the source will associate with, for this tutorial we will leave it as `DemoType Default`.

:::info Note

For more information on Derivation Groups, refer to the [External Events](../../../planning/external-events) documentation underneath the `Derivation` section!

:::

Finally, click upload. The new External Source should show in the table on the right:

<figure>
<img alt="External Sources table is populated" src={externalEventsTutorialUploadStep3} />
</figure>

Click the 'x' next to 'Selected External Source' to deselect it, then repeat these steps with the second file. The table should now look as follows:
Click the `X` next to `Selected External Source` to deselect it, then repeat these steps with the second file. The table should now look as follows:

<figure>
<img alt="External Sources table is populated with both test files" src={externalEventsTutorialUploadStep4} />
Expand Down

0 comments on commit c6e9a79

Please sign in to comment.