From 770c5b648164fc3b54dfab1c7a7aa0370223fcfd Mon Sep 17 00:00:00 2001 From: Cody Hansen Date: Thu, 5 Oct 2023 06:23:33 -1000 Subject: [PATCH 1/2] Added some basic extension documentation --- docs/planning/extensions.mdx | 64 ++++++++++++++++++++++++++++++++++++ sidebars.js | 3 +- 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/planning/extensions.mdx diff --git a/docs/planning/extensions.mdx b/docs/planning/extensions.mdx new file mode 100644 index 0000000..6295543 --- /dev/null +++ b/docs/planning/extensions.mdx @@ -0,0 +1,64 @@ +# 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; +}; +``` diff --git a/sidebars.js b/sidebars.js index 1b46871..281ac34 100644 --- a/sidebars.js +++ b/sidebars.js @@ -81,7 +81,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', @@ -117,6 +117,7 @@ const sidebars = { 'planning/ui-views', 'planning/timeline-editing', 'planning/advanced-incons', + 'planning/extensions', ], }, { From 61d9c86795440acc9357560f26dce74e843145e4 Mon Sep 17 00:00:00 2001 From: Cody Hansen Date: Mon, 16 Oct 2023 06:11:38 -1000 Subject: [PATCH 2/2] Added an API page for extensions and marked them as an advanced topic --- docs/api/examples/advanced-extensions.mdx | 58 +++++++++++++++++++ ...extensions.mdx => advanced-extensions.mdx} | 2 +- sidebars.js | 8 ++- 3 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 docs/api/examples/advanced-extensions.mdx rename docs/planning/{extensions.mdx => advanced-extensions.mdx} (98%) diff --git a/docs/api/examples/advanced-extensions.mdx b/docs/api/examples/advanced-extensions.mdx new file mode 100644 index 0000000..d085e25 --- /dev/null +++ b/docs/api/examples/advanced-extensions.mdx @@ -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 + } +} +``` diff --git a/docs/planning/extensions.mdx b/docs/planning/advanced-extensions.mdx similarity index 98% rename from docs/planning/extensions.mdx rename to docs/planning/advanced-extensions.mdx index 6295543..992db0f 100644 --- a/docs/planning/extensions.mdx +++ b/docs/planning/advanced-extensions.mdx @@ -1,4 +1,4 @@ -# Extensions +# 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: diff --git a/sidebars.js b/sidebars.js index 281ac34..e42a079 100644 --- a/sidebars.js +++ b/sidebars.js @@ -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', @@ -117,7 +121,7 @@ const sidebars = { 'planning/ui-views', 'planning/timeline-editing', 'planning/advanced-incons', - 'planning/extensions', + 'planning/advanced-extensions', ], }, {