diff --git a/.gitattributes b/.gitattributes
index 9ac723b..d77614c 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,4 @@
*.png filter=lfs diff=lfs merge=lfs -text
*.webm filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/workflows/generate-pdfs.yml b/.github/workflows/generate-pdfs.yml
index 059367c..0d4df9f 100644
--- a/.github/workflows/generate-pdfs.yml
+++ b/.github/workflows/generate-pdfs.yml
@@ -1,6 +1,9 @@
name: Generate PDFs
on:
+ push:
+ tags:
+ - v*
workflow_dispatch:
jobs:
diff --git a/docs/api/assets/api-playground-admin-secret.mov b/docs/api/assets/api-playground-admin-secret.mov
new file mode 100644
index 0000000..8448c47
--- /dev/null
+++ b/docs/api/assets/api-playground-admin-secret.mov
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ce3914cb1baa1963297b0cc293bfbadf8f3b7d8ee695175afddb2ff1b39ea1b5
+size 2121965
diff --git a/docs/api/assets/api-playground-headers.png b/docs/api/assets/api-playground-headers.png
deleted file mode 100644
index 5f31267..0000000
--- a/docs/api/assets/api-playground-headers.png
+++ /dev/null
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:c22d0e4baa3868e56cb8fa26754dca671ca6cfbc1e45b1b4d41ac1a20415103e
-size 565176
diff --git a/docs/api/assets/api-playground-pre-request-script.mov b/docs/api/assets/api-playground-pre-request-script.mov
new file mode 100644
index 0000000..08747fd
--- /dev/null
+++ b/docs/api/assets/api-playground-pre-request-script.mov
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:79eddeb20cf03fa9fb0ad8ce0398c5ac7a7ed318805ce45fc44b69a1e5984600
+size 2768358
diff --git a/docs/api/examples/advanced-extensions.mdx b/docs/api/examples/advanced-extensions.mdx
new file mode 100644
index 0000000..e667cfa
--- /dev/null
+++ b/docs/api/examples/advanced-extensions.mdx
@@ -0,0 +1,82 @@
+# Extensions
+
+## Adding an Extension
+
+```graphql
+mutation InsertExtension($extension: extensions_insert_input!) {
+ insert_extensions_one(object: $extension) {
+ id
+ label
+ url
+ description
+ }
+}
+```
+
+Below is an example query variable that creates an extension called "My External Application".
+
+```json
+{
+ "extension": {
+ "label": "My External Application",
+ "url": "https://externalapp/api/test",
+ "description": "An application that exists outside of Aerie."
+ }
+}
+```
+
+## Permitting Roles to run Extensions
+
+```graphql
+mutation InsertExtensionRoles($roles: [extension_roles_insert_input!]!) {
+ insert_extension_roles(objects: $roles) {
+ returning {
+ extension {
+ id
+ label
+ }
+ role
+ }
+ }
+}
+```
+
+Below is an example query variable that grants the `aerie_admin` and `user` roles to run the extension with an ID of 1.
+
+```json
+{
+ "roles": [
+ { "extension_id": 1, "role": "aerie_admin" },
+ { "extension_id": 1, "role": "user" }
+ ]
+}
+```
+
+## Deleting an Extension
+
+```graphql
+mutation DeleteExtension($extension_id: Int!) {
+ delete_extensions_by_pk(id: $extension_id) {
+ id
+ }
+}
+```
+
+## Get Extensions With Roles
+
+```graphql
+query GetExtensions {
+ extensions {
+ description
+ extension_roles {
+ id
+ role
+ }
+ id
+ label
+ url
+ }
+}
+```
+
+Invocation payloads are discussed on [Planning / Advanced - Extensions](/planning/advanced-extensions).
diff --git a/docs/api/examples/constraints.md b/docs/api/examples/constraints.md
deleted file mode 100644
index 9b533eb..0000000
--- a/docs/api/examples/constraints.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Constraints
-
-## Check Constraints
-
-```graphql
-query CheckConstraints($planId: Int!, $simulationDatasetId: Int) {
- checkConstraintsResponse: constraintViolations(planId: $planId, $simulationDatasetId: simulationDatasetId) {
- violations
- }
-}
-```
-
-Returns a list of constraint violations for a given plan by `$planId`. The violations will include the corresponding constraint name, type, and id. An optional `$simulationDatasetId` can be provided which limits the constraint violation checking to a single simulation dataset, which is useful when external datasets are added that only reference a single simulation dataset, as constraint violations would otherwise be reported for every uploaded external dataset.
-
-## Create Constraint
-
-```graphql
-mutation CreateConstraint($constraint: constraint_insert_input!) {
- insert_constraint_one(object: $constraint) {
- id
- }
-}
-```
-
-The `$constraint` query variable has the following type definition:
-
-```ts
-type Constraint = {
- definition: string;
- description: string;
- model_id: number | null;
- name: string;
- plan_id: number | null;
- summary: string;
-};
-```
-
-## Update Single Constraint
-
-```graphql
-mutation UpdateConstraint($id: Int!, $constraint: constraint_set_input!) {
- update_constraint_by_pk(pk_columns: { id: $id }, _set: $constraint) {
- id
- }
-}
-```
-
-The `$constraint` query variable has the same type definition as the [create constraint](#create-constraint) query above, but less strict. You can leave properties out that you do not need to update.
-
-## Delete Constraint
-
-```graphql
-mutation DeleteConstraint($id: Int!) {
- delete_constraint_by_pk(id: $id) {
- id
- }
-}
-```
diff --git a/docs/api/examples/constraints.mdx b/docs/api/examples/constraints.mdx
new file mode 100644
index 0000000..e25e29f
--- /dev/null
+++ b/docs/api/examples/constraints.mdx
@@ -0,0 +1,318 @@
+# Constraints
+
+## Check Constraints
+
+```graphql
+query CheckConstraints($planId: Int!, $simulationDatasetId: Int) {
+ constraintViolations(planId: $planId, simulationDatasetId: $simulationDatasetId) {
+ constraintId
+ constraintName
+ constraintRevision
+ success
+ results {
+ violations {
+ activityInstanceIds
+ windows {
+ end
+ start
+ }
+ }
+ gaps {
+ end
+ start
+ }
+ resourceIds
+ }
+ errors {
+ stack
+ message
+ location {
+ column
+ line
+ }
+ }
+ }
+}
+```
+
+Returns a list of constraint violations for a given plan by `$planId`.
+The violations will include the corresponding constraint name, type, and id. An optional `$simulationDatasetId` can be provided which limits the constraint violation checking to a single simulation dataset, which is useful when external datasets are added that only reference a single simulation dataset, as constraint violations would otherwise be reported for every uploaded external dataset.
+
+## Create Constraint
+
+
+ For Aerie deployments before v2.4.0
+
+ ```graphql
+ mutation CreateConstraint($constraint: constraint_insert_input!) {
+ insert_constraint_one(object: $constraint) {
+ id
+ }
+ }
+ ```
+
+ The `$constraint` query variable has the following type definition:
+
+ ```ts
+ type Constraint = {
+ definition: string;
+ description: string;
+ model_id: number | null;
+ name: string;
+ plan_id: number | null;
+ summary: string;
+ };
+ ```
+
+
+
+```graphql
+mutation CreateConstraint($constraint: constraint_metadata_insert_input!) {
+ insert_constraint_metadata_one(object: $constraint) {
+ id
+ public
+ description
+ versions {
+ definition
+ }
+ }
+}
+```
+
+The `$constraint` query variable has the following structure:
+
+```json
+{
+ "constraint": {
+ "name": string,
+ "public": boolean, // Default false
+ "description": string, // Optional
+ "versions": {
+ "data": {
+ "definition": string // EDSL Code
+ }
+ }
+ }
+}
+```
+
+The `public` field controls whether all users can add your constraint to their constraint specifications
+or if only you can do that.
+Additionally, if `public` is set to `true`, the constraint _must_ have a unique name.
+
+The `description` field, if present, contains a human-readable description of the constraint.
+
+The `definition` field contains your EDSL constraint code.
+
+## Update Constraint Metadata
+
+***Introduced in v2.4.0***
+
+A constraint's metadata includes its name, public status, owner, and description.
+In order to update a constraint's metadata, you must be either an admin user or the owner of the constraint.
+
+```graphql
+mutation UpdateConstraintMetadata($id: Int!, $constraint: constraint_set_input!) {
+ update_constraint_by_pk(pk_columns: { id: $id }, _set: $constraint) {
+ id
+ }
+}
+```
+
+The `$constraint` query variable has the same type definition as the [create constraint](#create-constraint) query above, but less strict. You can leave properties out that you do not need to update.
+
+## Add Constraint Version
+
+***Introduced in v2.4.0***
+
+Constraint definitions are versioned and cannot be changed once created.
+
+```graphql
+mutation AddConstraintVersion($constraintId: Int!, $definition: String!) {
+ insert_constraint_definition_one(object: {constraint_id: $constraintId, definition: $definition}) {
+ revision
+ }
+}
+```
+
+## Delete Constraint Version
+
+***Introduced in v2.4.0***
+
+In order to delete a constraint version, it must not be in use on any constraint specifications (see [below](#manage-constraint-specifications)).
+
+```graphql
+mutation DeleteConstraintVersion($constraintId: Int!, $revsion: Int!) {
+ delete_constraint_definition_by_pk(constraint_id: $constraintId, revision: $revsion){
+ definition
+ }
+}
+```
+
+## Delete Constraint
+
+
+ For Aerie deployments before v2.4.0
+
+ ```graphql
+ mutation DeleteConstraint($id: Int!) {
+ delete_constraint_by_pk(id: $id) {
+ id
+ }
+ }
+ ```
+
+
+
+In order to delete a constraint, it must not be in use on any constraint specifications (see [below](#manage-constraint-specifications)).
+
+```graphql
+mutation DeleteConstraint($id: Int!) {
+ delete_constraint_metadata_by_pk(id: $id){
+ id
+ }
+}
+```
+
+## Manage Constraint Specifications
+
+***Introduced in v2.4.0.***
+
+There are two types of constraint specifications in Aerie:
+a **model specification** and a **plan specification**.
+
+- A **constraint plan specification** is the set of constraints that
+will be checked against the plan when you [Check Constraints](#check-constraints).
+- A **constraint model specification** is used as a guideline for
+the constraint specification of every plan that uses the model.
+All new plans created from this model will start with their constraint
+specification prepopulated with the contents of their model's constraint specification.
+Note that updating a model's constraint specification will not automatically update
+the constraint specification of plans using the model.
+
+### Add Constraint to Model Specification
+
+```graphql
+mutation AddConstraintModelSpec($constraint: constraint_model_specification_insert_input!) {
+ insert_constraint_model_specification_one(object: $constraint) {
+ model_id
+ constraint_id
+ constraint_revision
+ }
+}
+```
+
+The `$constraint` query variable has the following structure.
+
+```json
+{
+ "model_id": integer,
+ "constraint_id": integer,
+ "constraint_revision": integer, // optional
+}
+```
+
+The `constraint_revision` field is used to specify which version of the constraint to use when checking constraints.
+If absent, the latest version of the constraint will be used.
+
+### Update Constraint Version on a Plan Specification
+
+Excluding the revision will set the recommended version of the constraint to the latest version.
+
+```graphql
+mutation SetConstraintVersion($modelId: Int!, $constraintId: Int!, $constraintVersion: Int) {
+ update_constraint_model_specification_by_pk(
+ pk_columns: {model_id: $modelId, constraint_id: $constraintId},
+ _set: {constraint_revision: $constraintVersion}
+ ) {
+ model_id
+ constraint_id
+ constraint_revision
+ }
+}
+```
+
+### Remove a Constraint from the Model Specification
+
+```graphql
+mutation RemoveConstraintFromModelSpec($modelId: Int!, $constraintId: Int!) {
+ delete_constraint_model_specification_by_pk(model_id: $modelId, constraint_id: $constraintId) {
+ constraint_id
+ }
+}
+```
+
+### Add Constraint to Plan Specification
+
+```graphql
+mutation AddConstraintPlanSpec($constraint: constraint_specification_insert_input!) {
+ insert_constraint_specification_one(object: $constraint) {
+ plan_id
+ enabled
+ constraint_id
+ constraint_revision
+ }
+}
+```
+
+The `$constraint` query variable has the following structure.
+
+```json
+{
+ "plan_id": integer,
+ "constraint_id": integer,
+ "constraint_revision": integer, // optional
+ "enabled": boolean, // optional, defaults to true
+}
+```
+
+The `constraint_revision` field is used to specify which version of the constraint to use when checking constraints.
+If absent, the latest version of the constraint will be used.
+
+The `enabled` field controls whether a constraint will be checked.
+
+### Update Constraint Version on a Plan Specification
+
+Excluding the revision will set the plan to use the latest version of the constraint.
+
+```graphql
+mutation SetConstraintVersion($planId: Int!, $constraintId: Int!, $constraintVersion: Int) {
+ update_constraint_specification_by_pk(
+ pk_columns: {plan_id: $planId, constraint_id: $constraintId},
+ _set: {constraint_revision: $constraintVersion}
+ ) {
+ plan_id
+ constraint_id
+ constraint_revision
+ enabled
+ }
+}
+```
+
+### Enable/Disable Constraints on a Plan Specification
+
+Constraints that are disabled will not be checked when checking constraints.
+
+```graphql
+mutation SetConstraintVersion($planId: Int!, $constraintId: Int!, $enabled: Boolean!) {
+ update_constraint_specification_by_pk(
+ pk_columns: {plan_id: $planId, constraint_id: $constraintId},
+ _set: {enabled: $enabled}
+ ) {
+ plan_id
+ constraint_id
+ constraint_revision
+ enabled
+ }
+}
+```
+
+### Remove a Constraint from the Plan Specification
+
+```graphql
+mutation RemoveConstraintFromSpec($planId: Int!, $constraintId: Int!) {
+ delete_constraint_specification_by_pk(plan_id: $planId, constraint_id: $constraintId) {
+ constraint_id
+ }
+}
+```
diff --git a/docs/api/examples/planning/collaboration.md b/docs/api/examples/planning/collaboration.md
index 6fd62e9..01af4fb 100644
--- a/docs/api/examples/planning/collaboration.md
+++ b/docs/api/examples/planning/collaboration.md
@@ -15,10 +15,12 @@ In order to perform scheduling tasks on a branch, it is necessary to also [creat
## Create Merge Request
```graphql
-mutation CreateMergeRequest($requester_username: String!, $source_plan_id: Int!, $target_plan_id: Int!) {
+mutation CreateMergeRequest($source_plan_id: Int!, $target_plan_id: Int!) {
create_merge_request(
- args: { requester_username: $requester_username, target_plan_id: $target_plan_id, source_plan_id: $source_plan_id }
- ) {
+ args: {
+ target_plan_id: $target_plan_id,
+ source_plan_id: $source_plan_id
+ }) {
merge_request_id
}
}
@@ -31,7 +33,7 @@ A withdrawn merge request cannot be used to begin a merge.
```graphql
mutation WithdrawMergeRequest($merge_request_id: Int!) {
- withdraw_merge_request(args: { merge_request_id: $merge_request_id }) {
+ withdraw_merge_request(args: {_merge_request_id: $merge_request_id}) {
merge_request_id
}
}
@@ -44,11 +46,11 @@ Beginning a merge locks the target plan until the merge is either cancelled, den
Once you have a `pending` merge request between two plans, you can use the following mutation to begin the merge:
```graphql
-mutation BeginMerge($reviewer_username: String!, $merge_request_id: Int!) {
- begin_merge(args: { reviewer_username: $reviewer_username, merge_request_id: $merge_request_id }) {
+mutation BeginMerge($merge_request_id: Int!) {
+ begin_merge(args: {_merge_request_id: $merge_request_id}) {
merge_request_id
- conflicting_activities
non_conflicting_activities
+ conflicting_activities
}
}
```
@@ -56,8 +58,8 @@ mutation BeginMerge($reviewer_username: String!, $merge_request_id: Int!) {
By default, the above mutation will return the list of non-conflicting activities and the list of conflicting activities. If you would like neither, you can instead perform the following mutation:
```graphql
-mutation BeginMerge($reviewer_username: String!, $merge_request_id: Int!) {
- begin_merge(args: { reviewer_username: $reviewer_username, merge_request_id: $merge_request_id }) {
+mutation BeginMerge($merge_request_id: Int!) {
+ begin_merge(args: {_merge_request_id: $merge_request_id}) {
merge_request_id
}
}
@@ -67,7 +69,7 @@ If you want the list of non-conflicting activities of an in-progress merge at a
```graphql
query GetNonConflictingActivities($merge_request_id: Int!) {
- get_non_conflicting_activities(args: { merge_request_id: $merge_request_id }) {
+ get_non_conflicting_activities(args: {_merge_request_id: $merge_request_id}) {
activity_id
change_type
source
@@ -80,7 +82,7 @@ If you want the list of conflicting activities of an in-progress merge, perform
```graphql
query GetConflictingActivities($merge_request_id: Int!) {
- get_conflicting_activities(args: { merge_request_id: $merge_request_id }) {
+ get_conflicting_activities(args: {_merge_request_id: $merge_request_id}) {
activity_id
change_type_source
change_type_target
@@ -98,7 +100,9 @@ You can cancel any `in-progress` merge.
```graphql
mutation CancelMerge($merge_request_id: Int!) {
- cancel_merge(args: { merge_request_id: $merge_request_id })
+ cancel_merge(args: { _merge_request_id: $merge_request_id }) {
+ merge_request_id
+ }
}
```
@@ -138,7 +142,9 @@ It is possible to deny an in-progress merge, for example, if a request is outdat
```graphql
mutation DenyMerge($merge_request_id: Int!) {
- deny_merge(args: { merge_request_id: $merge_request_id })
+ deny_merge(args: { merge_request_id: $merge_request_id }) {
+ merge_request_id
+ }
}
```
@@ -148,6 +154,8 @@ Once all conflicts have been resolved, you can commit a merge.
```graphql
mutation CommitMerge($merge_request_id: Int!) {
- commit_merge(args: { merge_request_id: $merge_request_id })
+ commit_merge(args: { _merge_request_id: $merge_request_id }) {
+ merge_request_id
+ }
}
```
diff --git a/docs/api/examples/planning/introduction.mdx b/docs/api/examples/planning/introduction.mdx
index 950f4e9..35550d4 100644
--- a/docs/api/examples/planning/introduction.mdx
+++ b/docs/api/examples/planning/introduction.mdx
@@ -61,13 +61,11 @@ The `start_time` is in the [day-of-year](https://nsidc.org/data/user-resources/h
:::info
-If you want to run **simulation** against your plan you need to [update the simulation configuration](../../simulation#update-a-simulation-configuration) with the bounds you want to run simulation over.
-
-If you want to run **scheduling** against your plan you need to [create an associated scheduling specification](../../scheduling#create-scheduling-specification) respectively.
+If you want to run **scheduling** against your plan you need to [create an associated scheduling specification](../../scheduling#create-scheduling-specification).
:::
-## Query for All Activity Directives (aka Instances) for a Plan
+## Query for All Activity Directives for a Plan
Notice how in this query we get the same `plan` data as the previous query, but also the nested `activity_directives`. If you are familiar with relational databases you can think of this as a join query between the `plan` table and `activity_directive` table (in Hasura these joins are made via [relationships](https://hasura.io/learn/graphql/hasura/relationships/)). This is the secret sauce behind GraphQL. It allows us to query for deeply-nested data across the Aerie system in a single unified way.
@@ -132,3 +130,111 @@ query GetActivityTypesForPlan($id: Int!) {
}
}
```
+
+## Create Activity Directive
+
+TODO: Finish
+
+```graphql
+mutation CreateDirectives($directives: [activity_directive_insert_input!]! ) {
+ insert_activity_directive(objects: $directives) {
+ returning {
+ id
+ start_offset
+ }
+ }
+}
+```
+
+The query variable `directives` is a list of activity directives.
+Each directive has the following shape:
+```json
+{
+ "name": string, // optional
+ "plan_id": integer,
+ "type": string,
+ "start_offset": duration, // format: "HH:MM:SS.sss"
+ "arguments": jsonb
+}
+```
+
+## Query for Activity Effective Arguments
+
+This query returns a set of effective arguments given a set of required (and overridden) arguments.
+
+```graphql
+query GetEffectiveArgs($modelId: ID!, $activityType: String!, $arguments: ActivityArguments!) {
+ getActivityEffectiveArguments(
+ missionModelId: $modelId
+ activityTypeName: $activityType
+ activityArguments: $arguments
+ ) {
+ arguments
+ errors
+ success
+ }
+}
+```
+
+For example, running the query with the arguments of:
+
+```json
+{
+ "modelId": 1,
+ "activityType": "BakeBananaBread",
+ "arguments": { "tbSugar": 1, "glutenFree": false }
+}
+```
+
+Results in:
+
+```json
+{
+ "data": {
+ "getActivityEffectiveArguments": {
+ "arguments": {
+ "glutenFree": false,
+ "tbSugar": 1,
+ "temperature": 350
+ },
+ "success": true
+ }
+ }
+}
+```
+
+When a required argument is not provided, the returned JSON will indicate which argument is missing.
+With ``examples/banananation``'s ``BakeBananaBread``, where only the ``temperature`` parameter has a default value:
+
+```graphql
+{
+ "modelId": 1,
+ "activityType": "BakeBananaBread",
+ "arguments": {}
+}
+```
+
+Results in:
+
+```json
+{
+ "data": {
+ "getActivityEffectiveArguments": {
+ "arguments": {
+ "temperature": 350
+ },
+ "errors": {
+ "tbSugar": {
+ "schema": {"type": "int"} ,
+ "message": "Required argument for activity \"BakeBananaBread\" not provided: \"tbSugar\" of type ValueSchema.INT"
+ },
+ "glutenFree": {
+ "schema": {"type": "boolean"},
+ "message": "Required argument for activity \"BakeBananaBread\" not provided: \"glutenFree\" of type ValueSchema.BOOLEAN"
+ }
+ },
+ "success": false
+ }
+ }
+}
+```
diff --git a/docs/api/examples/planning/snapshots.mdx b/docs/api/examples/planning/snapshots.mdx
new file mode 100644
index 0000000..c99bcfe
--- /dev/null
+++ b/docs/api/examples/planning/snapshots.mdx
@@ -0,0 +1,74 @@
+# Snapshots
+
+A snapshot of a plan is a named record of the state of all activities in a plan at a certain time.
+Snapshots are useful for recording and returning to known "good" states of a plan.
+
+## Taking a Snapshot
+
+```graphql
+mutation createSnapshot($planId: Int!, $snapshotName: String!, $description: String) {
+ create_snapshot(args: {
+ _plan_id: $planId,
+ _snapshot_name: $snapshotName,
+ _description: $description
+ }) {
+ snapshot_id
+ }
+}
+```
+
+Below is an example set of query variables for this function. Note that `description` is optional and may be excluded.
+
+```json
+{
+ "planId": 1,
+ "snapshotName": "Snapshot of My Plan",
+ "description": "Optional description for this snapshot"
+}
+```
+
+## Tagging a Snapshot
+
+[Tags](../../tags) can be applied to snapshots.
+
+### Adding a Tag
+
+```graphql
+mutation AddPlanSnapshotTag($snapshotId:Int!, $tagId: Int!){
+ insert_plan_snapshot_tags_one(object: {snapshot_id: $snapshotId, tag_id: $tagId}) {
+ plan_snapshot {
+ snapshot_name
+ description
+ }
+ tag {
+ name
+ color
+ owner
+ }
+ }
+}
+```
+
+### Removing a Tag
+
+```graphql
+mutation RemovePlanSnapshotTag($snapshotId: Int!, $tagId: Int!) {
+ delete_plan_snapshot_tags_by_pk(snapshot_id: $snapshotId, tag_id: $tagId) {
+ plan_snapshot {
+ snapshot_name
+ description
+ }
+ tag { name }
+ }
+}
+```
+
+## Restoring a Snapshot
+
+```graphql
+mutation restoreSnapshot($planId: Int!, $snapshotId: Int!) {
+ restore_from_snapshot(args: {_plan_id: $planId, _snapshot_id: $snapshotId}) {
+ snapshot_id
+ }
+}
+```
diff --git a/docs/api/examples/simulation.mdx b/docs/api/examples/simulation.mdx
index 2428c53..a54c855 100644
--- a/docs/api/examples/simulation.mdx
+++ b/docs/api/examples/simulation.mdx
@@ -21,6 +21,22 @@ mutation updateSimulationArguments($plan_id: Int!, $arguments: jsonb!) {
}
```
+Query for Mission Model Configuration Effective Arguments
+---------------------------------------------------------
+
+The `getModelEffectiveArguments` returns the same structure as [`getActivityEffectiveArguments`](../planning/introduction#query-for-activity-effective-arguments);
+a set of effective arguments given a set of required (and overridden) arguments.
+
+```graphql
+query getModelEffectiveArgs($modelId: ID!, $arguments: ModelArguments!) {
+ getModelEffectiveArguments(missionModelId: $modelId, modelArguments: $arguments) {
+ arguments
+ errors
+ success
+ }
+}
+```
+
## Update Simulation Bounds
By default, a simulation will go from plan start to plan end. If you would like to run simulation on only a subset of the plan, you must first update the simulation bounds in the Simulation Configuration.
@@ -102,6 +118,22 @@ query Simulate($planId: Int!) {
}
```
+### Forcibly Rerun Simulation
+
+Occasionally, there may be a need to resimulate a plan without changing any arguments,
+for example if there was a network failure during a prior run.
+In these cases, simulation can be forcibly rerun by providing the `force` argument to the `simulate` endpoint.
+
+```graphql
+query ForceResimulate($planId: Int!) {
+ simulate(planId: $planId, force: true) {
+ reason
+ simulationDatasetId
+ status
+ }
+}
+```
+
## Query for Simulation Results
The output of a simulation is stored in a `simulation_dataset`. A `simulation_dataset` has both profiles (aka states or resources), and simulated activities.
@@ -164,6 +196,50 @@ query GetProfileSegments($datasetId: Int!) {
}
```
+You can further filter this query to only fetch a subset of profiles:
+
+```graphql
+query GetProfileSegments($dataset_id: Int!, $resources: [String!]!) {
+ profile(where: {_and: {name: {_in: $resources}, dataset_id: {_eq: $dataset_id}}}) {
+ name
+ profile_segments {
+ profile_id
+ dynamics
+ start_offset
+ }
+ }
+}
+```
+
+### Query for Simulated Activities (Spans)
+
+For performance, it can sometimes be beneficial to request the simulated activity directives (otherwise known as "simulated activities" or "spans") separately.
+
+```graphql
+query GetSpans($simulationDatasetId: Int!) {
+ simulated_activity(where: {simulation_dataset_id: {_eq: $simulationDatasetId}}) {
+ activity_type_name
+ attributes
+ duration
+ id
+ parent_id
+ simulation_dataset_id
+ start_offset
+ }
+}
+```
+
+## Query for Resource Types in a Mission Model
+
+```graphql
+query GetResourceTypes($modelId: Int!) {
+ resource_type(where: {model_id: {_eq: $modelId}}) {
+ name
+ schema
+ }
+}
+```
+
## Query for Simulation Resource Data at a Given Time
Once a simulation has been run, you can query for the profile segments at a certain duration into the results.
diff --git a/docs/api/examples/tags.md b/docs/api/examples/tags.md
new file mode 100644
index 0000000..9733341
--- /dev/null
+++ b/docs/api/examples/tags.md
@@ -0,0 +1,52 @@
+# Tags
+
+Tags are metadata that can be used to mark certain things in Aerie, including Plans, Plan Snapshots, Activity Directives, Scheduling Goals, Constraints, and Command Expansion Runs.
+Tags are shared across an Aerie instance.
+
+## Creating a Tag
+
+```graphql
+mutation CreateTag($name: String!, $color: String) {
+ insert_tags_one(object: {name: $name, color: $color}) {
+ id
+ name
+ color
+ }
+}
+```
+
+The `color` field is optional, however, if specified, it must be a hex color code.
+This field is used to determine what color the tag appears as when displayed in the UI.
+
+## Updating a Tag
+
+```graphql
+mutation UpdateTag($tagId: Int!, $set: tags_set_input!) {
+ update_tags_by_pk(pk_columns: {id: $tagId}, _set: $set) {
+ id
+ name
+ color
+ owner
+ }
+}
+```
+
+The `set` object is a JSON containing any of the following fields:
+ - `name`: the new name for the tag
+ - `owner`: the new owner of the tag
+ - `color`: either `null` or a hex color code
+
+## Deleting a Tag
+
+```graphql
+mutation DeleteTag($tagId: Int!) {
+ delete_tags_by_pk(id: $tagId) {
+ id
+ name
+ color
+ owner
+ }
+}
+```
+
+
diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx
index 6846090..6b7fd00 100644
--- a/docs/api/introduction.mdx
+++ b/docs/api/introduction.mdx
@@ -1,7 +1,8 @@
import apiPlayground from './assets/api-playground.png';
-import apiPlaygroundHeaders from './assets/api-playground-headers.png';
import gatewayAuthLogin from './assets/gateway-auth-login.png';
import hasuraConsoleLogin from './assets/hasura-console-login.png';
+import adminSecretPlayground from './assets/api-playground-admin-secret.mov';
+import preRequestScript from './assets/api-playground-pre-request-script.mov';
# Introduction
@@ -71,7 +72,7 @@ To interact with the API you need to be authenticated. For each request Hasura r
To get a token from the gateway UI you can visit [http://localhost:9000/#/Auth/post_auth_login](http://localhost:9000/#/Auth/post_auth_login), and enter your JPL username and password (change `localhost` do your deployment URL if you are running Aerie on a different domain).
-
+Figure 1: Aerie Gateway UI - Auth Login
@@ -116,28 +117,135 @@ If you are using Aerie locally, or have the [admin secret](https://hasura.io/doc
Since a GraphQL API has more underlying structure than a REST API, there are a range of methods by which a client application may choose to interact with the API. A simple usage could use the [curl](https://curl.se/) command line tool, whereas a full featured web application may integrate a more powerful client library like [Apollo Client](https://www.apollographql.com/docs/react/) or [Relay](https://relay.dev/) which automatically handle query building, batching and caching.
+
+The Hasura Console
+
+Previously our recommendation was to use the Hasura Console to explore the Aerie API. As of Aerie `1.7.0` the Hasura Console requires the admin secret to access, which makes it unavailable to most for non-local use cases.
+If you have the admin secret you can still use the Hasura Console by supplying the secret on the login page.
+
+
+
+ Figure 4: Aerie Hasura Console - Admin Login
+
+
+
### Playground
Aerie provides an API playground via the [Altair](https://altairgraphql.dev/) GraphQL client. You can use the playground user interface to query the Aerie API directly. It is a great way to start exploring Aerie data and get familiar with GraphQL. If you are running Aerie locally you can view the playground (via the gateway server) at [http://localhost:9000/api-playground/](http://localhost:9000/api-playground/) (change the `localhost` domain as needed).
-
+Figure 2: Aerie API Playground - Altair
-To use the API playground you need to set the proper authorization header (either `Authorization` or `x-hasura-admin-secret` - see the [Authentication section above](#authentication)). Here is an example on how to set either one in the playground:
+To use the API playground you need to set the proper authorization header (either `Authorization` or `x-hasura-admin-secret` - see the [Authentication section above](#authentication)).
-
-
- Figure 3: Aerie API Playground - Altair Authorization Headers
-
+#### Admin Secret
-Previously our recommendation was to use the Hasura Console to explore the Aerie API. As of Aerie `1.7.0` the Hasura Console requires the admin secret to access, which makes it unavailable to most for non-local use cases. If you have the admin secret you can still use the Hasura Console by supplying the secret on the login page.
+Access the Global Environment by clicking on "No Environment" -> "Environments..." in the top-right of the page.
+Set it to the following:
-
-
- Figure 4: Aerie Hasura Console - Admin Login
-
+```json
+{
+ "headers" :
+ {
+ "x-hasura-admin-secret": "",
+ "x-hasura-user-id": "",
+ "x-hasura-role": "viewer"
+ }
+}
+```
+
+
+
+#### Authorization
+
+If you do not know the admin secret for your venue, you can instead run a pre-request script to authorize yourself against the Gateway.
+
+
+ For Aerie versions before v2.2.0
+
+1. Access the Global Environment by clicking on "No Environment" -> "Environments..." in the top-right of the page.
+Set it to the following:
+```json
+{
+ "headers" :
+ {
+ "Authorization": "Bearer {{user}}",
+ "x-hasura-role": "viewer"
+ }
+}
+```
+
+2. In the Query Window, click on Pre-request. Select Enable Pre-request script.
+
+
+3. Enter the following pre-request script:
+```js
+// Fetch a new token from the Gateway
+const res = await altair.helpers.request(
+ 'POST',
+ '/auth/login', // AUTH ENDPOINT OF THE DEPLOYMENT
+ {
+ body: { "username": "", "password": ""}, // CREDENTIALS TO LOG IN AS
+ headers: {"Content-Type": "application/json"}
+ });
+if(res.success) {
+ const token = res.token;
+ await altair.helpers.setEnvironment("user", token);
+} else {
+ altair.log(res);
+}
+```
+
+The Playground will now automatically fetch an updated token before each query.
+To learn more about pre-request scripts, visit [the Altair GQL docs](https://altairgraphql.dev/docs/features/prerequest-scripts.html).
+
+
+
+
+
+:::info Note
+If you find yourself asked to install the extension `altair-graphql-plugin-graphql-explorer`, allow this.
+This extension allows you to view and explore the GQL schema by opening the `GraphiQL Explorer` using the button midway down the left-side sidebar.
+The Explorer is useful for discovering and constructing available queries, mutations, and subscriptions.
+:::
+
+In the Query Window, click on "Pre-Request". Find this part of the script:
+
+```typescript
+const res = await altair.helpers.request(
+ 'POST',
+ '/auth/login', // AUTH ENDPOINT OF THE DEPLOYMENT
+ {
+ body: { "username": "", "password": ""}, // CREDENTIALS TO LOG IN AS
+ headers: {"Content-Type": "application/json"}
+ });
+```
+
+Replace `` and `` with the username and password you use to sign in to Aerie.
+
+:::info Setting Your Role
+By default, you will make queries using the `viewer` role. If you want to use a different role,
+select `Set Headers` from the top of the left-side sidebar and update the header `x-hasura-role` to a different role you are permitted to use.
+
+To see the list of your permitted roles, use the following query:
+```gql
+{
+ users_and_roles {
+ username
+ hasura_allowed_roles
+ }
+}
+```
+
+After changing your role, you will need to press the `Reload Docs` button to the left of the `Send Request` button
+to update the list of available queries and mutations in the GraphiQL Explorer.
+:::
### Python
@@ -156,7 +264,7 @@ response = requests.post(
print(json.dumps(response.json(), indent=2))
```
-If you have the admin secret you can just use it to make your request. Set the `x-hasura-admin-secret` header (default admin secret shown below):
+If you have the admin secret you can alternatively use it to make your request. Set the `x-hasura-admin-secret` header (default admin secret shown below):
```python
headers={ 'x-hasura-admin-secret': 'aerie' }
diff --git a/docs/command-expansion/expansion-rules.mdx b/docs/command-expansion/expansion-rules.mdx
index bf82726..aabeac3 100644
--- a/docs/command-expansion/expansion-rules.mdx
+++ b/docs/command-expansion/expansion-rules.mdx
@@ -15,9 +15,7 @@ Click on "New" above the table to the right to create a new expansion rule.
-
- Figure 1: Aerie UI Expansion Rules Page - View, create, or delete expansion rules
-
+ Figure 1: Aerie UI Expansion Rules Page - View, create, or delete expansion rules
## Authoring
@@ -29,7 +27,7 @@ Once the activity type is selected, its parameters can be accessed within the ex
- Figure 2: Aerie UI Expansion Rules Editor
+ Figure 2: Aerie UI Expansion Rules Editor
An expansion rule starts with some boilerplate code, and users are expected to add their commands as comma-separated objects in a `return []` statement structured as the following:
@@ -53,12 +51,12 @@ Values for ENUMs will be listed as strings, and must be input as strings. See th
- Figure 3: Aerie UI Expansion Rules Editor - Command Autocomplete
+ Figure 3: Aerie UI Expansion Rules Editor - Command Autocomplete
- Figure 4: Aerie UI Expansion Rules Editor - Command Arguments Error
+ Figure 4: Aerie UI Expansion Rules Editor - Command Arguments Error
The true power of command expansion is to be able to map activity parameter values to command arguments.
@@ -71,9 +69,7 @@ Note that expansion request will replace these with actual values from simulated
-
- Figure 5: Aerie UI Expansion Rules Editor - Passing Command Arguments from Activity
-
+ Figure 5: Aerie UI Expansion Rules Editor - Passing Command Arguments from Activity
Expansion rules can also access computed attributes of an activity.
diff --git a/docs/command-expansion/expansion-sets.mdx b/docs/command-expansion/expansion-sets.mdx
index e9d06a2..9d0867c 100644
--- a/docs/command-expansion/expansion-sets.mdx
+++ b/docs/command-expansion/expansion-sets.mdx
@@ -18,7 +18,7 @@ To create a new expansion set click the "New" button on the upper right corner o
- Figure 1: Aerie UI Expansion Sets Page - View or delete expansion sets
+ Figure 1: Aerie UI Expansion Sets Page - View or delete expansion sets
:::info
@@ -35,7 +35,7 @@ In the figure below users can select as many activity types, but must select a s
- Figure 2: Aerie UI Expansion Sets Create Page
+ Figure 2: Aerie UI Expansion Sets Create Page
:::info
diff --git a/docs/command-expansion/run-expansion.mdx b/docs/command-expansion/run-expansion.mdx
index 1134415..3e731f6 100644
--- a/docs/command-expansion/run-expansion.mdx
+++ b/docs/command-expansion/run-expansion.mdx
@@ -8,7 +8,7 @@ Once the expansion set is selected, clicking on the "Expand" button in the upper
- Figure 1: Plan Run Expansion
+ Figure 1: Plan Run Expansion
## Viewing Expansion Results
@@ -17,5 +17,5 @@ Once expansion is complete, users can view the resulting sequence in the seqJSON
- Figure 2: Plan View Sequence
+ Figure 2: Plan View Sequence
diff --git a/docs/command-expansion/sequences.mdx b/docs/command-expansion/sequences.mdx
index edd9d23..6f46b07 100644
--- a/docs/command-expansion/sequences.mdx
+++ b/docs/command-expansion/sequences.mdx
@@ -11,7 +11,7 @@ To do so users should first open the "Expansion" panel in the [Aerie Planning UI
- Figure 1: Plan Expansion Panel
+ Figure 1: Plan Expansion Panel
## Adding Sequences to a Simulation Dataset
@@ -37,7 +37,7 @@ To declare a new sequence, simply type the seqID and press "Create".
- Figure 2: Plan Create Sequence
+ Figure 2: Plan Create Sequence
## Assigning seqIDs to Simulated Activities
diff --git a/docs/command-expansion/upload-command-dictionary.mdx b/docs/command-expansion/upload-command-dictionary.mdx
index 7414c58..34204a1 100644
--- a/docs/command-expansion/upload-command-dictionary.mdx
+++ b/docs/command-expansion/upload-command-dictionary.mdx
@@ -16,14 +16,14 @@ Aerie does not allow uploading the command dictionary files that has the same mi
-
+
Figure 1: Aerie UI Navigation Menu - Click to the 'Command Dictionaries' menu item
-
+
Figure 2: Aerie UI Command Dictionary Page - View, upload, or delete AMPCS command dictionaries
diff --git a/docs/deployment/advanced-authentication.mdx b/docs/deployment/advanced-authentication.mdx
index 86d90c7..0a27fd7 100644
--- a/docs/deployment/advanced-authentication.mdx
+++ b/docs/deployment/advanced-authentication.mdx
@@ -1,8 +1,8 @@
import uiLoginPage from './assets/ui-login-page.png';
-# Advanced - Authentication
+# Advanced - Password Authentication
-Aerie currently only supports authentication for applications internal to JPL via CAM. This document describes how to enable CAM authentication.
+Aerie currently only supports password authentication for applications internal to JPL via CAM. This document describes how to enable CAM username + password authentication.
Note that Hasura _authorization_ is enabled by default (even without CAM authentication enabled), so you need either an admin token or JWT provided by the gateway to access it.
@@ -16,6 +16,21 @@ To learn how to programmatically authenticate with Aerie to get a token, see the
The default Aerie [docker-compose.yml](https://github.com/NASA-AMMOS/aerie/blob/develop/deployment/docker-compose.yml) file requires certain environment variables to be set to enable authentication. This section outlines the variable definitions and the services that require them for authentication.
+### AUTH_GROUP_ROLE_MAPPINGS
+- Description: Optional JSON object that maps LDAP groups to allowed Aerie roles.
+- Service: aerie_gateway
+- Accepted values: Stringified JSON. Auth provider groups are keys, values are list of allowed Aerie roles
+- Example:
+```
+{
+ "team_leads": [ "aerie_admin" ],
+ "power_users": [ "user", "viewer" ],
+ "business_users": [ "viewer" ]
+}
+```
+- Default: `{}`
+- See: [SSO auth docs](../advanced-sso#mapping-auth-provider-groups-to-aerie-roles) for more information.
+
### AUTH_TYPE
- Description: Authentication method (currently only supports CAM or none)
@@ -48,9 +63,9 @@ The default Aerie [docker-compose.yml](https://github.com/NASA-AMMOS/aerie/blob/
## Aerie UI Login Page
-With CAM authentication enabled you can login to the Aerie UI with your JPL username and password.
+With CAM authentication enabled you can log in to the Aerie UI with your JPL username and password.
-
+Figure 1: Aerie UI - Login Page
diff --git a/docs/deployment/advanced-database-migrations.md b/docs/deployment/advanced-database-migrations.mdx
similarity index 57%
rename from docs/deployment/advanced-database-migrations.md
rename to docs/deployment/advanced-database-migrations.mdx
index 36f6c88..2e002b7 100644
--- a/docs/deployment/advanced-database-migrations.md
+++ b/docs/deployment/advanced-database-migrations.mdx
@@ -2,8 +2,8 @@
To aid in migrating between database versions we provide a Python script called [aerie_db_migration.py](https://github.com/NASA-AMMOS/aerie/blob/develop/deployment/aerie_db_migration). In order to run it, the following software is required:
-- [Python 3.7](https://www.python.org/downloads/) or later
-- [Hasura CLI 2.13.0](https://hasura.io/docs/latest/hasura-cli/install-hasura-cli/) or later
+- [Python 3.9](https://www.python.org/downloads/) or later
+- [Hasura CLI 2.35.1](https://hasura.io/docs/latest/hasura-cli/install-hasura-cli/) or later
Additional Python package requirements can be installed by running the following command in the [deployment](https://github.com/NASA-AMMOS/aerie/tree/develop/deployment) directory:
@@ -27,6 +27,9 @@ The script expects all migration files present on the server to also exist on th
## Arguments
+
+ For Aerie deployments before v2.8.0
+
`aerie_db_migration` takes the following command line arguments:
```sh
@@ -34,7 +37,7 @@ aerie_db_migration.py [-h] (-a | -r) [--all] [-db DB_NAMES [DB_NAMES ...]] [-p H
```
| Option Name | Option Description |
-| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| `-h`, `--help` | Shows the help message. |
| `-a`, `--apply` | Apply migration steps to specified databases. |
| `-r`, `--revert` | Revert migration steps to specified databases. |
@@ -47,9 +50,35 @@ aerie_db_migration.py [-h] (-a | -r) [--all] [-db DB_NAMES [DB_NAMES ...]] [-p H
It is necessary to at least specify `--apply` or `--revert`.
If you are not running `aerie_db_migration` from within `deployment`, or if the `hasura` directory containing the `config.yaml` and the `migrations` directory is not in the directory that `aerie_db_migration` is being run from, then it is necessary to specify `--hasura-path`.
+
+
+`aerie_db_migration.py` takes the following command line arguments:
+
+```sh
+aerie_db_migration.py [-h] (-a | -r) [--all] [-p HASURA_PATH] [-e ENV_PATH] [-n NETWORK_LOCATION]
+```
+
+| Option Name | Option Description |
+|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `-h`, `--help` | Shows the help message. |
+| `-a`, `--apply` | Apply migration steps to the database. |
+| `-r`, `--revert` | Revert migration steps to the database. |
+| `--all` | Apply (Revert) _ALL_ unapplied (applied) migration steps to the database. |
+| `-p HASURA_PATH`, `--hasura-path HASURA_PATH` | The path to the directory containing the `config.yaml` for Aerie. Defaults to `./hasura` |
+| `-e ENV_PATH`, `--env-path ENV_PATH` | The path to the `.env` file used to deploy Aerie. **Must** define `AERIE_USERNAME` and `AERIE_PASSWORD`. Defaults to `.env`. |
+| `-n NETWORK_LOCATION`, `--network-location NETWORK_LOCATION` | The network location of the database. Defaults to `localhost`. |
+
+It is necessary to at least specify `--apply` or `--revert`.
+
+If you are not running `aerie_db_migration.py` from within `deployment`,
+or if the `hasura` directory containing the `config.yaml` and the `migrations` directory is not in the directory
+that `aerie_db_migration.py` is being run from, then it is necessary to specify `--hasura-path`.
## Migrating a Database
+
+ For Aerie deployments before v2.8.0
+
If `--all` has been specified, then `aerie_db_migration.py` will automatically apply or revert all applicable changes to the specified databases (or all available databases if none are specified). It will then output the details of each change applied, followed by the overall status. For example:
```sh
@@ -109,3 +138,50 @@ Entering `y` will apply the migration and then proceed to the next step,
should one exist. Entering `n` will return to the Database Selection screen.
Entering `q` at any point will exit the program.
+
+
+
+If `--all` has been specified, then `aerie_db_migration.py` will automatically apply or revert all applicable changes to the database.
+It will then output the details of each change applied, followed by the overall status. For example:
+
+```sh
+> aerie_db_migration.py -a --all
+###############################
+AERIE DATABASE MIGRATION HELPER
+###############################
+VERSION TYPE NAME
+1 up sample_migration
+INFO migrations applied
+INFO Metadata reloaded
+INFO Metadata is consistent
+
+###############
+Database Status
+###############
+VERSION NAME SOURCE STATUS DATABASE STATUS
+1 sample_migration Present Present
+```
+
+Otherwise, `aerie_db_migration` will enter a step-by-step mode, where you will be prompted
+whether to apply each available migration step. For example:
+
+```sh
+> aerie_db_migration.py -a
+###############################
+AERIE DATABASE MIGRATION HELPER
+###############################
+
+MIGRATION STEPS AVAILABLE:
+VERSION NAME SOURCE STATUS DATABASE STATUS
+1 sample_migration Present Not Present
+
+CURRENT STEP:
+
+VERSION TYPE NAME
+1 up sample_migration
+
+Apply 1_sample_migration? (y/n/quit): _
+```
+
+Entering `y` will apply the migration and then proceed to the next step, should one exist.
+Entering `n`, `q`, or `quit` will exit the program.
diff --git a/docs/deployment/advanced-permissions.mdx b/docs/deployment/advanced-permissions.mdx
new file mode 100644
index 0000000..bf6e895
--- /dev/null
+++ b/docs/deployment/advanced-permissions.mdx
@@ -0,0 +1,365 @@
+# Advanced - User Role Permissions
+
+User Roles are sets of permissions that defines how a user is a allowed to interact with the Aerie system.
+By default, Aerie provides three User Roles:
+
+- `viewer`, which can view all data
+- `user`, which can view all data and perform all actions based on ownership
+- `aerie_admin`, which can view all data and perform all actions
+
+## Creating New User Roles
+
+Should the default three not be sufficient for your deployment, it is possible to define new User Roles.
+
+:::info
+The `viewer` role is the most restricted role Aerie supports. To ensure Aerie works as expected when using your new role,
+it is strongly recommended to give your role *at least* the same permissions as `viewer`.
+:::
+
+### Adding the Role to Hasura
+
+In order to interact with the Aerie system, a role must first be provided access via the [Hasura Metadata](https://github.com/NASA-AMMOS/aerie/tree/develop/deployment/hasura/metadata).
+
+There are three parts of the Hasura Metadata that a role needs to be added to:
+Functions, Actions, and individual tables. The Hasura Metadata can be found in `hasura/metadata`.
+
+#### Function Permissions
+
+Function Permissions can be found in `databases//functions/functions.yaml`.
+Currently, all functions are in the AerieMerlin Database.
+The inside of a `functions.yaml` will look like a sequence of entries in the following pattern:
+
+```yaml
+- function:
+ name:
+ schema: hasura_functions
+ configuration:
+ custom_root_fields:
+ function:
+ session_argument: hasura_session
+ permissions:
+ - role: aerie_admin
+```
+
+To give the new role permission to see a given Function,
+you must add them to the list of roles listed under the `permissions` key, like so:
+
+```yaml
+ permissions:
+ - role: aerie_admin
+ - role:
+```
+
+#### Action Permissions
+
+Action permissions can be found in `actions.yaml`. Similar to Functions, the file will be a series of entries.
+The pattern for these entries is:
+
+```yaml
+ - name:
+ definition:
+ kind: synchronous
+ handler: ""
+ timeout: 300
+ permissions:
+ - role: aerie_admin
+ - role: user
+```
+
+To give a role permission to see an Action, add them to the list of roles under the `permissions` key:
+
+```yaml
+ permissions:
+ - role: aerie_admin
+ - role: user
+ - role:
+```
+
+#### Table Permissions
+
+Table permissions are specified per table and can be found under `databases//tables`.
+
+There are four permissions that may be specified for a role on a table: Select, Insert, Update, and Delete.
+The follow section goes over how to configure these permissions.
+More information on [configuring table permissions](https://hasura.io/docs/latest/auth/authorization/permissions/)
+and [the YAML syntax](https://hasura.io/docs/latest/api-reference/syntax-defs/#insertpermission) may be found in the Hasura Docs.
+
+##### Select Permissions:
+- `columns` determines which fields a role can see on all rows it can read. It is generally expected that all roles can read all columns in a table, abbreviated as `'*'`.
+- `filter` determines which rows a role can read. It is generally expected that all roles can read all rows in a table, represented as `{}`.
+- `allow_aggregations` determines whether a role can run aggregation functions, such as `count` or `max` on parts of the table it can read.
+
+Example Select Permission:
+```yaml
+select_permissions:
+ - role:
+ permission:
+ columns: '*'
+ filter: {}
+ allow_aggregations: true
+```
+
+##### Insert Permissions:
+- `columns` determines which fields a role can provide values for while setting a row. It is expected that `columns` includes at least those specified in the `user` role.
+- `check` allows for validation of the row being inserted.
+For example, `{"name":{"_like":"aerie--%"}}` means that the row being inserted must have its `name` field begin with "aerie--".
+- `set` automatically sets the value of certain fields on the row to be inserted.
+For example, `owner: "x-hasura-user-id"` will set `owner` as the current user's username (`"x-hasura-user-id"`).
+These fields **must not** be included in `columns`.
+
+Example Insert Permission:
+```yaml
+insert_permissions:
+ - role:
+ permission:
+ columns: [name, definition]
+ check: {"name":{"_like":"aerie--%"}}
+ set:
+ owner: "x-hasura-user-id"
+```
+
+##### Update Permissions:
+- `columns` determines which fields a role may update for a given row.
+It is expected that `columns` includes at least those specified in the `user` role.
+- `filter` determines which rows a role may update.
+For example, `{"owner":{"_eq":"x-hasura-user-id"}}` means that users using the role can only delete rows
+where the `owner` field is their username.
+- `check` allows for validation of the updated row.
+For example, `{"name":{"_like":"aerie--%"}}` means that the row must have its `name` field begin with "aerie--" after being updated.
+This is optional.
+- `set` automatically sets the value of certain fields on the row being updated.
+For example, `updated_by: "x-hasura-user-id"` will set `owner` as the current user's username.
+These fields **must not** be included in `columns`.
+
+Example Update Permission:
+```yaml
+update_permissions:
+ - role:
+ permission:
+ columns: [name, owner]
+ filter: {"owner":{"_eq":"x-hasura-user-id"}}
+ check: {"name":{"_like":"aerie--%"}}
+ set:
+ updated_by: "x-hasura-user-id"
+```
+
+##### Delete Permissions:
+- `filter` determines which rows a role can delete.
+For example, `{"owner":{"_eq":"x-hasura-user-id"}}` means that users using the role can only delete rows
+where the `owner` field is their username.
+
+Example Delete Permission:
+```yaml
+delete_permissions:
+ - role:
+ permission:
+ filter: {"owner":{"_eq":"x-hasura-user-id"}}
+```
+
+### Adding the Role to the Database
+
+Before a role can be applied to users, it must be added to the Database.
+
+This can be done using the following GraphQL mutation:
+
+```graphql
+mutation InsertUserRole {
+ insert_user_roles_one(object: {
+ role: "",
+ description: ""})
+ {
+ role
+ description
+ }
+}
+```
+
+After adding a new role, [it is currently necessary to refresh the Hasura Metadata](https://hasura.io/docs/latest/schema/postgres/enums/#current-limitations).
+Instructions on how to do so can be found [in the Hasura Docs](https://hasura.io/docs/latest/migrations-metadata-seeds/manage-metadata/#reload-metadata).
+
+
+#### Action and Function Permissions
+
+In addition to the coarse-grained permissions granted by the Hasura Metadata,
+certain Functions and Actions have what are known as fine-grained permissions.
+For these Functions and Actions **it is not sufficient** to only allow the role
+to see the function via the Hasura metadata.
+This section will go over how to specify these fine-grained permissions
+for a custom role.
+
+Action and Function Permissions are represented as two JSONs, one for Actions and one for Functions.
+The structure of these JSONs are `{ KEY_1: PERMISSION, KEY_2: PERMISSION, ... , KEY_N: PERMISSION }`.
+The absence of a Key will be considered equivalent to a role **NOT** having permission to perform the Action or Function.
+
+
+Keys Permitted for Action Permissions
+
+Any Actions not included here only have coarse-grained control.
+
+| Key | Hasura Action |
+| -: | :- |
+| `check_constraints` | constraintViolations
+| `create_expansion_rule` | addCommandExpansionTypeScript
+| `create_expansion_set` | createExpansionSet
+| `expand_all_activities` | expandAllActivities
+| `insert_ext_dataset` | addExternalDataset
+| `resource_samples` | resourceSamples
+| `schedule` | schedule
+| `sequence_seq_json_bulk` | getSequenceSeqJsonBulk
+| `simulate` | simulate
+
+
+
+
+
+Keys Permitted for Function Permissions
+
+Any Functions not included here only have coarse-grained control.
+
+| Key | Hasura Function |
+| -: | :- |
+| `apply_preset` | `apply_preset_to_activity`
+| `begin_merge` | `begin_merge`
+| `branch_plan` | `duplicate_plan`
+| `cancel_merge` | `cancel_merge`
+| `commit_merge` | `commit_merge`
+| `create_merge_rq` | `create_merge_request`
+| `create_snapshot` | `create_snapshot`
+| `deny_merge` | `deny_merge`
+| `delete_activity_reanchor` | `delete_activity_by_pk_reanchor_to_anchor`
+| `delete_activity_reanchor_bulk` | `delete_activity_by_pk_reanchor_to_anchor_bulk`
+| `delete_activity_reanchor_plan` | `delete_activity_by_pk_reanchor_plan_start`
+| `delete_activity_reanchor_plan_bulk` | `delete_activity_by_pk_reanchor_plan_start_bulk`
+| `delete_activity_subtree` | `delete_activity_by_pk_delete_subtree`
+| `delete_activity_subtree_bulk` | `delete_activity_by_pk_delete_subtree_bulk`
+| `get_conflicting_activities` | `get_conflicting_activities`
+| `get_non_conflicting_activities` | `get_non_conflicting_activities`
+| `get_plan_history` | `get_plan_history` |
+| `restore_activity_changelog` | `restore_activity_changelog`
+| `restore_snapshot` | `restore_from_snapshot`
+| `set_resolution` | `set_resolution`
+| `set_resolution_bulk` | `set_resolution_bulk`
+| `withdraw_merge_rq`| `withdraw_merge_request`
+
+
+
+
+Values Permitted for PERMISSION
+
+| Permission | Meaning |
+| -: | :- |
+| `NO_CHECK` | The user may run the action/function with no restrictions. **The `aerie_admin` role will always be treated as having `NO_CHECK` permissions on all Actions and Functions.** |
+| `OWNER` | The user must be the `owner` of **all** relevant objects **directly** used by the KEY |
+| `MISSION_MODEL_OWNER` | The user must own the relevant Mission Model |
+| `PLAN_OWNER` | The user must be the Owner of the relevant Plan |
+| `PLAN_COLLABORATOR` | The user must be a Collaborator of the relevant Plan. **The Plan Owner is NOT considered a Collaborator of the Plan** |
+| `PLAN_OWNER_COLLABORATOR` | The user must be either the Owner or a Collaborator of the relevant Plan |
+
+In general, `OWNER` is equivalent to `PLAN_OWNER`. Exceptions are as follows:
+- `apply_preset`, where `OWNER` means a user must own both the plan and the preset
+
+#### On Plan Merge Keys
+
+The following Function Keys are in a group known as "Plan Merge Functions" and are involved in [Plan Merging](../../planning/collaboration/merging-plans/):
+`begin_merge`, `cancel_merge`, `create_merge_rq`, `commit_merge`, `deny_merge`, `get_conflicting_activities`,
+`get_non_conflicting_activities`, `set_resolution`, `set_resolution_bulk`, `withdraw_merge_rq`.
+
+Plan Merge Functions are special, as they involve multiple plans.
+As such, there are special Permissions that may be used on these Keys.
+Additionally, the other Permissions take on a slightly different meaning when applied to a Plan Merge Function.
+
+A complete list of what Permissions are allowed on Plan Merge Functions follows.
+Keep in mind that in a merge 'Source Plan' refers to the plan *providing* changes,
+and 'Target Plan' refers to the plan *receiving* changes.
+
+| Permission | Meaning |
+|-:|:-|
+| `NO_CHECK` | The user may run the action/function with no restrictions. **The `aerie_admin` role will always be treated as having `NO_CHECK` permissions on all Plan Merge Functions.** |
+| `OWNER` | The user must be the Owner of **both** Plans
+| `MISSION_MODEL_OWNER` | The user must be the Owner of the relevant Mission Model
+| `PLAN_OWNER` | The user must be the Owner of **either** Plan
+| `PLAN_COLLABORATOR` | The user must be a Collaborator of **either** Plan. **The Plan Owner is NOT considered a Collaborator of the Plan**
+| `PLAN_OWNER_COLLABORATOR` | The user must be either the Owner or a Collaborator of **either** Plan
+| `PLAN_OWNER_SOURCE` | The user must be the Owner of the Source Plan.
+| `PLAN_COLLABORATOR_SOURCE` | The user must be a Collaborator of the Source Plan.
+| `PLAN_OWNER_COLLABORATOR_SOURCE` | The user must be either the Owner or a Collaborator of the Source Plan.
+| `PLAN_OWNER_TARGET` | The user must be the Owner of the Target Plan.
+| `PLAN_COLLABORATOR_TARGET` | The user must be a Collaborator of the Target Plan.
+| `PLAN_OWNER_COLLABORATOR_TARGET` | The user must be either the Owner or a Collaborator of the Target Plan.
+
+
+
+Once you have devised your Action Permissions and Function Permissions JSONs,
+you can use this GraphQL Mutation to apply them to your custom role:
+
+```graphql
+mutation updateUserRolePermissions($function_permissions: jsonb!, $action_permissions: jsonb!) {
+ update_user_role_permission_by_pk(
+ pk_columns: {role: },
+ _set: {
+ function_permissions: $function_permissions,
+ action_permissions: $action_permissions}
+ ) {
+ function_permissions
+ action_permissions
+ }
+}
+```
+
+Below are sample Query Variables. These are equivalent to the `user` role's Permissions.
+
+```json
+{
+ "action_permissions": {
+ "check_constraints": "PLAN_OWNER_COLLABORATOR",
+ "create_expansion_rule": "NO_CHECK",
+ "create_expansion_set": "NO_CHECK",
+ "expand_all_activities": "NO_CHECK",
+ "insert_ext_dataset": "PLAN_OWNER",
+ "resource_samples": "NO_CHECK",
+ "schedule":"PLAN_OWNER_COLLABORATOR",
+ "sequence_seq_json_bulk": "NO_CHECK",
+ "simulate":"PLAN_OWNER_COLLABORATOR"
+ },
+ "function_permissions": {
+ "apply_preset": "PLAN_OWNER_COLLABORATOR",
+ "begin_merge": "PLAN_OWNER_TARGET",
+ "branch_plan": "NO_CHECK",
+ "cancel_merge": "PLAN_OWNER_TARGET",
+ "commit_merge": "PLAN_OWNER_TARGET",
+ "create_merge_rq": "PLAN_OWNER_SOURCE",
+ "create_snapshot": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_reanchor": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_reanchor_bulk": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_reanchor_plan": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_reanchor_plan_bulk": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_subtree": "PLAN_OWNER_COLLABORATOR",
+ "delete_activity_subtree_bulk": "PLAN_OWNER_COLLABORATOR",
+ "deny_merge": "PLAN_OWNER_TARGET",
+ "get_conflicting_activities": "NO_CHECK",
+ "get_non_conflicting_activities": "NO_CHECK",
+ "get_plan_history": "NO_CHECK",
+ "restore_activity_changelog": "PLAN_OWNER_COLLABORATOR",
+ "restore_snapshot": "PLAN_OWNER_COLLABORATOR",
+ "set_resolution": "PLAN_OWNER_TARGET",
+ "set_resolution_bulk": "PLAN_OWNER_TARGET",
+ "withdraw_merge_rq": "PLAN_OWNER_SOURCE"
+ }
+}
+```
+
+## Configuring Roles for New Users
+
+The first time a user not in the system logs in, they will be added to the Aerie system with a set of User Roles they
+are allowed to use and one Role from this set that they use by default.
+By default, users will use the `user` role and have access to the `user` and `viewer` roles.
+To configure this, use the `ALLOWED_ROLES` and `DEFAULT_ROLE` environment variables.
+**Note: `DEFAULT_ROLE` _must_ be an entry in `ALLOWED_ROLES`.**
+
+For more information, see the [Environment Variables document](https://github.com/NASA-AMMOS/aerie-gateway/blob/develop/docs/ENVIRONMENT.md) in the Gateway.
+
+:::info When Authentication is Disabled
+[If authentication is disabled](../advanced-authentication/), then the following changes apply:
+1. By default, users will use the `aerie_admin` role and have access to the `aerie_admin`, `user`, and `viewer` roles
+2. To configure these roles for new users, use the `ALLOWED_ROLES_NO_AUTH` and `DEFAULT_ROLES_NO_AUTH` environment variables instead.
+:::
diff --git a/docs/deployment/advanced-reverse-proxy.md b/docs/deployment/advanced-reverse-proxy.md
new file mode 100644
index 0000000..3943a53
--- /dev/null
+++ b/docs/deployment/advanced-reverse-proxy.md
@@ -0,0 +1,53 @@
+# Advanced - Reverse Proxy
+
+# Deploying with HTTPS / Behind a reverse proxy
+
+The `./deployment/proxy` folder contains the following as a standard pattern for deploying Aerie with a reverse proxy:
+```
+- nginx.conf # nginx (reverse proxy) configuration file that terminates TLS and proxies traffic to internal containers
+- Dockerfile # runs an nginx instance as configured above
+- docker-compose-proxy.yml # docker-compose that runs the above Docker container within the Aerie stack, closing unneccesary ports
+```
+
+In this example, an [`nginx`](https://nginx.org) instance runs within the Aerie container stack, acting as the single ingress point for all network traffic, which strips TLS and forwards HTTP traffic to internal containers.
+
+## Generating a self-signed TLS certificate for testing
+
+Running the following command will generate a self-signed certificate for testing TLS. It will prompt you for several fields which can all be left blank (i.e. just press enter).
+
+```
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 --nodes
+```
+
+Move these `key.pem` and `cert.pem` files into the `./deployment/proxy` folder, so `nginx` can read them.
+
+## Define Aerie deployment host
+When running a production deployment of Aerie, you can use DNS records to point a domain to your deployment server's IP address.
+
+To emulate DNS on a local machine, you can edit `/etc/hosts` (on unix-based machines). Adding the following line will redirect `localhost.jpl.nasa.gov` to `127.0.0.1`, which will allow us to use a fake domain name for a local Aerie deployment. This can be any domain, but it's a best practice to use something that doesn't exist as a public site.
+
+```
+127.0.0.1 localhost.jpl.nasa.gov
+```
+
+## Run Aerie instance with reverse proxy
+Edit your Aerie `./deployment/.env` file to define `AERIE_HOST=${whatever domain you put in your /etc/hosts or DNS}`.
+
+Running the following command from the `./deployment` directory of the Aerie repo will now deploy the regular Aerie stack with `nginx` proxying all connections.
+```
+docker compose -f docker-compose.yml -f ./proxy/docker-compose-proxy.yml up -d --build
+```
+
+You can now visit `https://here-is-the-domain-you.set`, which will prompt you to trust a self-signed certificate, and then forward you to Aerie as usual!
+
+:::info Accepting self-signed certificates
+You will need to accept self-signed certificates for Aerie UI, Hasura, _and_ the Gateway.
+Visit the following three URLs and follow the instructions to allow self-signed certs:
+- `https://here-is-the-domain-you.set`
+- `https://here-is-the-domain-you.set:8080/console`
+- `https://here-is-the-domain-you.set:9000`
+
+Aerie will *not* function correctly if all three certificates are not accepted.
+
+This manual process can be avoided if you are able to use a testing certificate for this domain that is signed by your authorities.
+:::
diff --git a/docs/deployment/advanced-sso.md b/docs/deployment/advanced-sso.md
new file mode 100644
index 0000000..bba4951
--- /dev/null
+++ b/docs/deployment/advanced-sso.md
@@ -0,0 +1,191 @@
+# Advanced - SSO Authentication
+
+Aerie is able to interoperate with external auth providers like JPL CAM, [Auth0](https://auth0.com/), [AWS Cognito](https://aws.amazon.com/cognito/), etc in order to provide single-sign on (SSO) support. Due to Aerie's open source and flexible nature, the SSO implementation is very extensible, and while this allows for organizations of many types to use Aerie, it will require some configuration on the deployment side.
+
+This is achieved through the use of several environment variables as well as "Auth Adapters", that read these environment variables, communicate with external auth providers, and translate their response to work with Aerie's existing auth.
+
+## Enabling SSO Authentication
+
+The following environment variables will need to be set in conjunction for SSO auth to work correctly.
+
+### Aerie Gateway variables
+
+#### AUTH_URL
+- Description: URL that the Gateway will make auth API requests to. Likely found in auth provider docs.
+- Accepted values: Any URL
+- Example: `https://your-auth-provider-api-endpoint`
+- Default: `https://atb-ocio-12b.jpl.nasa.gov:8443/`
+
+#### AUTH_UI_URL
+- Description: Login UI URL that the Gateway will redirect the UI to if SSO auth fails. Likely found in auth provider docs.
+- Accepted values: Any URL
+- Example: `https://your-auth-provider-login-screen`
+- Default: `https://atb-ocio-12b.jpl.nasa.gov:8443/cam-ui`
+
+#### AUTH_SSO_TOKEN_NAME
+- Description: Name of the cookie(s) that the Gateway will parse for SSO token(s). See the [following tip](#setting-default_roles) to make sure you're setting array env vars correctly.
+- Accepted values: List of strings
+- Example: `["my_sso_token_cookie_name"]`
+- Default: `["iPlanetDirectoryPro"]`
+
+#### AUTH_TYPE
+- Description: Enum value that determines which Auth Adapter is loaded.
+- Accepted values: `cam` or `none`
+- Default: `none`
+
+### Aerie UI variables
+
+#### PUBLIC_AUTH_SSO_ENABLED
+- Description: Boolean flag that enables the SSO-based auth flow instead of the JWT-only flow
+- Accepted values: `true` or `false`
+- Example: `true`
+- Default: `false`
+
+## Sensible configurations
+
+Three main use cases exist for auth within Aerie, each with their own configuration and combination of env vars:
+
+### CAM API auth + Aerie login UI
+
+User is forwarded to Aerie UI /login page if no valid Aerie JWT is found. Credentials passed in here will be tested against the CAM API for validity.
+
+```sh
+# Gateway vars
+AUTH_TYPE=cam
+AUTH_UI_URL="https://localhost.jpl.nasa.gov/login" # example Aerie UI /login URL
+AUTH_URL="https://atb-ocio-12b.jpl.nasa.gov:8443/cam-api" # example SSO API URL
+
+# UI var
+PUBLIC_AUTH_SSO_ENABLED=false # use /login prompt instead of SSO
+```
+
+### Aerie login UI without authentication
+
+User is forwarded to Aerie UI `/login` page if no valid Aerie JWT is found. Validity of username / password is never checked; automatically signed in as username with admin privileges. Useful for testing / dev environments
+
+```sh
+# Gateway vars
+AUTH_TYPE=none
+AUTH_UI_URL="https://localhost.jpl.nasa.gov/login" # Aerie UI /login URL
+
+# UI var
+PUBLIC_AUTH_SSO_ENABLED=false # use /login prompt instead of SSO
+```
+
+### SSO token-based authentication using external auth providers.
+
+User is forwarded to SSO login UI page if no valid Aerie JWT or SSO token is found.
+
+```sh
+# Gateway vars
+AUTH_TYPE=cam
+AUTH_UI_URL="https://atb-ocio-12b.jpl.nasa.gov:8443/cam-ui" # example SSO login UI
+AUTH_URL="https://atb-ocio-12b.jpl.nasa.gov:8443/cam-api" # example SSO API
+AUTH_SSO_TOKEN_NAME='["iPlanetDirectoryPro"]' # example name of SSO token cookie
+
+# UI var
+PUBLIC_AUTH_SSO_ENABLED=true # use SSO login page instead of Aerie's `/login`
+```
+
+## Mapping auth provider groups to Aerie roles
+
+:::info
+
+This feature was introduced in Aerie 2.5.0
+
+:::
+
+:::note
+
+This is an optional feature. If `AUTH_GROUP_ROLE_MAPPINGS` isn't set (or is set to an empty JSON: `{}`), the Gateway will not use auth provder group membership and instead use `DEFAULT_ROLE` and `ALLOWED_ROLES` as the source of truth for assigning roles, as described in the [Password Authentication docs](../advanced-permissions/#configuring-roles-for-new-users)
+
+:::
+
+When authenticating with external auth providers like CAM, Aerie provides the ability to map auth groups (e.g. LDAP groups) to roles within Aerie (e.g. `user`, `viewer`). This is facilitated with the `AUTH_GROUP_ROLE_MAPPINGS` environment variable. When authenticating users, the loaded Auth Adapter within Aerie Gateway can query the external auth provider for available group membership (e.g. LDAP group membership in the CAM SSO case).
+
+The authentication role-mapping algorithm is roughly as follows:
+
+- Get all groups the user is a member of from external auth provider
+- Take the intersection of user's groups and the groups that have mappings defined in `AUTH_GROUP_ROLE_MAPPINGS`
+- Map these groups to Aerie roles using the defined mapping
+- Take the union of all allowed roles, this becomes `allowed_roles` for the user
+- Iterate through `DEFAULT_ROLE` list. The first role that is contained within the user's `allowed_roles` becomes the user's `default_role`
+
+In other words, `AUTH_GROUP_ROLE_MAPPINGS` is an unordered mapping that defines which roles are granted to users in a specific auth group. `DEFAULT_ROLE` is an ordered priority list, where the default role for a user is the first match. This means that each group -> role mapping in `AUTH_GROUP_ROLE_MAPPINGS` _must_ contain at least one of the roles in the `DEFAULT_ROLE` list, since a user must always have a default role defined. An error will be thrown from the Gateway on bootup if this constraint is not satisfied.
+
+### Creating an `AUTH_GROUP_ROLE_MAPPINGS`
+
+The `AUTH_GROUP_ROLE_MAPPINGS` environment variable must be valid JSON in the following format:
+
+```json
+{
+ "some_auth_group_name": ["aerie_admin", "user", "viewer"],
+ "another_auth_group_name": ["viewer"]
+}
+```
+
+:::info
+This variable will be run through `JSON.parse()` in the Auth Adapters, so it must be valid JSON (e.g. double quotes, no trailing comma, etc). An error will be thrown from the Gateway on boot if the environment variable is invalid JSON. View the [following tip](#setting-default_roles) to make sure you're setting env vars as literal values, e.g. in a `docker-compose.yml` file:
+```yaml
+aerie_gateway:
+ environment:
+ AUTH_GROUP_ROLE_MAPPINGS: |
+ {
+ "some_auth_group_name": ["aerie_admin", "user", "viewer"],
+ "another_auth_group_name": ["viewer"]
+ }
+```
+
+:::
+
+### Setting `DEFAULT_ROLE`'s
+
+:::tip
+You'll need to be cognizant on how environment variables are set in your Aerie deployment (e.g. docker-compose.yml file v.s. .env file). Some ways of setting environment variables will escape or strip quotes, which can lead to invalid JSON being passed to Aerie services.
+
+e.g. in a docker-compose.yml file:
+
+```yaml
+aerie_gateway:
+ environment:
+ DEFAULT_ROLE: "[\"viewer\"]" # won't work
+```
+
+DEFAULT_ROLE will be stripped of quotes, and passed to the Gateway as the literal ["viewer"], which isn't valid JSON.
+
+Instead, pass literal values when possible, like in the following docker-compose.yml example.
+
+```yaml
+aerie_gateway:
+ environment:
+ DEFAULT_ROLE: |
+ ["viewer"]
+```
+:::
+
+## Writing custom Auth Adapters
+
+The SSO-based auth flow is roughly as follows:
+
+- A user request is made from the client (e.g. navigate to `/plans/1`)
+- The Aerie UI server intercepts this request, and forwards cookies to the Gateway
+- The Gateway reads `AUTH_TYPE` to determine which auth adapter to load (CAM, Auth0, etc)
+- The Gateway executes the `validate` function of the loaded auth adapter
+ - Cookies named within `AUTH_SSO_TOKEN_NAME` are read as SSO token(s)
+ - Authentication requests are made to `AUTH_URL` that determine token validity
+ - If the user has a valid SSO token, `validate` returns a JWT for use within Aerie
+ - Otherwise, `validate` returns a redirection to `AUTH_UI_URL`
+- The Aerie UI server reads the response, and either redirects the user to the SSO login UI, or continues with the original request, using the returned JWT for authorization
+
+This architecture was chosen so that the Gateway can be easily extended with custom auth adapters that implement this interface for any arbitrary auth provider. The interface for the Auth Adapter is as follows (defined in `auth/types.ts` in the Gateway repo):
+
+```typescript
+export interface AuthAdapter {
+ validate(req: Request): Promise;
+ logout(req: Request): Promise;
+}
+```
+
+Advanced Aerie users can easily create their own e.g. `Auth0Adapter.ts` that implements this interface and runs a custom version of the previously defined algorithm, that will validate any existing SSO token cookies, and return a `ValidateResponse` that can be used downstream by Aerie UI.
+
+More docs to come as this custom implementation feature is fleshed out.
diff --git a/docs/introduction.md b/docs/introduction.md
index 2891b1a..894f001 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -1,6 +1,6 @@
# Introduction
-Aerie is a next-generation software framework for modeling spacecraft. It is developed by the [NASA Jet Propulsion Laboratory (JPL)](https://www.jpl.nasa.gov/), and is being used for planning and operating spacecraft missions like [Europa Clipper](https://europa.nasa.gov/).
+Aerie is an open source, extensible software system for planning, scheduling, and commanding space missions. Developed and maintained by NASA's [Advanced Multi-Mission Operation System (AMMOS)](https://ammos.nasa.gov/), it provides modeling and simulation capabilities that can be used for mission planning and analysis during project formulation all the way through operations, where it can be used to manage and validate spacecraft activity plans. Aerie is actively being used on flagship missions like [Europa Clipper](https://europa.nasa.gov/), but is equally suitable for smaller missions and constellations.
Some of the main features of Aerie include:
@@ -13,6 +13,8 @@ Some of the main features of Aerie include:
- A GraphQL API so you can easily build tools on top of Aerie
- A web-based [client application](https://github.com/NASA-AMMOS/aerie-ui)
+As a multi-tenant system, Aerie allows multiple distributed users to [collaborate](https://nasa-ammos.github.io/aerie-docs/planning/collaboration/introduction/) in real-time on a single plan or concurrently work on multiple plans for multiple missions. Additionally, Aerie's [service based architecture](https://nasa-ammos.github.io/aerie-docs/overview/software-design-document/#aerie-system-design) allows for efficient system deployment and scalability on the cloud.
+
## Fast Track ⏱️ {#fast-track}
Understand Aerie in **5 minutes** by trying it out!
@@ -37,4 +39,6 @@ Understand Aerie in **5 minutes** by trying it out!
1. Visit [http://localhost/](http://localhost/) to view the [Aerie UI](https://github.com/NASA-AMMOS/aerie-ui).
+ Note that the fast track deployment is not configured to connect to an authentication and authorization provider, therefore any credentials are accepted.
+
1. Head over to the planning documentation to learn how to [upload a mission model](../planning/upload-mission-model).
diff --git a/docs/keyboard-shortcuts.mdx b/docs/keyboard-shortcuts.mdx
new file mode 100644
index 0000000..34e2b8c
--- /dev/null
+++ b/docs/keyboard-shortcuts.mdx
@@ -0,0 +1,68 @@
+---
+title: Keyboard Shortcuts
+---
+
+export const Shortcut = ({ children }) => (
+
+ {children}
+
+);
+
+A list of keyboard shortcuts that can be used within the Aerie UI.
+
+### Plan View
+
+Start running simulation from anywhere in the plan view with ⌘ + s (MacOS) or ctrl + s (Windows).
+
+**Timeline**
+
+The easiest way to navigate the timeline is by holding ⌘ (MacOS) or ctrl (Windows) and then using click+drag to pan and scroll to zoom in and out.
+
+- middle mouse button + drag pans the timeline horizontally
+- = zooms timeline in
+- - zooms timeline out
+- [ nudges timeline left
+- ] nudges timeline right
+- ctrl + T toggles the cursor visibility
+- 0 resets the timeline zoom
+- delete or backspace deletes selected activity directive
+
+
+
+**Activity Table**
+
+- delete or backspace delete selected row from tables you have permissions to delete
+
+
+
+**Activity Parameters**
+
+- ⌘ + left click (MacOS) or ctrl +
+ left click
+ (Windows) resets paramater value to default
+
+
+
+**Activity Error Rollup**
+
+- ⌘ + left click (MacOS) or ctrl +
+ left click
+ (Windows) resets invalid parameters if possible
+
+
+
+### Expansion Rule Form
+
+- ⌘ + s (MacOS) or ctrl + s (Windows)
+ saves the form
+
+
+
+### Sequence Editor
+
+- ⌘ + s (MacOS) or ctrl + s (Windows)
+ saves the sequence
diff --git a/docs/mission-modeling/activity-types/introduction.mdx b/docs/mission-modeling/activity-types/introduction.mdx
index 80c2b14..7dab961 100644
--- a/docs/mission-modeling/activity-types/introduction.mdx
+++ b/docs/mission-modeling/activity-types/introduction.mdx
@@ -6,13 +6,13 @@ An **activity type** defines a simulated behavior that may be invoked by a plann
Activity types may define **parameters**, which are filled with **arguments** by a planner and provided to the activity upon execution.
Activity types may also define **validations** for the purpose of informing a planner when the parameters they have provided may be problematic.
-For example, here is a simple activity type from the FireSat template mission model:
+For example, here is a simple activity type from the examples in the template mission model:
Aerie automatically generates parameter serialization boilerplate for every activity type defined in the mission model's [package-info.java](../introduction.mdx#the-package-infojava-file).
@@ -23,7 +23,7 @@ Moreover, the generated Model base class provides helper methods for spawning ea
In order for Aerie to detect an activity type, its class must be annotated with the `@ActivityType` tag. An activity type is declared with its name using the following annotation:
```java
-@ActivityType("GncChangeControlMode")
+@ActivityType("CollectData")
```
By doing so, the Aerie annotation processor can discover all activity types declared in the mission model, and validate that activity type names are unique.
diff --git a/docs/mission-modeling/activity-types/parameters.md b/docs/mission-modeling/activity-types/parameters.md
index f0ed92f..9d1a4bb 100644
--- a/docs/mission-modeling/activity-types/parameters.md
+++ b/docs/mission-modeling/activity-types/parameters.md
@@ -34,3 +34,26 @@ public boolean validateInstrumentPowers() {
```
The annotation processor identifies these methods and arranges for them to be invoked whenever a planner instantiates an instance of the class. A message will be provided to the planner for each failing validation, so the order of validation methods does not matter.
+
+Validations can also be more dynamic if failure reasons are needed for specific cases, rather than using the annotation above the following is supported. The first parameter is the validation result, the second is the subject of the validation, and the third is the message.
+
+If returning a `true` result the subject and message can be `null`.
+
+```java
+@Validation
+public ValidationResult validateInstrumentPowers() {
+ if (instrumentPower_W < 0) {
+ return new ValidationResult(false, "instrumentPower_W", "Instrument W's power is below " + 0);
+ } else if (instrumentPower_W > 1000.0) {
+ return new ValidationResult(false, "instrumentPower_W", "Instrument W's power is above " + 1000.0);
+ }
+
+ if (instrumentPower_Y < 0) {
+ return new ValidationResult(false, "instrumentPower_Y", "Instrument Y's power is below " + 0);
+ } else if (instrumentPower_Y > 1000.0) {
+ return new ValidationResult(false, "instrumentPower_Y", "Instrument Y's power is above " + 1000.0);
+ }
+
+ return new ValidationResult(true, null, null);
+}
+```
diff --git a/docs/mission-modeling/advanced-the-merlin-interface.mdx b/docs/mission-modeling/advanced-the-merlin-interface.mdx
index 1477696..7f5c91d 100644
--- a/docs/mission-modeling/advanced-the-merlin-interface.mdx
+++ b/docs/mission-modeling/advanced-the-merlin-interface.mdx
@@ -5,7 +5,13 @@ Aerie is a software framework for modeling spacecraft. Within Aerie is **Merlin*
Because mission models are expressed in Java, rather than a custom DSL, Merlin has little to no ability to see the actual Java code comprising a mission model.
Merlin must instead make inferences about the mission model based on its observable behavior.
-Predecessors of Merlin, such as [APGen](https://trs.jpl.nasa.gov/handle/2014/45571) and [SEQGen](https://trs.jpl.nasa.gov/handle/2014/45455), provided a domain-specific language for mission modeling, allowing them to obtain deep, fine-grained information about the composition of a mission model before performing any simulation.
+Merlin is a spiritual successor to the
+[Blackbird](https://trs.jpl.nasa.gov/handle/2014/52245) planning
+system, which similarly uses Java for activity and resource modeling.
+Blackbird's design shed light on the myriad choices made in designing
+Merlin.
+
+Predecessors of Merlin and Blackbird, such as [APGen](https://trs.jpl.nasa.gov/handle/2014/45571) and [SEQGen](https://trs.jpl.nasa.gov/handle/2014/45455), provided a domain-specific language for mission modeling, allowing them to obtain deep, fine-grained information about the composition of a mission model before performing any simulation.
In some ways, this provides enhanced ergonomics, as a mission modeler can focus on expressing their model directly in the modeling language, without being concerned with the needs of the system that will be interpreting that model.
The language itself captures all interesting aspects of the model.
diff --git a/docs/mission-modeling/configuration.md b/docs/mission-modeling/configuration.md
index 1eb5b56..e375197 100644
--- a/docs/mission-modeling/configuration.md
+++ b/docs/mission-modeling/configuration.md
@@ -6,18 +6,18 @@ A **mission model configuration** enables mission modelers to set initial missio
To use a mission model configuration the `@WithConfiguration` annotation must be used within the mission model's [package-info.java](./introduction.mdx#the-package-infojava-file) to register the configuration with Aerie.
-For example, the Aerie mission model template [package-info.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/firesat/package-info.java) makes use of this annotation:
+For example, the Aerie mission model template [package-info.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/missionmodel/package-info.java) makes use of this annotation:
```java
@MissionModel(model = Mission.class)
@WithConfiguration(Configuration.class)
-package firesat;
+package missionmodel;
import gov.nasa.jpl.aerie.merlin.framework.annotations.MissionModel;
import gov.nasa.jpl.aerie.merlin.framework.annotations.MissionModel.WithConfiguration;
```
-In this example `Configuration` is the class class containing all mission model configuration data. When the `@WithConfiguration` annotation is used, the model – defined within the `@MissionModel` annotation – must accept the configuration as the last constructor parameter. See [Mission.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/firesat/Mission.java):
+In this example `Configuration` is the class class containing all mission model configuration data. When the `@WithConfiguration` annotation is used, the model – defined within the `@MissionModel` annotation – must accept the configuration as the last constructor parameter. See [Mission.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/missionmodel/Mission.java):
```java
public Mission(final Registrar registrar, final Configuration config) {
@@ -44,7 +44,7 @@ Similarly to activities, the annotation processor will take care of all serializ
A `Configuration` can be a simple data class. For example:
```java
-package firesat;
+package missionmodel;
import gov.nasa.jpl.aerie.merlin.framework.annotations.Export;
import java.nio.file.Path;
diff --git a/docs/mission-modeling/introduction.mdx b/docs/mission-modeling/introduction.mdx
index 2f82be6..bbb066e 100644
--- a/docs/mission-modeling/introduction.mdx
+++ b/docs/mission-modeling/introduction.mdx
@@ -6,10 +6,13 @@ In Aerie, a mission model serves activity planning needs in two ways. First, it
## Creating a Mission Model
-You can create your first mission model by using our [GitHub template mission model repository](https://github.com/NASA-AMMOS/aerie-mission-model-template).
-See the template mission model repository [README](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/README.md#aerie-mission-model-template) for detailed build instructions.
+If you want to learn how to develop a mission model, head to our [mission modeling tutorial](../../tutorials/mission-modeling/introduction/),
+or check out our [GitHub template mission model repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) for an empty template.
You will need a public [GitHub.com](https://github.com/) account to download the Aerie Maven packages.
+If you do not want to develop a mission model and just want to try an example, you can download the [missionmodel.jar](https://github.com/NASA-AMMOS/aerie-modeling-tutorial/blob/main/missionmodel.jar) from the [Aerie modeling tutorial repository](https://github.com/NASA-AMMOS/aerie-modeling-tutorial).
+Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.
+
## The package-info.java File
A mission model must contain a [package-info.java](https://www.baeldung.com/java-package-info) file containing annotations that describe the highest-level features of the mission model. For example:
@@ -17,8 +20,8 @@ A mission model must contain a [package-info.java](https://www.baeldung.com/java
This `package-info.java` identifies the top-level class representing the mission model, and registers activity types that may interact with the mission model. Aerie processes these annotations at compile-time, generating a set of boilerplate classes which take care of interacting with the Aerie system.
@@ -35,8 +38,8 @@ The top-level model is received by activities, however, so it must make accessib
Mission resources are declared using `Registrar#discrete` or `Registrar#real` functions.
diff --git a/docs/overview/concept-of-operations.mdx b/docs/overview/concept-of-operations.mdx
index b81c698..583681f 100644
--- a/docs/overview/concept-of-operations.mdx
+++ b/docs/overview/concept-of-operations.mdx
@@ -2,7 +2,7 @@
## Introduction
-The planning, scheduling and sequencing are common needs across many space missions, yet a common solution does not yet exist. Many space missions clone and own legacy solutions inherited from a similar, previous mission. AMMOS is dedicated to provide solutions shared across missions, liberating them from re-inventing the wheel that address the same needs and major cost of maintenance. Aerie is the new generation AMMOS product, not only providing a powerful simulation framework like its predecessors, it also addresses the crucial need of enabling less expert users to input their planning requests, trigger simulations, automate scheduling and similar through a collaborative web application.
+Planning, scheduling and sequencing are common needs across many space missions, yet a common solution does not yet exist. Many space missions clone and own legacy solutions inherited from a similar, previous mission. AMMOS is dedicated to providing solutions shared across missions, liberating them from re-inventing the wheel and major cost of maintenance. Aerie is the new generation AMMOS product, not only providing a powerful simulation framework like its predecessors, it also addresses the crucial need of enabling less expert users to input their planning requests, trigger simulations, automate scheduling and similar through a collaborative web application.
Aerie is designed to address the following capability gaps:
@@ -11,12 +11,12 @@ Aerie is designed to address the following capability gaps:
- Allow missions to make use of existing libraries for modeling, and write custom code in their mission model as they see fit
- Allow missions to provide a web deployment of a planning tool such that operators with limited programming skills can create valid activity plans and run simulations
- Support real time collaboration and and parallel hypothesis testing such that many more iterations of an activity plan can be tested within the same time frame
-- Allow automation and manual modifications to coexist through out the planning process
-- Provide a low code constraint checking mechanism to validate simulation outputs which can be automated largely
-- Provide a low code scheduling mechanism that can scaffold parts of or generate complete activity plans according to goal snippets
-- Support an easy to use and verified translation from activities to flight system recognized sequences of commands
+- Allow automation and manual modifications to coexist throughout the planning process
+- Provide a low-code constraint checking mechanism to validate simulation outputs which can be largely automated
+- Provide a low-code scheduling mechanism that can scaffold parts of or generate complete activity plans according to goal snippets
+- Support an easy-to-use and verified translation from activities to sequences of commands that are recognized by the flight system
-Note that none of the capabilities above are completely new. Different software solutions have offered pieces of the listed capabilities, different or more limited flavors. Aerie's mission is to cover as many key steps in the whole activity planning and sequencing workflow in one deployed tool with dedicated components.
+Note that none of the capabilities above are completely new. Other software solutions have offered pieces of the listed capabilities in different or more limited flavors. Aerie's mission is to cover as many key steps in the whole activity planning and sequencing workflow in one deployed tool with dedicated components.
Although Aerie does not aim to be a complete solution for every mission, it has a strong emphasis on extensibility, customization and 3rd party tool integrations.
@@ -28,23 +28,23 @@ Mission operations may involve labour intensive, error prone tasks such as autho
### Design for customization and configurability
-Aerie tools and services allow systems and services to be configured customized to meet different mission and user needs. For instance, Aerie simulations can be configured to run at different fidelity levels depending on the planners' need at different steps of the planning process. Or an Aerie deployment can be customized to accommodate many parallel simulation and scheduling requests scaled for usage. Similarly Aerie UI can be customized by mission system or by the users interactively to display data relevant for different contexts.
+Aerie tools and services allow systems and services to be customized to meet different mission and user needs. For instance, Aerie simulations can be configured to run at different fidelity levels depending on the planners' need at different steps of the planning process. Or an Aerie deployment can be customized to accommodate many parallel simulation and scheduling requests scaled for usage. Similarly Aerie UI can be customized by the mission system or by the users interactively to display data relevant for different contexts.
### Design for usability
-An integral design guideline for Aerie is to improve user experience for all users. Note that the experience of mission modelers creating a mission model with Aerie framework is highly different than the experience of scientists performing activity planning through a web application, or the experience of an engineer deploying Aerie for all mission users. The Aerie mission modeling framework is striking a tough balance between expressibility and ease of learning. One of the key advantages of using Aerie for modeling is the discrete event simulation engine that takes care of integrating resources for the modelers, handling concurrency of events. This allows mission modelers to model unit behaviors independent from one another. Similarly Aerie web application enables scientists engineers to trigger simulation with a no code approach, and perform automated scheduling and simulation analysis with a low code approach.
+An integral design guideline for Aerie is to improve user experience for all users. Note that the experience of mission modelers creating a mission model with Aerie framework is highly different than the experience of scientists performing activity planning through a web application, or the experience of an engineer deploying Aerie for all mission users. The Aerie mission modeling framework is striking a tough balance between expressibility and ease of learning. One of the key advantages of using Aerie for modeling is the discrete event simulation engine that takes care of integrating resources for the modelers, handling concurrency of events. This allows mission modelers to model unit behaviors independent from one another. Similarly Aerie web application enables scientists and engineers to trigger simulation with a no-code approach, and perform automated scheduling and simulation analysis with a low-code approach.
### Design for many contexts
-Aerie can be used in many different contexts other than mission operations where planning and scheduling generally follows strict processes. Aerie can be used to model and simulate any discrete events that effect shared resources. These resources can be on board the spacecraft or on the ground. Aerie can be effectively used in mission planning to generate and evaluate long term schedules for the purposes of validating high level mission requirements, and to derive low level requirements. Similarly Aerie can be used even earlier phases to develop mission concepts. By design Aerie does not implement mission business logic or dictate workflows.
+Aerie can be used in many different contexts other than mission operations where planning and scheduling generally follows strict processes. Aerie can be used to model and simulate any discrete events that affect shared resources. These resources can be on board the spacecraft or on the ground. Aerie can be effectively used in mission planning to generate and evaluate long-term schedules for the purposes of validating high-level mission requirements, and to derive low-level requirements. Similarly Aerie can be used in even earlier phases to develop mission concepts. By design Aerie does not implement mission business logic or dictate workflows.
### Eliminate duality in planning and sequencing
-Traditionally planning and sequencing are independent, serial processes where operators are responsible from accurately translating activities into spacecraft commands. This duality reduces efficiency, leads to redundant validations at the activity planning and sequencing steps, and can be error prone. Whereas, principles of and simulation are embarrassingly similar for activities and commands. Aerie aims to eliminate this duality by using the same simulation engine for activity and command simulations, which can provide an option for missions to do one simulation where abstracted activities decompose into actual commands.
+Traditionally planning and sequencing are independent, serial processes where operators are responsible for accurately translating activities into spacecraft commands. This duality reduces efficiency, leads to redundant validations at the activity planning and sequencing steps, and can be error prone. Aerie aims to eliminate this duality by using the same simulation engine for activity and command simulations, which can provide an option for missions to do one simulation where abstracted activities decompose into actual commands.
### Design for customization
-Aerie tools and services should be extendable and customizable to answer the needs of missions with different levels of complexity. In the following sections, we describe how Aerie can be used at its full capacity by a highly complex and automated mission. On the other end of the spectrum, a mission may choose manual activity planning, basically not utilizing modeling, simulation or scheduling capabilities, while leveraging command expansion to automate sequence generation based on planning inputs. The mission can utilize its flight software simulator to simulate commands, upload resulting resource profiles back to Aerie for visualization and analysis. We provide a few examples of such different mission operations Section 4.14.
+Aerie tools and services should be extendable and customizable to answer the needs of missions with different levels of complexity. In the following sections, we describe how Aerie can be used at its full capacity by a highly complex and automated mission. On the other end of the spectrum, a mission may choose manual activity planning, basically not utilizing modeling, simulation or scheduling capabilities, while leveraging command expansion to automate sequence generation based on planning inputs. The mission can utilize its flight software simulator to simulate commands, upload resulting resource profiles back to Aerie for visualization and analysis. We provide a few examples of such different mission operations in Section 4.14.
+
+## Taking a Snapshot
+
+Snapshots can via one of two methods:
+1. Clicking on the Plan's name in the navbar, then clicking "Take Snapshot"
+2. Clicking on the "Take Snapshot" button in the Plan Metadata Pane
+
+Either option will then present you with a modal where you can name the snapshot and optionally provide a description and tags.
+Note that snapshot names must be unique per plan.
+
+
+
+
+
+
+ Figure 1: Aerie UI - How to Take a Plan Snapshot
+
+
+
+## Viewing a Snapshot
+
+You can view the snapshots taken for a specific plan by clicking on the Plan's name in the navbar, then clicking "View Snapshot History".
+Doing so will open the Plan Metadata Pane, where a list of all snapshots taken will be displayed.
+If a snapshot has been simulated, an icon will be present indicating the results of the most recent simulation for that snapshot.
+
+You can filter this list to only display snapshots for the currently selected simulation dataset by selecting the "Snapshot" badge to the left of the "Take Snapshot" button.
+
+
+
+
+
+
+ Figure 2: Aerie UI - How to View a Plan Snapshot
+
+
+Clicking on a snapshot will open a preview of its contents. From here, you can examine activities and related simulation datasets.
+
+
+
+ Figure 3: Aerie UI - Viewing a Plan Snapshot
+
+
+## Restoring a Snapshot
+
+If you would like to update a plan to match the state of a snapshot, you can do so by clicking on the "Restore Snapshot" button seen while previewing a snapshot.
+
+When restoring a snapshot, you can optionally choose to take a snapshot of the current state of the plan prior to restoring.
+
+
+
+
+
+
+ Figure 4: Aerie UI - How to Restore a Plan Snapshot
+
+
+The snapshot you restored will remain in the list in case you need to restore to it again in the future.
diff --git a/docs/planning/timeline-controls.mdx b/docs/planning/timeline-controls.mdx
new file mode 100644
index 0000000..40944c2
--- /dev/null
+++ b/docs/planning/timeline-controls.mdx
@@ -0,0 +1,49 @@
+import Link from '@docusaurus/Link';
+import timelineIconTray from './assets/timeline-icon-tray.png';
+import timelineInterpolationOff from './assets/timeline-cursor-interpolation-off.png';
+import timelineInterpolationOn from './assets/timeline-cursor-interpolation-on.png';
+
+# Timeline Controls
+
+Here we describe the timeline rendering and interaction options that are not part of the Aerie UI View. Above the timeline is a tray of icon buttons that can be used to control how data is rendered and interacted with on the timeline.
+
+
+
+ Figure 1: Aerie UI - Timeline Icon Tray
+
+
+The following controls are available:
+
+1. `Auto Scroll to Offscreen Selections` - Automatically scrolls the timline to the selected activity directive or span. This can be helpful when selecting directives or spans from their associated tables.
+2. `Decimation` - Perform on the fly min-max decimation of line layer points for improved timeline rendering performance. [Learn more about decimation below](#line-layer-decimation).
+3. `Cursor Value Interpolation` - Show interpolated value when hovering over resources. [Learn more about interpolation below](#cursor-value-interpolation).
+4. `Limit Tooltip to Line` - When enabled, the timeline tooltip will only appear when hovering near a resource line segment. When disabled, the tooltip will appear when hovering over any part of a resource layer.
+5. `Timeline Tooltip Visibility` - Toggle timeline tooltip visibility.
+6. `Timeline Modes` - Toggle between `Pan & Zoom` and `Interaction` modes. [Learn more about timeline modes below](#timeline-modes).
+7. `Time Step` - Slide the time view window to forwards and backwards.
+8. `Zoom` - Zoom in and out of the plan time window.
+9. `Copy URL` - Copy URL including plan, visible time window, selection, and simulation dataset to clipboard.
+10. `Drag Activities` - Enables dragging of activity directives in the timeline.
+11. `Timeline Options Menu` - Displays timeline controls with additional information.
+
+## Line Layer Decimation
+
+Decimation can be enabled on the Aerie timeline in order to more peformantly render line plots. This option can be useful when loading large quantities of profile segments (tens of thousands) and when visualizing a large number of moderately dense resource plots. Decimation of resources is performed on the fly using the min-max decimation algorithm. Min-max decimation reduces the number of points drawn on screen while accurately maintaining the shape of the data. This is achieved by binning the points by the number of available pixels and for each bin plotting the first point, the min, the max, and the last point. If decimation is enabled, line segments will always be rendered and individual points will only be rendered if the data no longer requires decimation (i.e. the number of pixels available is greater than the number of original points).
+
+## Cursor Value Interpolation
+
+Aerie will display a tooltip with resource values when you hover over a line plot. By default, Aerie will select the nearest point to your cursor position as shown in Figure 2. If Cursor Value Interpolation is enabled, Aerie will display a linearly interpolated value in the tooltip based on the two points neigboring your cursor's time position, as shown in Figure 3. The neighboring points used for the interpolation will be indicated by ghosted red triangles.
+
+
+
+ Figure 2: Aerie UI - Timeline Cursor Value Interpolation Off
+
+
+
+
+ Figure 3: Aerie UI - Timeline Cursor Value Interpolation On
+
+
+## Timeline Modes
+
+The default mode of the Aerie timeline is `Interaction` mode which enables you to click on activities and spans. Switching to `Pan and Zoom` mode will disable clicking on activities and spans and instead let you click and drag anywhere on the timeline to pan and scroll using the trackpad or mousewheel to zoom. `Pan and Zoom` mode can also be temporarily entered by holding down the `Command` key on Mac and `Control` key on Windows and then clicking, dragging, and zooming. Finally, while in `Interaction` mode, you can hold down the middle mouse button and drag (if you have one available) to pan.
diff --git a/docs/planning/timeline-editing.mdx b/docs/planning/timeline-editing.mdx
index 0a90924..c133b1f 100644
--- a/docs/planning/timeline-editing.mdx
+++ b/docs/planning/timeline-editing.mdx
@@ -1,7 +1,10 @@
import timelineEditor from './assets/timeline-editor.png';
import timelineRowEditor from './assets/timeline-row-editor.png';
+import timelineActivityOptionsEditor from './assets/timeline-activity-options-editor.png';
+import timelineActivityOptionsMode from './assets/timeline-activity-options-mode.png';
+import timelineYAxisSettings from './assets/timeline-y-axis-settings.png';
+import timelineActivityTree from './assets/timeline-activity-tree.png';
import timelineActivityEditingDemo from './assets/timeline-activity-layer-adding.mov';
-import timelineActivityHeightEditingDemo from './assets/timeline-activity-height-editing.mov';
import timelineLineLayerEditingDemo from './assets/timeline-line-layer-editing.mov';
# Timeline Editing
@@ -16,11 +19,9 @@ Edit general timeline properties from within the timeline editor panel. If multi
Changes made in the Timeline Editor are not automatically saved and must be saved to the UI view.
:::
-
+
-
- Figure 1: Aerie UI Timeline Editor - Manage Timeline properties, Vertical Guides, and Rows
-
+ Figure 1: Aerie UI Timeline Editor - Manage Timeline properties, Vertical Guides, and Rows
### Edit Timeline Margins
@@ -39,41 +40,102 @@ Click on the plus button to add a new row to the timeline. A row will be added b
Edit row properties from within the timeline row editor. If multiple rows exist you can use the top dropdown to edit different rows. A blue highlight will appear around the row in the timeline that you are currently editing. You can also edit a row by clicking on the pencil icon in the header of a row in the timeline.
-
-
-
+
+
+
Figure 2: Aerie UI Timeline Row Editor - Manage Row properties, Horizontal Guides, Y Axes, and Layers
### Add an Activity Layer
-To visualize activities on the timeline add a new layer using the plus button in the Layers section. By default new layers have a layer type of Activity. Additionally, the default Aerie UI view has a single row with a single activity layer with all activities visualized by default. Manage which activities are visualized in an activity layer by clicking on the search input for the layer and selecting activities. Activities can be filtered by substring match using the input. Once you have a filter applied you can also select all matches using the Select X activities button at the bottom of the result list. You can also manage the color of the layer using the color picker. Below is a demonstration of this workflow.
+To visualize activities on the timeline add a new layer using the plus button in the Layers section. By default new layers have a layer type of Activity. Additionally, the default Aerie UI view creates a row with a single activity layer with all activities grouped by type. Manage which activities are visualized in an activity layer by clicking on the search input for the layer and selecting activities. Activities can be filtered by substring match using the input. Once you have a filter applied you can also select all matches using the Select X activities button at the bottom of the result list. You can also manage the color of the layer using the color picker. All activity layers within a row are drawn on the same canvas so that all of the activities are grouped and packed together correctly. Below is a demonstration of this workflow.
-### Managing Activity Layer Height
+### Manage how Activities are Rendered
-Rows by default have a manually specified height. The UI will pack directives and simulated activities in a layer to make the most efficient use of the available space. However if the packed content is still too big for the manually specified height the content will begin to overdraw upon itself. To resolve this issue you can input a larger manual height for the row or specify that the row automatically calculate the minimum height needed to prevent overdraw. Control the row height manually from within the Details section of the timeline row editor or by dragging on the bottom of the row. Alternatively use the Auto option from within the Resize Mode dropdown in the Details section to have the row automatically resize to the content.
+An Activity Options section will appear in the row editor when the row has at least one activity layer. Activity options govern how activities are rendered for this row.
-:::info Note
-Use of Auto mode can result in degraded Aerie UI performance when visualizing thousands of activities on the timeline. It is recommended that you use a smaller, manually specified height for this scenario. Alternatively you can filter the activities down to a more manageable set to improve performance.
-:::
+
+
+ Figure 3: Aerie UI Timeline Activity Options Editor - Manage Activity Rendering
+
-Below is a demonstration of this workflow.
+#### 1. Activity Display Mode
-
+Activities can be rendered in two ways:
+
+- `Grouped Mode`: Activities are recursively grouped by type. In this mode, activity groups appear in the left side of the row and can be expanded to reveal the directives and spans within each type group. If a directive/span has descendents, the directive/span can be expanded to reveal its grouped descendents. This behavior continues down the decomposition tree until the resulting directive/span has no descendents. This mode is useful for understanding larger sets of activities in a broad sense across an entire plan, especially if the plan is long or contains a significant number of activities that cannot easily be visualized in a small area.
+- `Compact Mode`: Activities from all of the layers are packed together in a space efficient waterfall manner. This mode is useful for visualizing smaller sets of activities in a more traditional timeline view. In this mode the row will not autosize and must be manually adjusted to accommodate the current activity packing solution. This allows for a more precise adjustment of the density in the timeline.
+
+
+
+ Figure 4: Aerie UI Timeline Activity Options Display Mode
+
+
+#### 2. Activity Label Visibility
+
+There are several options to control how activity labels appear in the timeline:
+
+- `On`: Always show activity labels regardless of collision.
+- `Off`: Never show activity labels.
+- `Auto`: Show activity labels when they do not collide with other labels or activities.
+
+#### 3. Directive and Span Visibility
+
+By default, both directives and spans are shown in a row. Alternatively you may choose to show only directive or only spans.
+
+#### 4. Hierarchy Root
+
+_This option is only available in `Grouped` mode._
+
+Affects which activities appear in the initial type groups. By default, `Flat` is selected.
+
+- `Flat`: Both activity directives and spans will appear in the top most type groups. This is useful when examining all activities resulting from a simulation without needing to consider activity decomposition.
+- `By Directive`: Only activity directives will appear in the top most type groups, effectively hiding any child spans until further down in the trees. This is useful when examining the timeline from a decomposition perspective.
+
+#### 5. Activity Height
+
+Sets the height of activities in the row.
+
+### Understanding the Grouped Activity Tree
+
+
+
+ Figure 5: Aerie UI Timeline Activity Tree
+
+
+In `Grouped` mode the activity tree presented in the row header has several important indicators and actions:
+
+1. `Filter Activities by Time Window` - Automatically filter nodes in the tree when you zoom and pan around in the plan.
+2. This folder represents a group of activities whose type is `BananaNap`. Groups can contain both directives and spans.
+3. This icon represents a directive without a span.
+4. This icon represents a directive and its root span. The `parent` span has children spans which can be expanded as demonstrated here.
+5. Click on this button while hovering over an expandable folder/element in the tree to select that directive/span. In this case, the `parent` row is blue since it has been selected. Note that when selecting a combined directive and span node, the span details will be preferred over the directive details. You can jump between span and directive using a button in the top right of the `Selected Activity` panel.
+6. This icon represents a span. In this case, `child` is a span that also has children which are expanded below and grouped appropriately.
+7. This node is a span that does not have any children. The node can be selected by clicking directly on the node. Double click to open the `Selected Activity` panel if not already open.
### Add a Resource Line Layer
-To show resources on the timeline in a line plot, add a new layer using the plus button in the Layers section and change the layer type to Line. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the line layer. To select resources to plot on this layer, click on the input on the layer and select one or more resources. Control the min and max of the plot by modifying the associated Y axis above. You can use the "fit" button to automatically fit the min and max of the axis to the bounds of the data on demand.
+To show resources on the timeline in a line plot, add a new layer using the plus button in the Layers section and change the layer type to Line. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the line layer. To select resources to plot on this layer, click on the input on the layer and select a resource. It is not recommended to select more than one resource.
:::info Note
-Y axes are independent of layers. When you create a new line or x-range layer the layer will automatically be assigned to a Y axis. To modify which Y axis a layer is associated with you, click on the settings icon for the layer and select a Y axis from the Y Axis dropdown.
+Y axes are independent of layers. When you create a new line or x-range layer the layer will automatically be assigned to a Y axis. To modify which Y axis a layer is associated with, click on the settings icon for the layer and select a Y axis from the Y Axis dropdown.
:::
Below is a demonstration of this workflow.
@@ -86,10 +148,27 @@ Below is a demonstration of this workflow.
To show resources on the timeline in as an x-range plot, add a new layer using the plus button in the Layers section and change the layer type to X-Range. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the x-range layer. A Y Axis is only used to provide a label to the x-range plot. To select resources to plot on this layer, click on the input on the layer and select one or more resources.
+### Manage Y Axis Settings
+
+Y Axes have additional options available in the settings menu popover. By default, horizontal ticks are shown and Y Axis domain fitting is set to `Autofit Time Window`. The domain fitting option controls how the Y Axis domain behaves in response to your plan and current time window and has three modes:
+
+1. `Autofit Plan`: Automatically fit the domain to the bounds of all resources associated with the axis across the entire plan.
+2. `Autofit Time Window`: Automatically fit the domain to the bounds of all resources associated with the axis, filtered to the current time window. As you zoom and pan through the plan, the bounds will automatically update and the resources will rescale on the canvas.
+3. `Manual`: Manually enter a static min and max for the axis.
+
+
+
+ Figure 6: Aerie UI Timeline Y Axis Settings
+
+
+### Manage Line and X-Range Names
+
+By default, line and x-range layers will use the name of the resource associated with them when displayed in the row legend on the left and in the tooltip when hovering over a resource. When available, units will be appended to the resource name. To override this resource name, enter a name for the resource within the layer settings menu. Units will still be appended to your custom name.
+
### Manage Horizontal Guides
Horizontal guides can be added to a row when a row has at least one line or x-range layer. Add a horizontal guide using the plus button in the Horizontal Guides section. Horizontal guides are associated with a single Y axis and will use the first available Y axis by default. You can edit the name, Y value, associated Y axis, and color of each horizontal guide from within this section.
-### Manage Layer Order
+### Layer Order
-Click and drag on a layer to re-order the layer. Note that the layers within a row are drawn on top of each other, meaning that layers will appear in reverse order from the layers list.
+Layers have a fixed draw order in a row. X-range layers are on the bottom, activity layers are in the middle, and line layers are on top.
diff --git a/docs/planning/ui-views.md b/docs/planning/ui-views.md
index 1fe87d2..3879d0c 100644
--- a/docs/planning/ui-views.md
+++ b/docs/planning/ui-views.md
@@ -137,10 +137,11 @@ interface Timeline {
}
```
-To visualize data in a timeline you need to add row objects to the `rows` array. A row is a layered visualization of time-ordered data. Each layer of a row is specified as an object of the `layers` array. The interfaces for a `Row` and `Layer` are as follows:
+To visualize data in a timeline you need to add row objects to the `rows` array. A row is a layered visualization of time-ordered data. Each layer of a row is specified as an object of the `layers` array. The interfaces for a `Row`, `Layer`, and `ActivityOptions` are as follows:
```ts
interface Row {
+ activityOptions?: ActivityOptions;
autoAdjustHeight: boolean;
expanded: boolean;
height: number;
@@ -160,9 +161,26 @@ interface Layer {
id: number;
yAxisId: number | null;
}
+
+type ActivityOptions = {
+ // Height of activity subrows
+ activityHeight: number;
+
+ // Whether or not to display only directives, only spans, or both in the row
+ composition: 'directives' | 'spans' | 'both';
+
+ // Describes the primary method in which activities are visualized within this row
+ displayMode: 'grouped' | 'compact';
+
+ // If 'directive' the activities are grouped starting with directive types, if 'flat' activities are grouped by type regardless of hierarchy
+ hierarchyMode: 'directive' | 'flat';
+
+ // Activity text label behavior
+ labelVisibility: 'on' | 'off' | 'auto';
+};
```
-Here is a JSON object that creates a single row with one activity layer. Notice the `filter` property, which is a [JavaScript Regular Expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) that specifies we only want to see `activity` of `type` `.*`. This is a regex for giving all activity types.
+Here is a JSON object that creates a single row with one activity layer.
```json
{
@@ -175,7 +193,7 @@ Here is a JSON object that creates a single row with one activity layer. Notice
"activityColor": "#283593",
"activityHeight": 20,
"chartType": "activity",
- "filter": { "activity": { "type": ".*" } },
+ "filter": { "activity": { "types": ["BiteBanana", "PickBanana"] } },
"id": 0,
"yAxisId": null
}
@@ -196,12 +214,7 @@ interface Axis {
}
interface Label {
- align?: CanvasTextAlign;
- baseline?: CanvasTextBaseline;
color?: string;
- fontFace?: string;
- fontSize?: number;
- hidden?: boolean;
text: string;
}
```
@@ -212,6 +225,13 @@ Here is the JSON for creating a row with two overlaid `resource` layers. The fir
```json
{
+ "activityOptions": {
+ "activityHeight": 16,
+ "composition": "both",
+ "displayMode": "grouped",
+ "hierarchyMode": "flat",
+ "labelVisibility": "auto"
+ },
"autoAdjustHeight": false,
"height": 100,
"horizontalGuides": [],
@@ -219,7 +239,7 @@ Here is the JSON for creating a row with two overlaid `resource` layers. The fir
"layers": [
{
"chartType": "line",
- "filter": { "resource": { "name": "peel" } },
+ "filter": { "resource": { "names": ["peel"] } },
"id": 1,
"lineColor": "#283593",
"lineWidth": 1,
@@ -228,7 +248,7 @@ Here is the JSON for creating a row with two overlaid `resource` layers. The fir
},
{
"chartType": "line",
- "filter": { "resource": { "name": "fruit" } },
+ "filter": { "resource": { "names": ["fruit"] } },
"id": 2,
"lineColor": "#ffcd69",
"lineWidth": 1,
diff --git a/docs/planning/upload-mission-model.mdx b/docs/planning/upload-mission-model.mdx
index 9a3aac0..8b98228 100644
--- a/docs/planning/upload-mission-model.mdx
+++ b/docs/planning/upload-mission-model.mdx
@@ -8,11 +8,11 @@ To get the Aerie services running locally first follow the [fast track instructi
## Instructions
-1. First develop your mission model using the [mission modeling documentation](../../mission-modeling/introduction). If you do not want to develop a mission model and just want to try an example, you can download the [firesat.jar](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/firesat.jar) from the [Aerie mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template). Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.
+1. First develop your mission model using the [mission modeling documentation](../../mission-modeling/introduction). If you want to learn how to develop a mission model, head to our [mission modeling tutorial](../../tutorials/mission-modeling/introduction). If you do not want to develop a mission model and just want to try an example, you can download the [missionmodel.jar](https://github.com/NASA-AMMOS/aerie-modeling-tutorial/blob/main/missionmodel.jar) from the [Aerie modeling tutorial repository](https://github.com/NASA-AMMOS/aerie-modeling-tutorial). Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.
1. Navigate to the `/models` page in the Aerie UI. If you are running Aerie locally it is at [http://localhost/models](http://localhost/models).
-1. Use the form on the `/models` page to upload the mission model `.jar` file. Give the mission model a name ("FireSat" in this example). The version can be any string (preferably a semantic version string like `1.0.0`). After you fill in all the fields click the 'Create' button to upload the model. Here is a video demonstration:
+1. Use the form on the `/models` page to upload the mission model `.jar` file. Give the mission model a name ("MissionModel" in this example). The version can be any string (preferably a semantic version string like `1.0.0`). After you fill in all the fields click the 'Create' button to upload the model. Here is a video demonstration:
+ 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
- 
- 
+ 
+ 
+ 
+