Using plugins in Amazon Q Apps
If plugins are configured for your Amazon Q Business application environment you
can add these to a Amazon Q Apps you're creating. Once you add a plugin to your Q Apps,
your app users will be able to perform plugin actions from within your Q Apps.
All plugins (new and legacy built-in plugins, and custom plugins) configured in the
Amazon Q Business console will be available for Q App creators to use.
You can add only one action per plugin card.
The following section outlines how to add plugins to your Q Apps using both the
AWS Management Console and the AWS CLI.
Prerequisites for adding
plugins
Before your web experience users can create and use plugins, the web experience
IAM role for your application environment must have the correct permissions to perform the
necessary actions. We recommend updating your web experience IAM policy following
the steps outlined in Prerequisites for configuring Amazon Q Business
built-in plugins.
Adding plugins in Amazon Q Apps
To add a plugin to your Q App you can use either the AWS Management Console or the CreateQApp API operation. The
following tabs provide a procedure for the console and code examples for the
AWS CLI.
You can also add a plugin to your Q App through your Amazon Q Business
web experience URL.
- Console
-
To add a plugin card to an
Q App
-
Sign in to the AWS Management Console and open the Amazon Q Business
console.
-
In Applications, select the name of your
application environment from the list of applications.
-
From the left navigation menu, choose
Enhancements, and then choose
Amazon Q Apps.
-
In the Amazon Q Apps in library section,
choose the Q Apps that you want to add a plugin card to, and
then select the web experience URL for that Q Apps.
-
From the Q Apps App library navigate to
your app and select Open.
-
On the Q App page that opens, select Add
card, and then select
Actions.
-
From the Actions menu that opens up on
the right, do the following:
-
For Title – Add a title
for the card.
-
For Plugin – Select the
plugin you want to add.
Then, choose the actions you want your plugin to be able
to perform.
You can only add one action per plugin
card.
-
For Prompt – In the prompt
section, you get a dropdown of actions for the plugin
you select. Once you select an action in the dropdown,
your prompt will be populated with a recommended
template that you can use for configuration. We
recommend that Q App creators follow the generated
prompt when writing their own prompts to achieve better
results.
-
Select Save.
- AWS CLI
-
To add a plugin to an Q App
// Create an app with a single plugin card
aws qapps create-q-app \
--title appTitle
\
--instance-id qBusinessApplicationId
\
--description pluginDescription
\
--app-definition '{"cards":[{"qPlugin":{"type":"q-plugin","title":"Action Card","id":"cardUUID
","pluginId":"QBusinessPluginId
","actionIdentifier":"pa:jira:999.0_0:/rest/api/2/issue:POST
","prompt":"Create a task in my project
"}}]}'
Using plugins in Amazon Q Apps
To use a plugin within a Q App you can use either the Amazon Q Business web
experience URL or the StartQAppSession API operation. The
following tabs provide a procedure for the console and code examples for the
AWS CLI.
- Web experience
-
To use a plugin in an Q App
-
From your Q App with plugins, select
Run.
A window will open up asking you to log in to your
third party plugin
account.
-
After you login, Q Apps displays a dialog box asking you to
grant your Q App permission to access your
third party plugin account. From the
box, select Allow.
If there are multiple plugins configured for a Q App, the
authentication flow for the second app occurs after the
first one.
-
After a successful connection, your plugin card will display a
form where you can fill in the details for the action you are
taking.
-
After filling in the details needed, select
Create.
Your plugin card displays a success message when your action
completes successfully.
- AWS CLI
-
To use a plugin in an Q App
// start execution of an app
aws qapps start-q-app-session \
--app-id fill in from create or get q app response
\
--app-version fill in from create or get q app response
\
--instance-id qBusinessApplicationId
\
// If you have input cards that should be passed to the plugin:
aws qapps start-q-app-session \
--app-id fill in from create or get q app response
\
--app-version fill in from create or get q app response
\
--initial-values '{"cardId":"fill in from create q app input or get q app response
","value":"fill in
"}' \
--instance-id qBusinessApplicationId
\
// To get the status of an app, and results (if any):
aws qapps get-q-app-session \
--session-id fill in from StartQAppSession response
\
--instance-id qBusinessApplicationId
\
//To provide follow up messages to an app that is waiting for additional input:
aws qapps update-q-app-session \
--session-id fill in from StartQAppSession response
\
-- values '{"cardId":"fill in
","value":"fill in
"}'
--instance-id qBusinessApplicationId
\