Skip to content

Commit

Permalink
Added some basic extension documentation (#87)
Browse files Browse the repository at this point in the history
* Added some basic extension documentation
  • Loading branch information
cohansen authored Oct 16, 2023
1 parent 893b50c commit 5dd9739
Show file tree
Hide file tree
Showing 3 changed files with 129 additions and 2 deletions.
58 changes: 58 additions & 0 deletions docs/api/examples/advanced-extensions.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Advanced - Extensions

## Creating an Extension

```graphql
mutation InsertExtensions($object: extensions_insert_input!) {
insert_extensions(
objects: { description: "", label: "My External Application", url: "https://externalapp/api/test" }
) {
returning {
id
}
}
}
```

## Creating an Extension Role

This is an example query that would allow the `viewer` role the ability to execute the extension with id `1`. Only defined roles will be able to call the extension through the UI.

```graphql
mutation InsertExtensionRoles($object: extension_roles_insert_input!) {
insert_extension_roles(objects: { extension_id: 1, role: "viewer" }) {
returning {
id
}
}
}
```

## Deleting an Extension

The following query will delete an extension and cascade to delete any assigned roles for that extension as well.

```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
}
}
```
64 changes: 64 additions & 0 deletions docs/planning/advanced-extensions.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Advanced - Extensions

Extensions are external tools that can be invoked directly from inside of Aerie. If there are not any extensions defined the button to view them will be hidden. When an Extension is called, the following values are passed along in the request body:

- `gateway` - The URL for the current instance's Gateway server.
- `hasura` - The URL for the current instance's Hasura server.
- `planId` - The id of the plan the user is looking at.
- `selectedActivityDirectiveId` - The id of the selected activity directive (if applicable).
- `simulationDatasetId` - The id of the last run simulation (if applicable).

After the Extension is ran, it is expecting the following response:

```json
{
"message": "",
"success": true,
"url": ""
}
```

The message will be displayed as a Toast inside of Aerie. `success` can be true or false to indicate if the Extension ran successfully or not. The `url` is optional and can be a link to a file or another webpage that will be opened in a new tab if provided.

There isn't currently a way to insert an extension through the UI, but we can use Hasura to create them with an API call.

```graphql
mutation InsertExtension($extension: extensions_insert_input!) {
insert_extension_one(object: $extension) {
id
}
}
```

The `$extentsion` query variable has the following type definition:

```ts
type Extension = {
description: string;
extension_roles: ExtensionRole[];
id: number;
label: string;
updated_at: string;
url: string;
};
```

After creating an Extension, you need to define the roles that are allowed to access it through the following Hasura mutation:

```graphql
mutation InsertExtensionRole($extensionRole: extension_roles_insert_input!) {
insert_extension_roles_one(object: $extensionRole) {
id
}
}
```

THe `$extensionRole` query variable has the following type definition:

```ts
type ExtensionRole = {
extension_id: number;
id: number;
role: string;
};
```
9 changes: 7 additions & 2 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,11 @@ const sidebars = {
type: 'doc',
id: 'api/examples/planning/introduction',
},
items: ['api/examples/planning/collaboration', 'api/examples/planning/anchors'],
items: [
'api/examples/planning/collaboration',
'api/examples/planning/anchors',
'api/examples/advanced-extensions',
],
},
'api/examples/simulation',
'api/examples/constraints',
Expand Down Expand Up @@ -81,7 +85,7 @@ const sidebars = {
items: [
'mission-modeling/activity-types/parameters',
'mission-modeling/activity-types/effect-model',
'mission-modeling/activity-types/durations'
'mission-modeling/activity-types/durations',
],
},
'mission-modeling/resources-and-models',
Expand Down Expand Up @@ -117,6 +121,7 @@ const sidebars = {
'planning/ui-views',
'planning/timeline-editing',
'planning/advanced-incons',
'planning/advanced-extensions',
],
},
{
Expand Down

0 comments on commit 5dd9739

Please sign in to comment.