# Configuring actions in Amazon Q Business
After you configure your application environment, you can optionally choose to add integrations to third-party services using Amazon Q Business plugins. Plugins enable your end users to perform specific tasks in third-party services—such as change status of a ticket, or view open incidents—from within their web experience chat. You can integrate with one of the built-in plugins, or use custom plugins to create your own integrations.
Amazon Q Business offers plugins to enhance your application's functionality. Plugins help streamline tasks and boost productivity by integrating external services into the Amazon Q Business chat interface.
Amazon Q Business supports two types of plugins: built-in plugins and custom plugins.
+ **Fully integrated plugins** – The Quick plugin is fully integrated with Amazon Q Business, and won't appear in the list of plugins in the web experience. This plugin gives an Amazon Q Business application access to insights and external databases through Amazon Quick. For more information, see [Using the Quick plugin to get insights from structured data](quicksight-plugin.md).
+ **Built-in plugins** – These plugins are pre-made for popular services like Jira, Salesforce, ServiceNow, and Zendesk. They allow users to perform tasks in these services directly from their Amazon Q Business chat. For example, an IT representative can create a ServiceNow incident without leaving the chat.
+ **Custom plugins** – These plugins let you connect Amazon Q Business with any third-party application. Users can then use natural language to access real-time data or perform actions in these applications.
**Note**
You can have up to 25 plugins for each application environment. Each plugin should serve a different purpose. You can activate, deactivate, edit, or delete plugins as needed.
**Topics**
+ [Using the Quick plugin to get insights from structured data](quicksight-plugin.md)
+ [Built-in plugins for Amazon Q Business](built-in-plugin.md)
+ [Custom plugins for Amazon Q Business](custom-plugin.md)
+ [Managing Amazon Q Business plugins](plugin-management.md)
# Using the Quick plugin to get insights from structured data
**Note**
The Quick plugin feature is in preview and is subject to change.
The Quick plugin is a fully integrated plugin that gives an Amazon Q Business application access to insights and external databases through [Amazon Quick](https://docs.aws.amazon.com/quicksight/latest/user/welcome.html). Quick is a business intelligence service that provides insights from your structured data, such as databases, data lakes, and data warehouses.
With the Quick plugin for Amazon Q Business, end users can get answers from this structured data directly in an Amazon Q Business application. You don't have to index or reformat this structured data, and you don't need to migrate it to Amazon Q Business.
For example, an end user might ask "What was the revenue per month for my business for 2023?" in their Amazon Q Business chat application. They would get answers based on your unstructured data in Amazon Q Business and, below this response, Quick answers based on structured data.
The response from QuickSight can include a multi-visual answer that includes an AI-generated narrative that summarizes key insights, and supporting visuals and interactive graphs to add context. If these visuals don't exist already, Quick can generate them on the fly based on the user's question and the available data in Quick and external databases.
To enable the plugin, you use Amazon Q Business to link your Amazon Quick account with your application and grant it permission to communicate with Quick. If you use the console, you can create the Quick account in Amazon Q Business. If you already have a Quick account, you can enable the plugin with the console or the [CreatePlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation.
After you create resources in Quick (including datasets, topics, and, optionally, dashboards), end users automatically start getting insights based on your structured data.
**Important**
The Quick plugin is fully integrated with Amazon Q Business, and won't appear in the list of plugins in the web experience. For every user prompt, it automatically queries Quick. For information about pausing the plugin, see [Pausing integration with Quick](quicksight-plugin-pausing-integration.md).
**Note**
If your [Admin controls and guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html) settings allow Amazon Q to automatically orchestrate end user chat queries across plugins and data sources, an Quick plugin will only activate if:
No other plugin actions (read or write requests requiring additional end user input through forms) are detected, or, in progress.
No end user authentication requests are pending.
**Topics**
+ [Pricing](#quicksight-plugin-pricing)
+ [Guidelines and requirements](#quicksight-plugin-req)
+ [Service access role](#quicksight-plugin-service-access-role)
+ [Configuring an Amazon Q Business application to use the plugin](quicksight-plugin-configuring-application.md)
+ [Getting data insights from Amazon Quick answers](quicksight-plugin-getting-data-insights.md)
+ [Pausing integration with Quick](quicksight-plugin-pausing-integration.md)
## Pricing
When you set up the integration with Quick, you assign one or more IAM Identity Center groups the Quick Admin Pro role. This role grants users access to all Generative BI capabilities in Amazon Quick. Your Quick administrator is responsible for adding and managing user permissions and configuring your Quick account.
The Quick Admin Pro role incurs additional costs. For more information about pricing, see [Amazon Quick pricing](https://aws.amazon.com/quicksight/pricing/). For more information about Pro roles in Amazon Quick, see [Get started with Generative BI](https://docs.aws.amazon.com/quicksight/latest/user/generative-bi-get-started.html).
When you link a Quick account and an Amazon Q Business application, the following groups get Pro subscription benefits at no additional cost:
+ Quick Admin Pro groups are added to the Amazon Q Business Pro subscription.
+ Existing Amazon Q Business Pro groups are assigned the Quick Reader Pro role.
## Guidelines and requirements
+ You must use IAM Identity Center for authentication for both Quick and Amazon Q Business. If your Amazon Q Business application doesn't use IAM Identity Center, you must create a new one that does. For information about creating an IAM Identity Center integrated application, see [Configuring an Amazon Q Business application using AWS IAM Identity Center](create-application.md).
+ Your Amazon Q Business application and Amazon Quick account must be in the same AWS Region.
+ To get answers from QuickSight in your web experience, you must add at least one index to your Amazon Q Business application. To learn how to add an index, see [creating an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ If you don't have a Quick account, you can create the account from the Amazon Q Business console when you configure your application to communicate with Quick.
+ You must authorize Amazon Q Business to communicate with Amazon Quick with a service role. For more information, see [Service access role](#quicksight-plugin-service-access-role).
+ The IAM role for your Amazon Q Business web experience must have `quicksight:GenerateEmbedUrlForRegisteredUserWithIdentity` permissions. For a policy example, see [IAM role for an Amazon Q Business web experience using IAM Identity Center](web-experience-iam-role-idc.md).
## Service access role
When you link your Quick account in the Amazon Q Business console, you specify an AWS Identity and Access Management (IAM) role that authorizes Amazon Q Business to communicate with Amazon Quick. In the console, you can choose to create this role with the correct permissions automatically configured. Or you can manually create it.
+ The role's permissions policy must grant `quicksight:PredictQAResults` for Amazon Quick topics and, if you create them, dashboards. For a permissions policy example, see [AWS managed policy: QBusinessQuicksightPluginPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonq-quicksight-policy).
+ The role's trust policy must grant Amazon Q Business `AssumeRole` and `SetContext`permissions as follows.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "QBusinessQuicksightManagedPolicyTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:SetContext"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
}
}
}
]
}
```
------
# Configuring an Amazon Q Business application to use the plugin
You configure an Amazon Q Business application to get insights from Quick answers in different ways depending on whether you have a Quick account.
+ If you don't have a Quick account, you can create one in the Amazon Q Business console, and then authorize Amazon Q Business to communicate with Quick.
+ If you already have a Quick account, you use the Amazon Q Business console or APIs to authorize Amazon Q Business to communicate with Amazon Quick.
After you configure your application, you create Quick datasets, and create and share Quick topics. Users can also get insights from Quick dashboards.
+ You can create datasets from new or existing data sources in Amazon Quick. You can use a variety of database data sources to provide data to Amazon Quick. For more information, see [Creating datasets](https://docs.aws.amazon.com/quicksight/latest/user/creating-data-sets.html).
+ Quick *topics* are collections of one or more datasets that represent a subject area that your business users can ask questions about. For more information, see [Working with Amazon Quick Q topics](https://docs.aws.amazon.com/quicksight/latest/user/quicksight-q-topics.html).
+ A Quick *dashboard* is a read-only snapshot of an analysis that you can share with other Amazon Quick users for reporting purposes. For more information, see [Sharing and subscribing to data in Amazon Quick](https://docs.aws.amazon.com/quicksight/latest/user/working-with-dashboards.html).
**Topics**
+ [Creating a new Amazon Quick account in the Amazon Q Business console](#quicksight-plugin-creating-new-qs-account)
+ [Linking an existing Quick account](#quicksight-plugin-linking-existing-account)
## Creating a new Amazon Quick account in the Amazon Q Business console
If you don't have an existing Quick account, you can use the Amazon Q Business console to create one and link the two accounts. Then you configure your Quick resources to start getting insights.
**To link a new Quick account**
1. Log in to the Amazon Q Business console.
1. In **Applications**, choose the name of your application from the list of applications.
1. In the navigation pane, choose **Amazon Quick**.
1. Choose **Create Quick Account**.
1. Give your new account a name, and specify the email address to use for account notifications.
1. Optionally, specify an email for product updates.
1. In **Assign Quick Admin Pro role**, choose the IAM Identity Center groups to assign the Quick Admin Pro role, and choose **Next**.
1. In **Service access**, create a new service role or use an existing one. This role authorizes Amazon Q Business to communicate with Amazon Quick. For more information, see [Service access role](quicksight-plugin.md#quicksight-plugin-service-access-role).
1. Choose **Authorize**.
1. Choose **Go to Quick** to go to your Quick account. There you create datasets, create and share Quick topics, and optionally create, publish, and share dashboards. After you configure these resources, end users start getting insights with Quick answers.
## Linking an existing Quick account
If you have an existing Quick account that uses AWS IAM Identity Center for authentication, you can authorize Amazon Q Business to communicate with Amazon Quick in the console or with the Amazon Q Business API. Then end users can start getting insights from new and existing Quick topics and dashboards.
### Using the console
If you have an existing Quick account that uses AWS IAM Identity Center for authentication, you can start getting insights after you authorize Amazon Q Business to communicate with Amazon Quick. To authorize Amazon Q Business, you use the Amazon Q Business console to assign IAM Identity Center groups the Admin Pro role. Then you specify a service role that grants Amazon Q Business access.
**To link an existing Quick account**
1. Log in to the Amazon Q Business console.
1. Choose your application.
1. In the navigation pane, choose **Amazon Quick**.
1. Choose **Authorize Quick answers**.
1. In **Assign Quick Admin Pro role**, choose the IAM Identity Center groups to assign the Admin Pro role. The Quick Admin Pro role includes additional costs. For more information, see Amazon Quick pricing.
1. In **Service access**, create a new service role or use an existing one. This role authorizes Amazon Q Business to communicate with Amazon Quick. For more information, see [Service access role](quicksight-plugin.md#quicksight-plugin-service-access-role).
1. Choose **Authorize**. After you authorize the connection, end users start getting insights from existing Quick resources.
1. To get insights from additional structured data resources, choose **Go to Quick** to go to your Quick account. There you can create additional datasets, topics, and dashboards.
### Using the API
To authorize Amazon Q Business with the API, you first use IAM Identity Center to assign groups the Admin Pro role. Also, if your Quick account was created before November 25, 2024 and uses IdC authentication, use the [UpdateApplicationWithTokenExchangeGrant](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateApplicationWithTokenExchangeGrant.html) API to update your subscription to allow integration with Amazon Q Business Then you use the [CreatePlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation to create a Quick plugin for an Amazon Q Business application.
The following code shows how to create a Quick plugin. For `idcApplicationArn`, specify the Amazon Resource Name (ARN) of your application in IAM Identity Center. For `roleArn`, specify an AWS Identity and Access Management (IAM) role that authorizes Amazon Q Business to communicate with Amazon Quick. For more information about this role, see [Service access role](quicksight-plugin.md#quicksight-plugin-service-access-role).
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type QUICKSIGHT \
--auth-configuration idcAuthConfiguration="{idcApplicationArn=arn:aws:sso:::application/,roleArn=arn:aws:iam:::role/AmazonQServiceRole}"
```
# Getting data insights from Amazon Quick answers
After you complete [Configuring the plugin](quicksight-plugin-configuring-application.md), end users automatically start getting insights from Quick as they submit queries. Unlike other plugins in Amazon Q Business, you don't have to enable Quick insights for end users.
The following example shows the results of a query with Quick answers enabled. It shows a response from Amazon Q Business and a Quick dashboard visual. To navigate to Quick and view details for the insights, choose **Explore insights**.
![\[Screenshot showing query results with QuickSight answers enabled, displaying both an Amazon Q Business response and a QuickSight dashboard visual with an "Explore insights" button for accessing more detailed information.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/quicksight-plugin-results.png)
# Pausing integration with Quick
After you enable the plugin, it automatically queries Amazon Quick for every user prompt. To stop automatically querying Quick, you can pause the plugin. When you pause the plugin, end users will no longer see insights from Quick answers. You continue to incur costs for Quick Admin Pro subscription users.
**To pause the integration**
1. Log in to the Amazon Q Business console.
1. Choose your application.
1. In the navigation pane, choose **Amazon Quick**.
1. In **QuickSight details**, choose **Pause Quick answers**.
1. Confirm your decision to pause the integration. When you're ready to resume, choose **Resume QuickSight Answers** on this page.
# Built-in plugins for Amazon Q Business
Built-in plugins have already been built by Amazon Q Business for common use cases across Jira, Salesforce, ServiceNow, and Zendesk. Amazon Q supports the following built-in plugins and actions:
+ **Asana ** – Create and update tasks.
+ **Confluence** – Search pages.
+ **Google Calendar** – Find and list events.
+ **Jira Cloud** – Read, create, search, and delete issues. Change issue status and move issues to sprint. Create, read, and delete sprints.
+ **Microsoft Exchange** – Get events from calendar and get emails.
+ **Microsoft Teams** – Send private and public, or channel messages.
+ **PagerDuty** – Get incidents, find similar incidents, find root cause incidents, get status updates on incidents, and update incidents, and find out who is on-call for escalation.
+ **Salesforce** – Manage cases (create, delete, update, get), Retrieve account lists, handle opportunities (create, update, delete, get, fetch specific), and fetch specific contacts.
+ **ServiceNow** – Create, read, delete, and update incidents. Create, update, delete, and read change requests.
+ **Smartsheet** – Search and read sheets, and list and get reports.
+ **Zendesk Suite** – Create and update tickets, and get ticket details.
+ **Jira (Legacy)** – Create an issue.
+ **Salesforce (Legacy)** – Create a case.
+ **ServiceNow (Legacy)** – Create an incident.
+ **Zendesk (Legacy)** – Create a ticket.
This section provides information about how you can use create, configure and use Amazon Q Business built-in plugins.
**Topics**
+ [Prerequisites for configuring Amazon Q Business built-in plugins](basic-plugins-prereqs.md)
+ [Configuring an Asana plugin for Amazon Q Business](asana-actions.md)
+ [Configuring an Atlassian Confluence plugin for Amazon Q Business](confluence-actions.md)
+ [Configuring a Google Calendar plugin for Amazon Q Business](gcal-actions.md)
+ [Configuring a Jira Cloud plugin for Amazon Q Business](jira-actions.md)
+ [Configuring a Microsoft Exchange plugin for Amazon Q Business](exchange-actions.md)
+ [Configuring a Microsoft Teams plugin for Amazon Q Business](teams-actions.md)
+ [Configuring a PagerDuty Advance plugin for Amazon Q Business](pagerduty-actions.md)
+ [Configuring a Salesforce plugin for Amazon Q Business](salesforce-actions.md)
+ [Configuring a ServiceNow plugin for Amazon Q Business](servicenow-actions.md)
+ [Configuring a Smartsheet plugin for Amazon Q Business](smartsheet-actions.md)
+ [Configuring a Zendesk Suite plugin for Amazon Q Business](zendesk-actions.md)
+ [Configuring a Jira plugin for Amazon Q Business](jira-plugin.md)
+ [Configuring a Salesforce plugin for Amazon Q Business](salesforce-plugin.md)
+ [Configuring a ServiceNow plugin for Amazon Q Business](servicenow-plugin.md)
+ [Configuring a Zendesk plugin for Amazon Q Business](zendesk-plugin.md)
+ [Using Amazon Q Business built-in plugins](using-plugins.md)
# Prerequisites for configuring Amazon Q Business built-in plugins
**Important**
Built-in plugins require Amazon Q Business Pro subscription. Users with Lite subscriptions cannot access built-in plugin functionality and must upgrade to Pro to use plugins.
**Note**
If you use the console and are creating a new web experience, Amazon Q Business creates an IAM role with the necessary permissions for you. If you're using the console and choose to use an existing web experience created before December 3, 2024, or you use the API, make sure to add the permissions below.
Before you can configure built-in plugins, make sure you've added the following permissions in you Amazon Q Business web experience’s IAM permissions policy:
+ In `Action` field for `"Sid": "QBusinessConversationPermissions`, add the following permissions to allow Amazon Q Business to list plugin actions:
```
{
"Sid": "QBusinessConversationPermissions",
"Effect": "Allow",
"Action": [
"qbusiness:ListPluginActions",
],
"Resource": "arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}"
}
```
Add the following permissions to allow Amazon Q Business to allow your end users to discover plugins in their web experience:
```
{
"Sid": "QBusinessPluginDiscoveryPermissions",
"Effect": "Allow",
"Action": [
"qbusiness:ListPluginTypeMetadata",
"qbusiness:ListPluginTypeActions"
],
"Resource": "arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}"
}
```
For the complete set of permissions needed for an IAM role, see [IAM role for an Amazon Q Business web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-experience-iam-role.html).
+ If you use the console or the API to create a plugin, make sure to add the following permissions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-id"
],
"Effect": "Allow",
"Sid": "SecretsManagerPermissions"
}
]
}
```
------
To allow Amazon Q to assume a role, use the following trust policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
}
}
}
]
}
```
------
# Configuring an Asana plugin for Amazon Q Business
Asana is a web-based work management platform that helps teams organize, collaborate, and plan tasks. If you’re a Asana user, you can create an Amazon Q Business plugin to allow your end users to create and update tasks from within their web experience chat.
To create a Asana plugin, you need configuration information from your Asana instance to set up a connection between Amazon Q and Asana and allow Amazon Q to perform actions in Asana.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#asana-plugin-prereqs)
+ [Service access roles](#asana-plugin-iam)
+ [Creating a plugin](#asana-plugin-create)
## Prerequisites
Before you configure your Amazon Q Asana plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Asana app in the Asana developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [OAuth](https://developers.asana.com/docs/oauth) in Asana Developer Documentation.
+ Make sure you've added following required scopes: `default`, `email`, `openid`, `profile`.
+ Select the workspace you want this app to work with under **Choose distribution method**.
+ Note the domain URL of your Asana instance. For example: `https://app.asana.com/api/1.0`.
+ Note your:
+ **Access token URL** – For Asana OAuth applications, this is `https://app.asana.com/-/oauth_token`.
+ **Authorization URL** – For Asana OAuth applications, this is `https://app.asana.com/-/oauth_authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Asana.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Asana.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Asana, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Asana credentials. Amazon Q assumes this role to access your Asana credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Asana plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Asana plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Asana plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Asana**.
1. For **Asana**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Asana domain URL. For example, `https://app.asana.com/api/1.0`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Asana.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Asana.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Asana OAuth applications, this is `https://app.asana.com/-/oauth_token`.
1. For **Authorization URL** – For Asana OAuth applications, this is `https://app.asana.com/-/oauth_authorize` or the authorization URL provided in the OAuth app.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Asana plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type ASANA \
--server-url https://app.asana.com/api/1.0 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring an Atlassian Confluence plugin for Amazon Q Business
Atlassian Confluence is a collaborative work-management tool designed for sharing, storing, and working on project planning, software development, and product management. If you’re a Atlassian Confluence user, you can create an Amazon Q Business plugin to allow your end users to search pages from within their web experience chat.
To create a Atlassian Confluence plugin, you need configuration information from your Atlassian Confluence instance to set up a connection between Amazon Q and Atlassian Confluence and allow Amazon Q to perform actions in Atlassian Confluence.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#confluence-plugin-prereqs)
+ [Service access roles](#confluence-plugin-iam)
+ [Creating a plugin](#confluence-plugin-create)
## Prerequisites
Before you configure your Amazon Q Atlassian Confluence plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Atlassian Confluence app in the Atlassian Confluence developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) in Atlassian Confluence Developer Documentation. Make sure sharing is enabled. Required scopes: `search:confluence`.
+ Note the domain URL of your Atlassian Confluence instance. For example: `https://api.atlassian.com/ex/confluence/yourInstanceId`. To learn how to retrieve your instance ID (Cloud Site ID), go to [How to retrieve Cloud Site Id](https://confluence.atlassian.com/cloudkb/retrieve-my-atlassian-site-s-cloud-id-1272283178.html).
+ Note your:
+ **Access token URL** – For Atlassian Confluence OAuth applications, this is `https://auth.atlassian.com/oauth/token`.
+ **Authorization URL** – For Atlassian Confluence OAuth applications, this is `https://auth.atlassian.com/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Atlassian Confluence.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Atlassian Confluence.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Atlassian Confluence, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Atlassian Confluence credentials. Amazon Q assumes this role to access your Atlassian Confluence credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Atlassian Confluence plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Atlassian Confluence plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Atlassian Confluence plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Atlassian Confluence**.
1. For **Atlassian Confluence**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Atlassian Confluence domain URL. For example, `https://api.atlassian.com/ex/confluence/yourInstanceId`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Atlassian Confluence.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Atlassian Confluence.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Atlassian Confluence OAuth applications, this is `https://auth.atlassian.com/oauth/token`.
1. For **Authorization URL** – For Atlassian Confluence OAuth applications, this is `https://auth.atlassian.com/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Atlassian Confluence plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type ATLASSIAN_CONFLUENCE \
--server-url https://api.atlassian.com/ex/confluence/yourInstanceId \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Google Calendar plugin for Amazon Q Business
Google Calendar is an online calendar service that helps users schedule meetings, set up events, set reminders, and share their schedules. If you’re a Google Calendar user, you can create an Amazon Q Business plugin to allow your end users to find and list events from within their web experience chat.
To create a Google Calendar plugin, you need configuration information from your Google Calendar instance to set up a connection between Amazon Q and Google Calendar and allow Amazon Q to perform actions in Google Calendar.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#gcal-plugin-prereqs)
+ [Service access roles](#gcal-plugin-iam)
+ [Creating a plugin](#gcal-plugin-create)
## Prerequisites
Before you configure your Amazon Q Google Calendar plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Google Calendar app in the Google Calendar developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2) in Google Calendar Developer Documentation.
+ Make sure you've added following required scopes: `calendar.readonly`, `calendar.events`.
+ Note the domain URL of your Google Calendar instance. For example: `https://www.googleapis.com/calendar/v3`.
+ Note your:
+ **Access token URL** – For Google Calendar OAuth applications, this is `https://oauth2.googleapis.com/token`.
+ **Authorization URL** – For Google Calendar OAuth applications, this is `https://accounts.google.com/o/oauth2/v2/auth`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Google Calendar.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Google Calendar.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Google Calendar, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Google Calendar credentials. Amazon Q assumes this role to access your Google Calendar credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Google Calendar plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Google Calendar plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Google Calendar plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Google Calendar**.
1. For **Google Calendar**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Google Calendar domain URL. For example, `https://www.googleapis.com/calendar/v3`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Google Calendar.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Google Calendar.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Google Calendar OAuth applications, this is `https://oauth2.googleapis.com/token`.
1. For **Authorization URL** – For Google Calendar OAuth applications, this is `https://accounts.google.com/o/oauth2/v2/auth`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Google Calendar plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type GOOGLE_CALENDAR \
--server-url https://www.googleapis.com/calendar/v3 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Jira Cloud plugin for Amazon Q Business
Jira Cloud is a project management tool that creates issues (tickets) for software development, product management, and bug tracking. If you’re a Jira Cloud user, you can create an Amazon Q Business plugin to allow your end users to perform the following actions from within their web experience chat:
+ Read issues
+ Create issues
+ Search issues
+ Change issue status
+ Delete issue
+ Read sprint
+ Move issue to sprint
+ Create sprint
+ Delete sprint
To create a Jira Cloud plugin, you need configuration information from your Jira Cloud instance to set up a connection between Amazon Q and Jira Cloud and allow Amazon Q to perform actions in Jira Cloud.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#jira-plugin-prereqs)
+ [Service access roles](#jira-plugin-iam)
+ [Creating a plugin](#jira-plugin-create)
## Prerequisites
Before you configure your Amazon Q Jira Cloud plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Jira Cloud app in the Jira Cloud developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) in Jira Cloud Developer Documentation.
+ Make sure sharing is enabled and the following required scopes are added:
+ `read:jira-work`
+ `write:jira-work`
+ `manage:jira-project`
+ `read:sprint:jira-software`
+ `write:sprint:jira-software`
+ `delete:sprint:jira-software`
+ `read:board-scope:jira-software`
+ `read:project:jira`
+ Note the domain URL of your Jira Cloud instance. For example: `https://api.atlassian.com/ex/jira/yourInstanceId`. To learn how to retrieve your instance ID (Cloud Site ID), go to [ How to retrieve Cloud Site Id](https://confluence.atlassian.com/cloudkb/retrieve-my-atlassian-site-s-cloud-id-1272283178.html) in Jira Software Support.
+ Note your:
+ **Access token URL** – For Jira Cloud OAuth applications, this is `https://auth.atlassian.com/oauth/token`.
+ **Authorization URL** – For Jira Cloud OAuth applications, this is `https://auth.atlassian.com/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Jira Cloud.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Jira Cloud.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Jira Cloud, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Jira Cloud credentials. Amazon Q assumes this role to access your Jira Cloud credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Jira Cloud plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Jira Cloud plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Jira Cloud plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Jira Cloud**.
1. For **Jira Cloud**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Jira Cloud domain URL. For example, `https://api.atlassian.com/ex/jira/yourInstanceId`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Jira Cloud.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Jira Cloud.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Jira Cloud OAuth applications, this is `https://auth.atlassian.com/oauth/token`.
1. For **Authorization URL** – For Jira Cloud OAuth applications, this is `https://auth.atlassian.com/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Jira Cloud plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type JIRA_CLOUD \
--server-url https://api.atlassian.com/ex/jira/yourInstanceId \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Microsoft Exchange plugin for Amazon Q Business
Microsoft Exchange is an enterprise collaboration tool for messaging, meetings, and file sharing. If you’re a Microsoft Exchange user, you can create an Amazon Q Business plugin to allow your end users to get events from their calendars and get emails from within their web experience chat.
To create a Microsoft Exchange plugin, you need configuration information from your Microsoft Exchange instance to set up a connection between Amazon Q and Microsoft Exchange and allow Amazon Q to perform actions in Microsoft Exchange.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#exchange-plugin-prereqs)
+ [Service access roles](#exchange-plugin-iam)
+ [Creating a plugin](#exchange-plugin-create)
## Prerequisites
Before you configure your Amazon Q Microsoft Exchange plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Microsoft Exchange app in the Microsoft Exchange developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate#register-an-application) in Microsoft Exchange Developer Documentation. Select **Accounts** in any organizational directly under **Supported Account Types**.
+ Make sure you've added following required scopes: `mail.read`, `mail.send`, `calendars.readwrite`.
+ Note the domain URL of your Microsoft Exchange instance. For example: `https://graph.microsoft.com/v1.0`.
+ Note your:
+ **Access token URL** – For Microsoft Exchange OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/token`.
+ **Authorization URL** – For Microsoft Exchange OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Microsoft Exchange.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Microsoft Exchange.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Microsoft Exchange, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Microsoft Exchange credentials. Amazon Q assumes this role to access your Microsoft Exchange credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Microsoft Exchange plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Microsoft Exchange plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Microsoft Exchange plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Microsoft Exchange**.
1. For **Microsoft Exchange**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Microsoft Exchange domain URL. For example, `https://graph.microsoft.com/v1.0`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Microsoft Exchange.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Microsoft Exchange.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Microsoft Exchange OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/token`.
1. For **Authorization URL** – For Microsoft Exchange OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Microsoft Exchange plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type MICROSOFT_EXCHANGE \
--server-url https://graph.microsoft.com/v1.0 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Microsoft Teams plugin for Amazon Q Business
Microsoft Teams is an enterprise collaboration tool for messaging, meetings, and file sharing. If you’re a Microsoft Teams user, you can create an Amazon Q Business plugin to allow your end users to send private and public (channel) messages from within their web experience chat.
To create a Microsoft Teams plugin, you need configuration information from your Microsoft Teams instance to set up a connection between Amazon Q and Microsoft Teams and allow Amazon Q to perform actions in Microsoft Teams.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#teams-plugin-prereqs)
+ [Service access roles](#teams-plugin-iam)
+ [Creating a plugin](#teams-plugin-create)
## Prerequisites
Before you configure your Amazon Q Microsoft Teams plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Microsoft Teams app in the Microsoft Teams developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate#register-an-application) in Microsoft Teams Developer Documentation. Select **Accounts** in any organizational directly under **Supported Account Types**.
+ Make sure you've added following required scopes:
+ `channelMessage.send`
+ `chatMessage.send`
+ `Team.ReadBasic.All`
+ `Channel.ReadBasic.All`
+ `Chat.Read`
+ Note the domain URL of your Microsoft Teams instance. For example: `https://graph.microsoft.com/v1.0`.
+ Note your:
+ **Access token URL** – For Microsoft Teams OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/token`.
+ **Authorization URL** – For Microsoft Teams OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Microsoft Teams.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Microsoft Teams.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Microsoft Teams, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Microsoft Teams credentials. Amazon Q assumes this role to access your Microsoft Teams credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Microsoft Teams plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Microsoft Teams plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Microsoft Teams plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Microsoft Teams**.
1. For **Microsoft Teams**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Microsoft Teams domain URL. For example, `https://graph.microsoft.com/v1.0`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Microsoft Teams.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Microsoft Teams.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Microsoft Teams OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/token`.
1. For **Authorization URL** – For Microsoft Teams OAuth applications, this is `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Microsoft Teams plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type MICROSOFT_TEAMS \
--server-url https://graph.microsoft.com/v1.0 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a PagerDuty Advance plugin for Amazon Q Business
PagerDuty Operations Cloud is a software-as-a-service (SaaS) incident response management platform that provides IT teams with knowledge about incidents as soon as they occur. If you’re a PagerDuty Advance customer who has [PagerDuty Advance AI Assistant](https://support.pagerduty.com/main/docs/pagerduty-advance#manage-pagerduty-advance-account-settings) functionality turned on, you can use the Amazon Q Business PagerDuty Advance plugin to allow your end users to perform the following actions from within their web experience chat:
+ Get incidents
+ Similar incidents
+ Root cause incident
+ Find recent changes
+ Who is on-call
+ Status update on incident
+ Customer impact
+ Update incident
To create a PagerDuty Advance plugin, you need configuration information from your PagerDuty Advance instance to set up a connection between Amazon Q and PagerDuty Advance and allow Amazon Q to perform actions in PagerDuty Advance.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#pagerduty-plugin-prereqs)
+ [Service access roles](#pagerduty-plugin-iam)
+ [Creating a plugin](#pagerduty-plugin-create)
## Prerequisites
Before you configure your Amazon Q PagerDuty Advance plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 PagerDuty Advance app in the PagerDuty Advance developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Register an App](https://developer.pagerduty.com/docs/dd91fbd09a1a1-register-an-app) in PagerDuty Advance Developer Documentation.
+ Make sure you've added following required scopes:
+ `openid`
+ `write`
**Note**
We recommend choosing Classic OAuth Scopes.
+ Note the domain URL of your PagerDuty Advance instance. For example: `https://api.pagerduty.com`.
+ Note your:
+ **Access token URL** – For PagerDuty Advance OAuth applications, this is `https://identity.pagerduty.com/oauth/token`.
+ **Authorization URL** – For PagerDuty Advance OAuth applications, this is `https://identity.pagerduty.com/oauth/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in PagerDuty Advance.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in PagerDuty Advance.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to PagerDuty Advance, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your PagerDuty Advance credentials. Amazon Q assumes this role to access your PagerDuty Advance credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a PagerDuty Advance plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a PagerDuty Advance plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a PagerDuty Advance plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **PagerDuty Advance**.
1. For **PagerDuty Advance**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your PagerDuty Advance domain URL. For example, `https://api.pagerduty.com`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in PagerDuty Advance.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in PagerDuty Advance.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For PagerDuty Advance OAuth applications, this is `https://identity.pagerduty.com/oauth/token`.
1. For **Authorization URL** – For PagerDuty Advance OAuth applications, this is `https://identity.pagerduty.com/oauth/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a PagerDuty Advance plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type PAGERDUTY_ADVANCE \
--server-url https://api.pagerduty.com \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Salesforce plugin for Amazon Q Business
Salesforce is a customer relationship management (CRM) tool for managing customer interactions. If you’re a Salesforce user, you can create an Amazon Q Business plugin to allow your end users to perform the following actions from within their web experience chat:
+ Managing cases (create, delete, update, get)
+ Retrieving account lists
+ Handling opportunities (create, update, delete, get, fetch specific)
+ Fetching specific contacts
**Note**
The Salesforce plugin returns a maximum of 5 items per query to manage response size and performance.
To set up this plugin, you'll need configuration details from your Salesforce instance to connect Amazon Q Business with Salesforce.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#salesforce-plugin-prereqs)
+ [Service access roles](#salesforce-plugin-iam)
+ [Creating a plugin](#salesforce-plugin-create)
## Prerequisites
Before you configure your Amazon Q Salesforce plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Salesforce app in the Salesforce developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Create a Connected App in Salesforce for OAuth](https://help.salesforce.com/s/articleView?id=platform.ev_relay_create_connected_app.htm&type=5) in Salesforce Developer Documentation.
+ Make sure to select **Yes** for **Enable Authorization Code and Credential Flow**, **Require Secret for Web Server Flow**, **Require Secret for Refresh Token Flow**, **Enable Token Exchange Flow**, and **Require Secret for Token Exchange Flow**.
+ Make sure that the following required scopes are added:
+ `visualforce`
+ `address`
+ `custom_permissions`
+ `open_id`
+ `profile`
+ `refresh_token`
+ `wave_api`
+ `web`
+ `phome`
+ `offline_access`
+ `chatter_api`
+ `id`
+ `api`
+ `eclair_api`
+ `email`
+ `pardot_api`
+ `full`
+ Note the domain URL of your Salesforce instance. For example: `https://yourInstance.my.salesforce.com/services/data/v60.0`.
+ Note your:
+ **Access token URL** – For Salesforce OAuth applications, this is `https://login.salesforce.com/services/oauth2/token`.
+ **Authorization URL** – For Salesforce OAuth applications, this is `https://login.salesforce.com/services/oauth2/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Salesforce.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Salesforce.
You will need this authentication information during the plugin configuration process.
**Note**
The Require Proof Key for Code Exchange (PKCE) extension option is not supported and it must be disabled in the Salesforce Connector application.
## Service access roles
To successfully connect Amazon Q to Salesforce, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Salesforce credentials. Amazon Q assumes this role to access your Salesforce credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Salesforce plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Salesforce plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Salesforce plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Salesforce**.
1. For **Salesforce**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Salesforce domain URL. For example, `https://yourInstance.my.salesforce.com/services/data/v60.0`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Salesforce.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Salesforce.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Salesforce OAuth applications, this is `https://login.salesforce.com/services/oauth2/token`.
1. For **Authorization URL** – For Salesforce OAuth applications, this is `https://login.salesforce.com/services/oauth2/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Salesforce plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type SALESFORCE_CRM \
--server-url https://yourInstance.my.salesforce.com/services/data/v60.0 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a ServiceNow plugin for Amazon Q Business
ServiceNow provides a cloud-based service management system to create and manage organization-level workflows, such as IT services, ticketing systems, and support. ServiceNow uses incidents (tickets) to track issues. If you’re a ServiceNow user, you can create an Amazon Q Business plugin to allow your end users to perform the following actions from within their web experience chat:
+ Create incident
+ Read incident
+ Update incident
+ Delete incident
+ Read change request
+ Create change request
+ Update change request
+ Delete change request
To create a ServiceNow plugin, you need configuration information from your ServiceNow instance to set up a connection between Amazon Q and ServiceNow and allow Amazon Q to perform actions in ServiceNow.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#servicenow-plugin-prereqs)
+ [Service access roles](#servicenow-plugin-iam)
+ [Creating a plugin](#servicenow-plugin-create)
## Prerequisites
Before you configure your Amazon Q ServiceNow plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 ServiceNow app in the ServiceNow developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Create an endpoint for clients to access the instance](https://docs.servicenow.com/bundle/xanadu-platform-security/page/administer/security/task/t_CreateEndpointforExternalClients.html) in ServiceNow Developer Documentation.
+ Make sure the OAuth plugin is active and the OAuth activation property is set to true. Required scopes:
+ `read`
+ `write`
+ `useraccount`
**Note**
We recommend choosing Classic OAuth Scopes.
+ Make sure to create an authentication profile by following the steps outlined in [ServiceNow Documentation](https://www.servicenow.com/docs/bundle/xanadu-platform-security/page/integrate/authentication/task/create-authentication-profile.html). For **Type**, select **OAuth**. For authentication policy, select **Allow Access Policy**.
Then, add the authentication profile you created to the REST API access policies for **Table API** and **Change Management** by following steps outlined in [Create REST API access policy](https://www.servicenow.com/docs/bundle/xanadu-platform-security/page/integrate/authentication/task/create-api-access-policy.html) in ServiceNow Documentation.
+ Note the domain URL of your ServiceNow instance. For example: `https://yourInstanceId.service-now.com`.
+ Note your:
+ **Access token URL** – For ServiceNow OAuth applications, this is `https://yourInstanceId.service-now.com/oauth_token.do`.
+ **Authorization URL** – For ServiceNow OAuth applications, this is `https://yourInstanceId.service-now.com/oauth_auth.do`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in ServiceNow.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in ServiceNow.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to ServiceNow, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your ServiceNow credentials. Amazon Q assumes this role to access your ServiceNow credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a ServiceNow plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a ServiceNow plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a ServiceNow plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **ServiceNow**.
1. For **ServiceNow**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your ServiceNow domain URL. For example, `https://yourInstanceId.service-now.com`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in ServiceNow.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in ServiceNow.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For ServiceNow OAuth applications, this is `https://yourInstanceId.service-now.com/oauth_token.do`.
1. For **Authorization URL** – For ServiceNow OAuth applications, this is `https://yourInstanceId.service-now.com/oauth_auth.do`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a ServiceNow plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type SERVICENOW_NOW_PLATFORM \
--server-url https://yourInstanceId.service-now.com \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Smartsheet plugin for Amazon Q Business
Smartsheet is an enterprise work management platform that lets users manage projects, programs and processes at scale using sheets, channels, and workspaces. If you’re a Smartsheet user, you can create an Amazon Q Business plugin to allow your end users to search and read sheets, and list and get reports from within their web experience chat.
To create a Smartsheet plugin, you need configuration information from your Smartsheet instance to set up a connection between Amazon Q and Smartsheet and allow Amazon Q to perform actions in Smartsheet.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#smartsheet-plugin-prereqs)
+ [Service access roles](#smartsheet-plugin-iam)
+ [Creating a plugin](#smartsheet-plugin-create)
## Prerequisites
Before you configure your Amazon Q Smartsheet plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Smartsheet app in the Smartsheet developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see the "Register Your App Using Developer Tools" section in [OAuth Walkthrough ](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#register-your-app-using-developer-tools) in the Smartsheet Developer Documentation.
+ Make sure you've added following required scopes:
+ `readsheet`
+ `writesheet`
+ Note the domain URL of your Smartsheet instance. For example: `https://api.smartsheet.com/2.0`.
+ Note your:
+ **Access token URL** – For Smartsheet OAuth applications, this is `https://api.smartsheet.com/2.0/token`.
+ **Authorization URL** – For Smartsheet OAuth applications, this is `https://app.smartsheet.com/b/authorize`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Smartsheet.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Smartsheet.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Smartsheet, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Smartsheet credentials. Amazon Q assumes this role to access your Smartsheet credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Smartsheet plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Smartsheet plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Smartsheet plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Smartsheet**.
1. For **Smartsheet**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Smartsheet domain URL. For example, `https://api.smartsheet.com/2.0`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Smartsheet.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Smartsheet.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Smartsheet OAuth applications, this is `https://api.smartsheet.com/2.0/token`.
1. For **Authorization URL** – For Smartsheet OAuth applications, this is `https://app.smartsheet.com/b/authorize`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Smartsheet plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type SMARTSHEET \
--server-url https://api.smartsheet.com/2.0 \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Zendesk Suite plugin for Amazon Q Business
Zendesk Suite is a customer relationship management system that helps businesses automate and enhance customer support interactions by creating tickets to track work. If you’re a Zendesk Suite user, you can create an Amazon Q Business plugin to allow your end users to create, update, search for, and get ticket details from within their web experience chat.
To create a Zendesk Suite plugin, you need configuration information from your Zendesk Suite instance to set up a connection between Amazon Q and Zendesk Suite and allow Amazon Q to perform actions in Zendesk Suite.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#zendesk-plugin-prereqs)
+ [Service access roles](#zendesk-plugin-iam)
+ [Creating a plugin](#zendesk-plugin-create)
## Prerequisites
Before you configure your Amazon Q Zendesk Suite plugin, you must do the following:
+ As an admin, create a new OAuth 2.0 Zendesk Suite app in the Zendesk Suite developer console with scoped permissions for performing actions in Amazon Q. To learn how to do this, see [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application) in Zendesk Suite Developer Documentation.
+ Make sure the following required scopes are added:
+ `tickets:read`
+ `tickets:write, read`
+ Note the domain URL of your Zendesk Suite instance. For example: `https://yourInstanceId.zendesk.com`.
+ Note your:
+ **Access token URL** – For Zendesk Suite OAuth applications, this is `https://yourInstanceId.zendesk.com/oauth/tokens`.
+ **Authorization URL** – For Zendesk Suite OAuth applications, this is `https://yourInstanceId.zendesk.com/oauth/authorizations/new`.
+ **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
+ **Client ID** – The unique identifier generated when you create your OAuth 2.0 application in Zendesk Suite.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Zendesk Suite.
You will need this authentication information during the plugin configuration process.
## Service access roles
To successfully connect Amazon Q to Zendesk Suite, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Zendesk Suite credentials. Amazon Q assumes this role to access your Zendesk Suite credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Zendesk Suite plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Zendesk Suite plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Zendesk Suite plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Zendesk Suite**.
1. For **Zendesk Suite**, enter the following information:
1. In **Plugin name**, for **Name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. In **Domain URL**, for **URL** – Enter your Zendesk Suite domain URL. For example, `https://yourInstanceId.zendesk.com`.
1. **OAuth 2.0 authentication** – do the following:
1. For **AWS Secrets Manager secret** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
+ **Secret name** – A name for your Secrets Manager secret.
+ **Client ID** – The client ID generated when you create your OAuth 2.0 application in Zendesk Suite.
+ **Client secret** – The client secret generated when you create your OAuth 2.0 application in Zendesk Suite.
+ For **Redirect URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. For **Access token URL** – For Zendesk Suite OAuth applications, this is `https://yourInstanceId.zendesk.com/oauth/tokens`.
1. For **Authorization URL** – For Zendesk Suite OAuth applications, this is `https://yourInstanceId.zendesk.com/oauth/authorizations/new`.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Zendesk Suite plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type ZENDESK_SUITE \
--server-url https://yourInstanceId.zendesk.com \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=,authorizationUrl=,tokenUrl=}"
```
------
# Configuring a Jira plugin for Amazon Q Business
Jira is a project management tool that creates issues (tickets) for software development, product management, and bug tracking. If you’re a Jira user, you can create an Amazon Q Business plugin to allow your end users to create Jira issues from within their web experience chat.
To create a Jira plugin, you need configuration information from your Jira instance to set up a connection between Amazon Q and Jira and allow Amazon Q to perform actions in Jira.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites for creating an Amazon Q Business Jira plugin](#jira-plugin-prereqs)
+ [Service access roles](#jira-plugin-iam)
+ [Creating a plugin](#jira-plugin-create)
## Prerequisites for creating an Amazon Q Business Jira plugin
Before you configure your Amazon Q Jira plugin, you must do the following:
+ Set up a new user in your Jira instance with scoped permissions for performing actions in Amazon Q.
+ (Optional) [Create an API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) for the new user that you created.
+ Note this user’s Jira username and Jira account password (and optionally, their API token). You will need this basic authentication information for creating an AWS Secrets Manager secret during the plugin configuration process.
+ Note the base URL of your Jira Cloud instance hosted by Atlassian. For example: `https://yourcompany.atlassian.net`.
## Service access roles
To successfully connect Amazon Q to Jira, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Jira credentials. Amazon Q assumes this role to access your Jira credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Jira plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure to create a Jira plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Jira plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console at [https://console.aws.amazon.com/amazonq/business/](https://console.aws.amazon.com/amazonq/business/?region=us-east-1).
1. In **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Jira**.
1. For **Jira**, enter the following information:
1. **Name**, **Plugin name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure that your service role has the necessary permissions.
1. **URL** – The base URL of your Jira Cloud instance hosted by Atlassian. For example: `https://yourcompany.atlassian.net`.
1. **Authentication** – Choose to **Create and add a new secret** or **Use an existing one**.
If you choose to create a new secret, a Secrets Manager secret window opens requesting the following information:
1. **Secret name** – A name for your Secrets Manager secret.
1. **Jira username** – The username for your Jira user.
1. **Jira password/API token** – The password/API token for your Jira user.
1. **Tags – *optional*** – Add an optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Jira plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type JIRA \
--server-url https://example.atlassian.net \
--auth-configuration basicAuthConfiguration="{secretArn=,roleArn=}"
```
------
# Configuring a Salesforce plugin for Amazon Q Business
Salesforce is a customer relationship management (CRM) tool for managing support, sales, and marketing teams that you can use to create cases (tickets) to track issues. If you’re a Salesforce user, you can create an Amazon Q Business plugin to allow your end users to create Salesforce cases from within their web experience chat.
To create a Salesforce plugin, you need configuration information from your Salesforce instance to set up a connection between Amazon Q and Salesforce and allow Amazon Q to perform actions in Salesforce.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#salesforce-plugin-prereqs)
+ [Service access roles](#salesforce-plugin-iam)
+ [Creating a plugin](#salesforce-plugin-create)
## Prerequisites
Before you configure your Amazon Q Salesforce plugin, you must do the following:
+ Set up a Connected App using the admin role in your Salesforce instance with Client Credentials Flow enabled.
+ As an admin, configure an execution user with scoped permissions for performing actions in Amazon Q. For instructions, see [Configure a Connected App for the OAuth 2.0 Client Credentials Flow](https://help.salesforce.com/s/articleView?id=sf.connected_app_client_credentials_setup.htm&type=5) in the Salesforce documentation.
+ Note your Salesforce Connected App’s consumer key (`client_id`) and your Salesforce Connected App Consumer secret (`client_secret`). You will need this Oauth 2.0 authentication information for creating an AWS Secrets Manager secret during the plugin configuration process.
+ Note the Salesforce My Domain URL of your Salesforce organization. For example: `https://yourdomain.my.salesforce.com`.
## Service access roles
To successfully connect Amazon Q to Salesforce, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Salesforce credentials. Amazon Q assumes this role to access your Salesforce credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Salesforce plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Salesforce plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Salesforce plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console at [https://console.aws.amazon.com/amazonq/business/](https://console.aws.amazon.com/amazonq/business/?region=us-east-1).
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Salesforce**.
1. For **Salesforce**, enter the following information:
1. **Name**, for **Plugin name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure that your service role has the necessary permissions.
1. **URL** – My Domain URL of your Salesforce organization. For example: `https://yourdomain.my.salesforce.com`
1. **Authentication** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
1. **Secret name** – A name for your Secrets Manager secret.
1. **Connected app consumer key** – The consumer key for your Salesforce connected app.
1. **Connected app consumer secret** – The consumer secret for your Salesforce connected app.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Salesforce plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type SALESFORCE \
--server-url //example.my.salesforce.com \
--auth-configuration oAuth2ClientCredentialConfiguration="{secretArn=,roleArn=}"
```
------
# Configuring a ServiceNow plugin for Amazon Q Business
ServiceNow provides a cloud-based service management system to create and manage organization-level workflows, such as IT services, ticketing systems, and support. ServiceNow uses incidents (tickets) to track issues. If you’re a ServiceNow user, you can create an Amazon Q Business plugin to allow your end users to create ServiceNow cases from within their web experience chat.
To create a ServiceNow plugin, you need configuration information from your ServiceNow instance to set up a connection between Amazon Q and ServiceNow and allow Amazon Q to perform actions in ServiceNow.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#servicenow-plugin-prereqs)
+ [Service access roles](#servicenow-plugin-iam)
+ [Creating a plugin](#servicenow-plugin-create)
## Prerequisites
Before you configure your Amazon Q ServiceNow plugin, you must do the following:
+ As an admin, set up a new user in your ServiceNow instance with scoped permissions for performing actions in Amazon Q.
+ Note your ServiceNow username and ServiceNow password. You will need this basic authentication information for creating an AWS Secrets Manager secret during the plugin configuration process.
+ Note the base URL of your ServiceNow instance. For example: `https://yourinstance.service-now.com`.
## Service access roles
To successfully connect Amazon Q to ServiceNow, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your ServiceNow credentials. Amazon Q assumes this role to access your ServiceNow credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a ServiceNow plugin for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a ServiceNow plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a ServiceNow plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console at [https://console.aws.amazon.com/amazonq/business/](https://console.aws.amazon.com/amazonq/business/?region=us-east-1).
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **ServiceNow**.
1. For **ServiceNow**, enter the following information:
1. **Name**, for **Plugin name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure tha your service role has the necessary permissions.
1. **URL** – The base URL of your ServiceNow instance. For example: `https://yourinstance.service-now.com`
1. **Authentication** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
1. **Secret name** – A name for your Secrets Manager secret.
1. **ServiceNow username** – The username for your ServiceNow user.
1. **ServiceNow password** – The password for your ServiceNow user.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a ServiceNow plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type SERVICE-NOW \
--server-url //example.service-now.com \
--auth-configuration basicAuthConfiguration="{secretArn=,roleArn=}"
```
------
# Configuring a Zendesk plugin for Amazon Q Business
Zendesk is a customer relationship management system that helps businesses automate and enhance customer support interactions by creating tickets to track work. If you’re a Zendesk user, you can create an Amazon Q Business plugin to allow your end users to create Zendesk cases from within their web experience chat.
To create a Zendesk plugin, you need configuration information from your Zendesk instance to set up a connection between Amazon Q and Zendesk and allow Amazon Q to perform actions in Zendesk.
For more information on how to use plugins during your web experience chat, see [Using plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html).
**Topics**
+ [Prerequisites](#zendesk-plugin-prereqs)
+ [Service access roles](#zendesk-plugin-iam)
+ [Creating a plugin](#zendesk-plugin-create)
## Prerequisites
Before you configure your Amazon Q Zendesk plugin, you must do the following:
+ As an admin, set up a new user in your Zendesk instance with scoped permissions for performing actions in Amazon Q.
+ (Optional) [Create an API token](https://support.zendesk.com/hc/en-us/articles/4408831452954-How-can-I-authenticate-API-requests-) for that new user.
+ Note your Zendesk username and Zendesk password/API token. You will need this basic authentication information for creating an AWS Secrets Manager secret during the plugin configuration process.
+ Note the base URL of your Zendesk instance. For example: `https://yoursubdomain.zendesk.com`.
## Service access roles
To successfully connect Amazon Q to Zendesk, you need to give Amazon Q the following permission to access your Secrets Manager secret to get your Zendesk credentials. Amazon Q assumes this role to access your Zendesk credentials.
The following is the service access IAM role required:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:[[secret-id]]"
]
}
]
}
```
To allow Amazon Q to assume a role, use the following trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn":"arn:aws:qbusiness:{{your-region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
If you use the console and choose to create a new IAM role, Amazon Q creates the role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your IAM role contains these permissions.
## Creating a plugin
To create a Zendesk plugin for your web experience chat, you can use AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) API operation. The following tabs provide a procedure for creating a Zendesk plugin using the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a Zendesk plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console at [https://console.aws.amazon.com/amazonq/business/](https://console.aws.amazon.com/amazonq/business/?region=us-east-1).
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, choose **Add plugin**.
1. For **Add plugins**, choose **Zendesk**.
1. For **Zendesk**, enter the following information:
1. **Name**, **Plugin name** – A name for your Amazon Q plugin. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters.
1. For **Service access** – Choose **Create and add a new service role** or **Use an existing service role**. Make sure that your service role has the necessary permissions.
1. **URL** – The base URL of your Zendesk instance. For example: `https://yoursubdomain.zendesk.com`
1. **Authentication** – Choose **Create and add a new secret** or **Use an existing one**. Your secret must contain the following information:
1. **Secret name** – A name for your Secrets Manager secret.
1. **Zendesk username** – The username for your Zendesk user.
1. **Zendesk password/API token** – The password/API token for your Zendesk user.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a Zendesk plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type ZENDESK \
--server-url //example.zendesk.com \
--auth-configuration basicAuthConfiguration="{secretArn=,roleArn=}"
```
------
# Using Amazon Q Business built-in plugins
After plugins have been configured, you can use them to perform supported actions in your Amazon Q Business web experience chat. This topic provides an overview of how to use plugins.
**Important**
Once configured, all authorized Amazon Q web experience end users can use plugins to perform supported actions. If a plugin is activated for an application, end users will see an option to **Use a plugin**. If a plugin is deactivated, users won't see an option to use a plugin. If your [Admin controls and guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html) settings allow Amazon Q to automatically orchestrate chat queries across plugins and data sources, your plugin actions can be automatically selected by Amazon Q during chat. End user access to plugins can't be customized.
**Topics**
+ [Performing a plugin action](#end-user-plugin-flow)
+ [Example plugin action prompts](#plugin-prompts)
## Performing a plugin action
**Note**
If your [Admin controls and guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html) settings allow Amazon Q to automatically orchestrate end user chat queries across plugins and data sources, plugin actions will be automatically activated by Amazon Q for your end user during chat. In that case, your end user won't have to follow the steps below.
The following describes how to perform a plugin action from within a web experience chat using both the console and the API.
------
#### [ Console ]
**Performing a plugin action**
1. Navigate to the deployed web experience URL and sign with your credentials on the login screen.
1. From conversation settings, choose **Use a plugin**.
1. You can choose to enact plugin actions in two ways:
1. Ask to perform an action directly. For example: Create a Jira ticket for a broken mouse. See [Quick create](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html#quick-create) for more details.
1. Start chatting in your web experience to find answers to your questions. Then choose to include the conversation context in any plugin action that you take. For example: Summarize this conversation and create a Jira ticket. For more information, see [Contextual create](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-plugins.html#contextual-create).
1. In response to your prompt for an action, Amazon Q displays a review form where you fill in the necessary information required to successfully complete an action.
1. To successfully complete the action, you need to submit it. Your web experience will display a success message if the action succeeds, or an error message if the action fails.
------
#### [ API ]
**Performing a plugin action**
```
aws qbusiness chat-sync --application-id '${application-id}' \
--user-message "Create an issue in Jira for broken button in web application" \
--clientToken '${user-oauth-token} ' \
--chat-mode PLUGIN_MODE \
--chat-mode-configuration '{
"pluginConfiguration": {
"pluginId":"${plugin-id}"
}
}'
```
------
## Example plugin action prompts
There are two ways you can choose to use plugins in your web experience chat, *quick creation* and *contextual creation*.
**Topics**
+ [Quick create](#quick-create)
+ [Contextual create](#context-create)
### Quick create
Using quick creation you can directly instruct your web experience to perform a plugin action. For example:
+ `Create a Zendesk ticket for a broken mouse`
+ `Log an incident in ServiceNow for network outage`
+ `Cut an issue in Jira for a broken link on a web page`
+ `Create a Salesforce case for a missing invoice`
### Contextual create
Using contextual creation you can include conversation contexts to create tickets. For example, consider the following example conversation flows:
**Topics**
+ [Example 1: Create a ServiceNow incident](#context-create-servicenow)
+ [Example 2: Create a ZenDesk ticket](#context-create-zendesk)
+ [Example 3: Create a Salesforce case](#context-create-salesforce)
+ [Example 4: Create a Jira issue](#context-create-jira)
#### Example 1: Create a ServiceNow incident
+ **User prompt 1** – `How to resolve network issues`
+ **Amazon Q response** – *Sample response*
+ **User prompt 2** – `How to reset my router`
+ **Amazon Q response** – *Sample response*
+ **User action request** – `Summarize this conversation and create a ServiceNow incident`
#### Example 2: Create a ZenDesk ticket
+ **User prompt 1** – `Compare Amazon Kendra with OpenSearch`
+ **Amazon Q response** – *Sample response*
+ **User action request** – `Create a Zendesk ticket to migrate to Amazon Kendra`
#### Example 3: Create a Salesforce case
+ **User prompt 1** – `Where is the IT office located`
+ **Amazon Q response** – *Sample response*
+ **User prompt 2** – `What floor is the office located in`
+ **Amazon Q response** – *Sample response*
+ **User action request** – `Create a case in Salesforce summarizing this conversation`
#### Example 4: Create a Jira issue
+ **User prompt 1** – `How do I enable auto-scaling in EC2`
+ **Amazon Q response** – *Sample response*
+ **User prompt 2** – `How do I create an auto-scaling group`
+ **Amazon Q response** – *Sample response*
+ **User action request** – `Summarize this conversation and create an issue in Jira`
# Custom plugins for Amazon Q Business
You can use the Amazon Q Business console or APIs to create custom plugins for your Amazon Q application.
With custom plugins, you can choose to integrate Amazon Q with any third-party application for a variety of different use cases. Once enabled, end users can use natural language to query data (like available calendar slots, stock prices, vacation balance), and take actions (like booking a meeting, submitting vacation time, updating a record).
To create a custom plugin, you need to perform the following steps:
+ Configure authentication and network information to connect Amazon Q Business to your third-party application.
+ Create or edit an OpenAPI schema outlining the different API operations you want to enable for your custom plugin in JSON or YAML format.
You can upload the OpenAPI schema file to Amazon S3 or you can paste it in the OpenAPI text editor in the Amazon Q Business console, which will validate your schema. You can configure up to 20 API operations per custom plugin.
Once your custom plugin is deployed, Amazon Q Business will dynamically determine the appropriate APIs to call to accomplish an end user requested task. In order to maximize plugin accuracy, review the [best practices for configuring OpenAPI schema definitions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins-api-schema-best-practices.html) for custom plugins.
**Note**
Creating custom forms with array fields (fields with nested objects inside an array) for custom plugins isn't supported on the console.
**Topics**
+ [Prerequisites for Amazon Q Business custom plugins](custom-plugin-prereqs.md)
+ [Service access roles for Amazon Q Business custom plugins](create-plugin-iam-role.md)
+ [Defining OpenAPI schemas for custom plugins](plugins-api-schema.md)
+ [Best practices for OpenAPI schema definition for custom plugins](plugins-api-schema-best-practices.md)
+ [Creating an Amazon Q Business custom plugin](custom-plugin-create.md)
+ [Using an Amazon Q Business custom plugin](using-custom-plugin.md)
# Prerequisites for Amazon Q Business custom plugins
**Before you configure your Amazon Q custom plugin, you must ensure you have the following:**
+ A defined OpenAPI schema in JSON or YAML (maximum size is 1 MB). In order to maximize accuracy with Amazon Q Business custom plugin, follow the [best practices for configuring OpenAPI schema definitions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins-api-schema-best-practices.html) for custom plugins.
+ If authentication is required to connect Amazon Q to your third-party application, create OAuth authentication credentials. You need to store these authentication credentials in a Secrets Manager secret to connect your third-party application to Amazon Q.
# Service access roles for Amazon Q Business custom plugins
To connect Amazon Q Business to third party applications that require authentication, you need to give the Amazon Q role permissions to access your Secrets Manager secret. This will enable an Amazon Q Business custom plugin to access the credentials needed to log in to the third party service.
+ Permission to access your Secrets Manager secret to get the credentials you use to log in to the third party service instance you are creating a plugin for.
You don't have to provide this role for custom plugins that don't require authentication.
**Important**
If you're changing response settings for an Amazon Q application created and deployed before 16 April, 2024, you need to update your web experience service role. For information on service role permissions needed, see [IAM role for an Amazon Q web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#deploy-experience-iam-role). For information on how to update your web experience service role, see [Updating a web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#update-web-experience).
The following is the service access IAM role required:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowQBusinessToGetSecretValue",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:111122223333:secret:[[secret_id]]"
]
}
]
}
```
------
**To allow Amazon Q to assume a role, use the following trust policy:**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "QBusinessApplicationTrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
}
}
}
]
}
```
------
Amazon Q assumes this role to access your third party service instance credentials.
If you use the console and choose to create a new IAM role, Amazon Q creates the IAM role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your secret contains the permissions above. For more information on creating IAM roles, see [Creating IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
# Defining OpenAPI schemas for custom plugins
Amazon Q Business uses the configured third-party OpenAPI specifications to dynamically determine which API operations to perform in order to fulfill an end user requests. To configure a custom plugin you must define at least 1 API operation and a maximum of 20 API operations that can be invoked. To define the API operations, create an OpenAPI schema in JSON or YAML format. You can create OpenAPI schema files and upload them to Amazon Simple Storage Service (Amazon S3). Alternatively, you can use the OpenAPI text editor in the console, which will validate your schema.
This section will first cover the required definitions for the OpenAPI schema. The next section will cover [best practices and examples for configuring OpenAPI schema definitions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins-api-schema-best-practices.html) to maximize the accuracy of your Amazon Q Business custom plugins. For more details about OpenAPI schemas, see [OpenAPI specification](https://swagger.io/specification/) on the Swagger website.
**Topics**
+ [OpenAPI Schema definitions for custom plugins](#plugins-api-schema-definition)
## OpenAPI Schema definitions for custom plugins
The following is the general format of an OpenAPI schema for a custom plugin.
```
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.example.com"
}
],
"paths": {
"/path": {
"method": {
"description": "string",
"operationId": "string",
"parameters": [ ... ],
"requestBody": { ... },
"responses": { ... },
"security": [ ... ]
}
}
},
"security": [
{
"OAuth2": ["read", "write"]
}
],
"components": {
"securitySchemes": {}
}
}
```
The following list describes fields in the OpenAPI schema
+ `openapi` – (Required) The version of OpenAPI that's being used. This value must be `"3.0.0"` or higher for custom plugins.
+ `servers` – (Required) The identifier for application connectivity from API clients. This is required for the custom plugin call to succeed.
+ `paths` – (Required) Contains relative paths to individual endpoints. Each path must begin with a forward slash (`/`). Amazon Q Business supports only one configured endpoint per custom plugin.
+ `method` – (Required) Defines the method to use.
+ `securitySchemes` – (Optional) Defines the OAuth security parameters.
+ `security` – (Required when using authentication) Defines which security schemes are applied to the whole API or specific operations. This is required when using OAuth authentication.
Minimally, each method requires the following fields:
+ `description` – A description of the API operation. Use this field to let the custom plugin know when to call this API operation and what the operation does.
+ `responses` – Contains properties that the custom plugin returns in the API response. The custom plugin uses the response properties to construct prompts, accurately process the results of an API call, and determine a correct set of steps for performing an action.
The fields within the following two objects provide more information for your custom plugin to effectively select API operations that are needed to fulfill an end user request. For each field, set the value of the `required` field to `true` if required and to `false` if optional.
+ `parameters` – Contains information about parameters that can be included in the request.
+ `requestBody` – Contains the fields in the request body for the operation. Don't include this field for `GET` and `DELETE` methods.
For details on configuring the fields review the following sections:
**Topics**
+ [OpenAPI Schema responses](#plugins-api-schema-responses)
+ [OpenAPI Schema parameters](#plugins-api-schema-parameters)
+ [OpenAPI Schema request body](#plugins-api-schema-request-body)
+ [OpenAPI Schema security schemes](#plugins-api-schema-security-scheme)
### OpenAPI Schema responses
The following is a sample response.
```
"responses": {
"200": {
"content": {
"": {
"schema": {
"properties": {
"": {
"type": "string",
"description": "string"
},
...
}
}
}
},
},
...
}
```
Each key in the `responses` object is a response code, which describes the status of the response. The response code maps to an object that contains the following information for the response:
+ `content` – (Required for each response) The content of the response.
+ ** – The format of the response body. At this time, only `application/json` is supported by custom plugins. For more information, see [Media types](https://swagger.io/docs/specification/media-types/) on the Swagger website.
+ `schema` – (Required for each media type) Defines the data type of the response body and its fields.
+ `properties` – (Required if there are `items` in the schema) Your custom plugins uses properties that you define in the schema to determine the information it needs to return to the end user in order to fulfill a task. Each property contains the following fields:
+ `type` – (Required for each property) The data type of the response field.
+ `description` – (Optional) Describes the property. The custom plugin can use this information to determine the information that it needs to return to the end user.
### OpenAPI Schema parameters
The following are examples of parameters.
```
"parameters": [
{
"name": "string", // e.g. "userName"
"description": "string",
"required": boolean,
"x-amzn-form-display-name": "string" // e.g. "User Name"
"schema": {
...
}
},
{
"name": "string", // e.g. "employeeId"
"description": "string",
"required": boolean,
"x-amzn-form-hide": boolean //e.g. true
"schema": {
...
}
}
...
]
```
Your custom plugin uses the following fields to determine the information it must get from the end user to perform the plugin's requirements.
+ `name` – (Required) The name of the parameter.
+ `description` – (Required) A description of the parameter. Use this field to help the plugin to understand how to elicit this parameter from the user or determine that it already has that parameter value from prior actions or from the user’s request to the custom plugin.
+ `required` – (Optional) Whether the parameter is required for the API request. Use this field to indicate to the custom plugin whether this parameter is needed for every invocation or if it's optional.
+ `schema` – (Optional) The definition of input and output data types. For more information, see [Data Models (Schemas)](https://swagger.io/docs/specification/data-models/) on the Swagger website.
+ Extension support – (Optional) For a write API operation, an Amazon Q Business custom plugin may dynamically create a confirmation form that is presented to end users. This form allows users to confirm and/or correct parameters Amazon Q populated based on the end user’s request or past actions. The following extensions can be used to modify how that form is created:
+ `x-amzn-form-display-name` – (Optional) This can be used at parameter level to override the default name visible in the form.
+ `x-amzn-form-hide` – (Optional) This can be used to hide a parameter from being displayed in the user facing form.
+ Schemas containing composition keywords (`allOf`, `not`, `oneOf`, or `anyOf`) are not supported.
+ Schemas containing array types are not supported. For example, schemas such as `{"type": "array", "items": {"string"}}` are not supported.
### OpenAPI Schema request body
The following is the general structure of a `requestBody` field:
```
"requestBody": {
"required": boolean,
"content": {
"": {
"schema": {
"properties": {
"": {
"type": "string",
"description": "string"
},
...
}
}
}
}
}
```
The following list describes each field:
+ `required` – (Optional) Whether the request body is required for the API request.
+ `content` – (Required) The content of the request body.
+ ** – (Optional) The format of the request body. At this time, only `application/json` is supported by custom plugins. For more information, see [Media types](https://swagger.io/docs/specification/media-types/) on the Swagger website.
+ `schema` – (Optional) Defines the data type of the request body and its fields.
+ `properties` – (Optional) Your custom plugin uses properties that you define in the schema to determine the information it must get from the end user to make the API request. Each property contains the following fields:
+ `type` – (Optional) The data type of the request field.
+ `description` – (Optional) Describes the property. The custom plugin can use this information to determine the information it needs to return to the end user.
+ Schemas containing composition keywords (`allOf`, `not`, `oneOf`, or `anyOf`) are not supported.
+ Schemas containing array types are not supported. For example, schemas such as `{"type": "array", "items": {"string"}}` are not supported.
### OpenAPI Schema security schemes
Following is the general structure of a `securityScheme` field:
```
"securitySchemes": {
"OAuth2": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://example.com/oauth/authorize",
"tokenUrl": "https://example.com/oauth/token",
"scopes": {
"read": "Read access to resources",
"write": "Write access to resources"
}
}
}
}
}
```
If your API requires OAuth authorization, the OpenAPI schema needs to include security schemes. We support the following authorization code flow of OAuth:
+ `type` – Must be `oauth2`.
+ `flows` – Must contain `authorizationCode`.
+ `authorizationUrl` – The URL to which the user will be sent to begin the authorization process.
+ `tokenUrl` – (Optional) The URL that the custom plugin will use to exchange the authorization code for an access token.
+ `scopes` – Defines the permissions that the custom plugin will request.
Successful authorization using OAuth also requires an OAuth client ID, client secret, and a redirect url. These will need to be provided as secrets when creating the custom plugin.
# Best practices for OpenAPI schema definition for custom plugins
While application programming interfaces (APIs) have traditionally been used by developers to integrate with external applications, today APIs are increasingly being used by generative AI-powered assistants, such as Amazon Q Business custom plugins. However, its important to note that APIs being used with AI assistants may require design optimizations that were not critical for traditional application integrations. Following the best practices below will help Amazon Q Business to maximize the accuracy and improve efficiency when resolving end user requests.
**Topics**
+ [Optimizing OpenAPI schema accuracy](#plugins-api-schema-accuracy)
+ [Best practices for OpenAPI Schema names](#plugins-api-schema-names)
+ [Best practices for OpenAPI Schema descriptions](#plugins-api-schema-descriptions)
+ [Best practices for JSON input schemas](#plugins-api-schema-json-input)
+ [Other important considerations for OpenAPI specifications](#plugins-api-schema-misc)
+ [Example of API Schema optimization](#plugins-api-schema-optimization)
## Optimizing OpenAPI schema accuracy
To create a custom plugin, you need to create or edit an OpenAPI schema outlining the different API actions you want to enable for your custom plugin. Once the custom plugin is deployed, Amazon Q Business will process an end user prompt and use the OpenAPI schema to dynamically determine the appropriate APIs to call to accomplish the user’s goal. Therefore, the OpenAPI schema definition has a big impact on API selection accuracy.
The following are the OpenAPI schema sections you need to optimize to maximize the accuracy of your Amazon Q Business plugins:
+ **Names** – Names for operation IDs, parameters, object schema property keys, title in info section, and more.
+ **Descriptions** – Descriptions for operations, parameters, schemas, and more.
+ **JSON schemas** – JSON schemas for API inputs (schemas defined in parameters and request body). Within these schemas, important information includes the data type of each schema and format information (for example, date/date-time for ISO-8601 date strings), as well as names and descriptions mentioned above.
In the next sections, we outline how you can maximize the accuracy of your custom plugin by following best practices for your OpenAPI schema parameters.
## Best practices for OpenAPI Schema names
+ Names and IDs should be human-readable, descriptive, and unambiguous while being as concise as possible.
+ Operation IDs provide important signals for understanding the function of each operation. Though not required, it is recommended to add `operationIds` to your API schema. The following outlines some Operation ID naming best practices:
+ Avoid noun-only `operationIds`, like `contacts`. Instead, prefix operation names with descriptive verbs like `get`, `find`, `search`, `create`, `update`, and `delete`. For example, `getContacts`.
+ Ensure `operationIds` meaningfully relate to the function of the operation. Avoid including `operationIds` with meaningless suffixes/prefixes, like `search_1` and `search_2`. If multiple operations perform similar functions, but differ only by inputs, consider creating IDs like `searchByName` or `searchByEmail`, or even merging these operations.
+ Avoid adding long, redundant prefixes to names. For example, avoid `contactsPlugin.getContacts` and `contactsPlugin.createContact`. Instead, use `getContacts` and `createContact`.
+ Names of input request body properties and parameters are important for determining the role and purpose of each input needed for invoking an operation. The following outlines some input request naming best practices:
+ Avoid non-descriptive parameter names like `id`. Instead include a descriptive noun, like `contactId`.
+ It’s not necessary to include information that is redundant with the JSON data type of the input. For example, avoid using `recipientEmailsArray` and instead just use `recipientEmails`.
+ Be consistent with parameter names. Generally, parameters and response properties with the same name should mean the same thing across all operations in your schema. The following outlines some parameter naming best practices:
+ Avoid using different names for parameters with the same meaning. For example, `start_date` in one API and `begin_date` in another API if they mean the same thing.
+ Ensure parameter names and property names in responses are consistent with each other. For example, if an API returns `begin_date`, then also use the name `begin_date` in the input parameters if they have the same meaning.
## Best practices for OpenAPI Schema descriptions
+ Descriptions should be self-contained, providing sufficient guidance for how and when to use the operation or parameter they describe. The following outlines some description creation best practices:
+ Operation descriptions should describe what the operation does, including when, when not, and how to use it.
+ Avoid verbose descriptions. Parameter descriptions should concisely describe their purpose and how they impact the behavior of the operation. For example, rather than write “this field accepts an ISO-8601 date, which is of the format YYYY-MM-DD”, assign date to the format field.
+ Concise explanations are generally more useful than examples.
+ Make dependencies between operations explicit in the description. If an operation always requires another operation to be called first (such as, populating an input parameter from the other operation’s outputs), make this clear in the description of the operation or parameter.
+ Use descriptions only where there is ambiguity or missing context. Avoid adding descriptions that provide no additional information. Restrict the description to information needed to use the API for the use cases Amazon Q Business custom plugin is intended to handle.
+ Descriptions should not reference external links/URLs. Amazon Q Business custom plugins may not be able to access these.
+ Avoid referencing operations by their *path* or *verb*. Instead use their operation ID when referring to other operations in descriptions.
+ Avoid referencing schema components or API paths (except dependency `operationIds`) in the description. Ensure that descriptions are self-contained. As an exception to this, descriptions may reference dependency operations by their `operationIds` but should avoid providing specific usage examples of the operation. The following outlines some referencing best practices:
+ Don’t refer to operations by their API paths (e.g. `/api/v1/timeoff/requests`). Instead, use `operationIds` to refer to operations in descriptions. For example, `GetTimeOffRequests`.
+ Don’t refer to schema components like `#/components/schemas/TimeOffRequest`.
+ If examples are necessary, describe them in abstract terms. “For example, use `{operationId}` to do `{X}`” or “Use `{operationId}` when the end user asks for...”.
+ Internally, Amazon Q Business may use generate API calls differently than described in the OpenAPI schema. So, including usage examples may not always be helpful.
## Best practices for JSON input schemas
+ Simpler interfaces will lead to more efficient, consistent, and accurate plugin usage from Amazon Q Business. Thus, having fewer input parameters of lower complexity is best.
+ Keep the total number of parameter schemas per operation low. Keeping the total number of parameter schemas to 10 at most, but less than 4 on average, will give the best results. Having more parameters may result in slower responses because Amazon Q Business custom plugins will need to fill out each field.
+ Avoid including unnecessary optional input parameters. For example, for search APIs with many parameters for filtering results, use the most informative/important filters. Or, split into multiple operations to search by alternate criteria.
+ Avoid structurally complex/nested inputs when possible. The following outlines some input parameter structure best practices:
+ **Instead of** `{"start": {"type": "object", "properties": {"date": {...}, "time": {...}}, "end": {...}}` **input** `{"start_date": {...}, "start_time": {...}, ..., "end_time": {...}}`.
+ Avoid schemas containing array types, which are not supported. For example, schemas such as `{"type": "array", "items": {"string"}}` are not supported..
+ Avoid circular references (`$ref` inside of `$ref`). Circular references can occur in nested structures when the same reference (`$ref`) appears inside of its de-referenced value. Although these are valid OpenAPI specifications, Amazon Q Business custom plugin may not reliably resolve these recursive definitions.
+ Avoid composition keywords (`allOf`, `not`, `oneOf`, or `anyOf` ), which are not supported
+ Use standard values in the format field for string parameters. For example, `date-time` or `date` for capturing ISO-8601 dates/times.
## Other important considerations for OpenAPI specifications
+ Never expose sensitive information in the API schema or API outputs. If information should not be exposed to the end user, do not include it in your API specification or use an API that produces such outputs.
+ If it is undesirable for an Amazon Q Business custom plugin to reference certain information in the API schemas to the end user, you can use instructions in the operation descriptions to help discourage this. However, you should not rely on this mechanism for highly sensitive information.
+ Only include essential information in API responses. Redundant or excessively verbose information will reduce the efficiency of an Amazon Q Business custom plugin.
+ Limit paginated search results explicitly, particularly if each result returned is large/complex. Large API responses may result in slower responses for end users. Consider setting guidance or limits in the description of the parameter (for example, set to five at most).
+ Only 2XX responses may be shared with Amazon Q Business custom plugin end users. 4xx and 5xx responses will not be shared with end users. If you want to expose specific errors from the API, consider using a 2XX code for such errors. Ensure you include information that is appropriate to share with the end user.
+ The OpenAPI specification should be self-contained. Ensure that the set of API operations described in the schema support complete use cases without relying on APIs not defined or other plugins.
## Example of API Schema optimization
This section shows you an example of an API schema before and after our best practices are applied. The example API is used for managing Paid Time Off (PTO) requests for employees and supports two operations: checking the status of requests (with `api.V1.TimeOffRequest`) and making new requests (with `api.V1.RequestTimeOff`).
The following is the example unoptimized API Schema:
```
openapi: 3.0.3
info:
# title is too long
title: API for PTO Request Management
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/api/v1/timeoff/requests:
get:
# operation ID is ambiguous (is it to get a time off request or make one?) and contains unnecessary details ("api.V1")
operationId: example.api.V1.TimeOffRequest
# description is not self-contained (references an external link) and does not describe what the API returns or how to use it.
description: Existing requests for the authenticated user. See the docs here for more details.
parameters:
- name: type
in: path
# description does not include what a "type" is
description: type to filter by
required: false
schema:
type: string
- name: status
in: path
# description does not include what a "status" is
description: status to filter by
required: false
schema:
type: string
- name: start
in: path
# description is ambiguous
description: start of range to include
required: false
schema:
type: string
# no formatting information is provided, e.g. `format: date`
- name: end
in: path
# description is ambiguous
description: end of range to include
required: false
schema:
type: string
# no formatting information is provided, e.g. `format: date`
- name: limit
in: path
# guidance should be provided on how many results to return by default, e.g. less than 5
description: limit on the number of requests to return
required: false
schema:
type: integer
- name: page
in: path
description: specific page of results to return if results are paginated
required: false
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TimeOffRequests"
/api/v1/timeoff/request:
post:
# operation ID is ambiguous (is it to get a time off request or make one?) and contains unnecessary details ("api.V1")
operationId: example.api.V1.RequestTimeOff
# description is not self-contained (references an external link) and ambiguous.
description: Make a request for the authenticated user. API docs for more details.-->
requestBody:
content:
application/json:
schema:
type: object
properties:
# this field adds unnecessary nesting to the inputs. Separate `start_date`, and `end_date` fields would be preferred
range:
# missing a description, non-descriptive field name
type: object
properties:
start:
# start of what?
type: string
format: date
end:
# end of what?
type: string
format: dat
required:
- start
- end
type:
description: the type of request to make, e.g. `Personal` or `Vacation`
type: string
# use enums where possible
note:
description: a short note describing the reason for the request
type: string
responses:
"201":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TimeOffRequest"
components:
schemas:
TimeOffRequest:
type: object
properties:
# this ID is not necessary for the end user (and is used nowhere else in the API), consider removing
id:
type: string
status:
# no descriptions provided
type: string
type:
type: string
start:
type: string
end:
type: string
note:
type: string
duration:
type: integer
# this ID is not necessary for the end user (and is used nowhere else in the API), consider removing
approver_id:
type: string
approver_display_name:
type: string
TimeOffRequests:
type: array
items:
$ref: "#/components/schemas/TimeOffRequest"
```
Applying the best practices defined above, there are multiple updates that should be made to this API schema to get the best results when using Amazon Q Business custom plugins.
First, based on guidance to make names concise, descriptive and unambiguous, we’ll make a few updates to the operation IDs, parameter names, and schema title:
+ Change `example.api.V1.RequestTimeOff` to `CreateTimeOffRequest`
+ Change `example.api.V1.RequestTimeOff` to `GetTimeOffRequests`
+ Change the schema title in the info section from `API for PTO Request Management` to `TimeOff`
If you are able to change the API itself, we’d also like you to fix parameter names. Change parameters named `type` and `status` to `request_type` and `request_status` respectively
Next, based on best practices for descriptions, we’ll make the following updates:
+ Modify the description of `/api/v1/timeoff/requests` and `/api/v1/timeoff/request` to make them self-contained (remove URL) and describe what they do and how to use them. For example:
+ Change `Existing requests for the authenticated user. See the docs here for more details.` to `Return existing time off requests (including information like the current approval status, dates/days used) for the authenticated user.`
+ Change `Make a request for the authenticated user. See API docs for more details.` to `Create a new time off request of a particular type (e.g. Personal or Vacation) for the authenticated user based on a start and end date (inclusive)`.
+ Add descriptions for ambiguous parameters. For example:
+ For the end date of a request, add a description: `Last day for the request (inclusive) in ISO-8601 format (for example, YYYY-MM-DD)`.
+ For the start date, add a description: `First day of the request in ISO-8601 format (e.g. YYYY-MM-DD)`.
+ Based on guidance to limit paginated search results explicitly, we’ll add a description to the `limit` field in `GetTimeOffRequests`. For example, `Limit on the number of requests to return. Limit to 5 unless otherwise instructed`.
Finally, we’ll apply changes based on the API input schema best practices:
+ Assuming we have control over the API implementation, we’d like to apply guidance on avoiding unnecessary nesting. For this, we can convert `range` (which contains start and end dates) to two top-level properties called `startDate` and `endDate`.
+ Following guidance to use standard format fields, we’ll add format: `date` to start/end date fields (assuming we are expecting standard date formats).
After making corrections, we end up with a vastly improved API specification that will maximize the Amazon Q Business custom plugin accuracy and efficiency in resolving user requests.
The following is the API Schema after we've added optimization fixes:
```
openapi: 3.0.3
info:
title: TimeOff
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/api/v1/timeoff/requests:
get:
operationId: GetTimeOffRequests
description: Return existing time off requests (including information like the current approval status, dates/days used) for the authenticated user
parameters:
- name: request_type
in: path
required: false
schema:
type: string
enum:
- Vacation
- Personal
- JuryDuty
- Sick
- name: request_status
in: path
required: false
schema:
type: string
enum:
- Approved
- Pending
- Cancelled
- name: start
in: path
description: Include requests ending on or after this date
required: false
schema:
type: string
format: date
- name: end
in: path
description: Include requests starting before this date
required: false
schema:
type: string
format: date
- name: limit
in: path
description: Limit on the number of requests to return. Limit to 5 unless otherwise instructed
schema:
type: integer
- name: page
in: path
description: Specific page of results to return if results are paginated
required: false
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TimeOffRequests"
/api/v1/timeoff/request:
post:
operationId: CreateTimeOffRequest
description: Create a new time off request for the authenticated user
requestBody:
content:
application/json:
schema:
type: object
properties:
startDate:
description: First day of the request in ISO-8601 format (e.g. YYYY-MM-DD)
type: string
format: date
endDate:
description: Last day for the request (inclusive) in ISO-8601 format (e.g. YYYY-MM-DD)
type: string
format: date
request_type:
description: The type of request to make, either `Personal`, `Vacation`, `Sick` or `JuryDuty`
type: string
enum:
- Personal
- Vacation
- Sick
- JuryDuty
note:
description: A short (one to two sentence) note describing the reason for the request
type: string
required:
- startDate
- endDate
- request_type
- note
responses:
"201":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TimeOffRequest"
components:
schemas:
TimeOffRequest:
type: object
properties:
# this ID is not necessary for the end user (and is used nowhere else in the API), consider removing
request_id:
type: string
request_status:
description: the current status of the request, either `Pending`, `Approved`, or `Cancelled`
type: string
enum:
- Pending
- Approved
- Cancelled
request_type:
type: string
start:
description: the start date of the request
type: string
end:
description: the last date of the request (inclusive)
type: string
note:
description: brief note describing the reason for the request
type: string
duration:
description: the number of working days used for the request
type: integer
approver_display_name:
description: the name of the person of who approved the request
type: string
TimeOffRequests:
type: array
items:
$ref: "#/components/schemas/TimeOffRequest"
```
# Creating an Amazon Q Business custom plugin
**Note**
To validate accuracy before deploying to end users, we recommend creating a Amazon Q Business test application to configure and test new features. To create a new custom plugin, first ensure that you have a test application with the same settings and configurations as your production application (the one deployed for your end users). Using the console, configure a custom plugin in the test application following the steps below. After you finish configuring your custom plugin, launch a test web experience and login as an end user. Issue a number of expected user prompts and confirm you are getting the expected results. If you are not getting the expected results, return to the console page and modify the OpenAPI specification to ensure it follows [best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins-api-schema-best-practices.html) for configuring OpenAPI specifications. Repeat this process until you are satisfied with the test application results and then replicate the same custom plugins settings in your production application before you share it with your end users.
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) action to create an Amazon Q custom plugin for your web experience chat. The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
**To create a custom plugin,** choose a tab based on your access preference for Amazon Q.
------
#### [ Console ]
**To create a application-name plugin**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the Amazon Q Business console, in **Applications**, click on the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. In **Plugins**, choose **Add plugin**.
1. In **Add plugins**, choose **Custom plugin**.
1. In **Custom plugin**, enter the following information:
1. In **Name and description**, for **Plugin name** – A name for your Amazon Q plugin. The name can include hyphens (-) but not spaces and can have a maximum of 1000 alphanumeric characters.
1. In **API schema**, for **API schema source**, choose from the following options:
+ **Select from Amazon S3** – Choose this to select an existing API schema from an Amazon S3 bucket. Your API schema must have an API description, structure, and parameters for your custom plugin. Then, enter the **Amazon S3 URL** to your API schema.
+ **Define with in-line OpenAPI schema editor** – Choose this to write your custom plugin API schema in the inline OpenAPI schema editor in the Amazon Q console. A sample schema appears that you can edit. Then, you can choose to do the following:
+ Select the format for the schema, whether **JSON** or **YAML**.
+ To import an existing schema from S3 to edit, select **Import schema**, provide the S3 URL, and select **Import**.
+ To restore the schema to the original sample schema, select **Reset** and then confirm the message that appears by selecting **Reset** again.
1. **Authentication** – Choose between **Authentication required** or **No authentication required**. If no authentication is required, there is no further action needed. If authentication is required, choose to **Create and add a new secret** or **Use an existing one**. Your secret must contain:
1. **Secret name** – A name for your Secrets Manager secret.
1. **Client ID** – The client ID you copied from your third-party application.
1. **Client secret** – The client secret you copied from your third-party application.
1. **OAuth callback URL** – The URL to which user needs to be redirected after authentication. If your deployed web url is ``, use `/oauth/callback` . Amazon Q Business will handle OAuth tokens in this URL. This callback URL needs to be allowlisted in your third-party application.
1. In **Choose a method to authorize Amazon Q Business** – Choose to **Create and add a new service role** or **Use an existing service role**. Make sure your service role has the necessary permissions.
The console will generate a **Service role name**.
1. **Tags – *optional*** – An optional tag to track your plugin.
1. Select **Add plugin** to add your plugin.
------
#### [ CLI ]
**To create a custom plugin**
```
aws qbusiness create-plugin \
--application-id application-id \
--display-name display-name \
--type CUSTOM \
--auth-configuration basicAuthConfiguration="'{"noAuthConfiguration": {}}' \
--custom-plugin-configuration '{"description":"description, "apiSchemaType": "OPEN_API_V3", "apiSchema": {"s3": {"bucket": s3_bucket_with_openapi_schema "key":s3_key_with_openapi_schema}}}'"
```
------
# Using an Amazon Q Business custom plugin
Once a custom plugin is deployed, end users can launch it from the menu icon in the Amazon Q Business web experience.
**Note**
If your [Admin controls and guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html) settings allow Amazon Q to automatically orchestrate end user chat queries across plugins and data sources, plugin actions will be automatically activated by Amazon Q for your end user during chat. In that case, your end user won't have to follow the steps below.
![\[Screenshot showing the Amazon Q Business web experience menu with the custom plugin option highlighted, allowing users to select and activate the plugin.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/1-custom-plugin-select-menu@2x.png)
End users can then type a prompt.
![\[Screenshot showing a user typing a prompt in the Amazon Q Business chat interface to interact with the custom plugin, demonstrating how users can make requests to the plugin.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/2-custom-plugin-prompt@2x.png)
If it is the first time an end user is accessing the custom plugin or their past login has expired, they will need to authenticate. After authenticating successfully, Amazon Q Business will perform the requested task. For a write API operation, end users will always get a confirmation form that allows them to confirm or correct parameters that were populated based on the request or past actions.
![\[Screenshot showing a confirmation form displayed by the custom plugin, allowing users to verify and modify parameters before the plugin performs the requested action.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/3-custom-plugin-form@2x.png)
Once the user confirms the action, Amazon Q Business will submit the request and give the user confirmation once it is complete.
![\[Screenshot showing a success message after the custom plugin has completed the requested action, confirming to the user that their request was processed successfully.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/4-custom-plugin-success@2x.png)
# Managing Amazon Q Business plugins
To manage Amazon Q plugins, you can take the following actions:
**Topics**
+ [Updating a plugin](#plugin-update)
+ [Deleting a plugin](#plugin-delete)
+ [Getting plugin properties](#plugin-properties)
+ [Listing plugins](#plugin-list)
+ [Listing configured plugin actions](#plugin-list-actions)
+ [Listing available plugin actions](#plugin-list-actions-type)
+ [Listing plugin metadata](#plugin-list-metadata)
## Updating a plugin
To update a plugin, you can use AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdatePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdatePlugin.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To update a plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, select the plugin that you want to update, and then choose **Actions**.
1. For **Actions**, choose **Edit**.
On the plugins configuration page, you can edit your settings.
**To deactivate a plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, select the plugin that you want to deactivate, and then choose **Actions**.
1. For **Actions**, choose **Deactivate**.
Your plugin will be deactivated. After your plugin is deactivated, its status will change to **Inactive**.
**To reactivate a plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, select the plugin that you want to reactivate, and then choose **Actions**.
1. For **Actions**, choose **Reactivate**.
Your plugin will be activated. After your plugin is reactivated, its status will change to **Active**.
------
#### [ AWS CLI ]
**To edit a plugin**
```
aws qbusiness update-plugin \
--application-id application-id \
--plugin-id plugin-id \
--display-name display-name \
--server-url https://example.atlassian.net \
--auth-configuration basicAuthConfiguration="{secretArn=,roleArn=}"
```
**To disable a plugin**
```
aws qbusiness update-plugin \
--application-id application-id \
--plugin-id plugin-id \
--state DISABLED
```
**To enable a plugin**
```
aws qbusiness update-plugin \
--application-id application-id \
--plugin-id plugin-id \
--state ENABLED
```
------
## Deleting a plugin
To delete a plugin, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeletePlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeletePlugin.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To delete a plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, select the plugin that you want to delete, and then choose **Actions**.
1. For **Actions**, choose **Delete**.
1. In the dialog box, type **delete** to confirm your action.
The console displays a successful deletion message when the plugin deletion process is finished.
------
#### [ AWS CLI ]
**To delete a plugin**
```
aws qbusiness delete-plugin \
--application-id application-id \
--plugin-id plugin-id
```
------
## Getting plugin properties
To get the details of an Amazon Q plugin, you can use either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetPlugin.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetPlugin.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To get plugin details**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. For **Plugins**, select the configured plugin that you want to see details for.
1. On the **Plugin settings** page, the following details are available:
+ **Name** – The name of your plugin.
+ **Type** – The type of your plugin.
+ **AWS Secrets Manager** – The Secrets Manager secret.
+ **Creation time** – The time stamp for when your plugin was created.
+ **Plugin ID** – The ID that's assigned to your plugin.
------
#### [ AWS CLI ]
**To get plugin details**
```
aws qbusiness get-plugin \
--application-id application-id \
--plugin-id plugin-id
```
------
## Listing plugins
To list Amazon Q plugins, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPlugins.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPlugins.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To list plugins**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. In **Plugins**, a list of plugins that are attached to your application is available.
------
#### [ AWS CLI ]
**To list plugins**
```
aws qbusiness list-plugins \
--application-id application-id
```
------
## Listing configured plugin actions
To list actions configured for a specific Amazon Q plugin, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginActions.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginActions.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To list specific actions configured for a plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. In **Plugins**, select your plugin from the list of plugins configured for your application.
1. On the plugin summary page, you'll find the actions supported by your plugin under **Actions supported**.
------
#### [ AWS CLI ]
**To list specific actions configured for a plugin**
```
aws qbusiness list-plugin-actions \
--application-id application-id \
--plugin-id plugin-id
```
------
## Listing available plugin actions
To list all available actions for a specific Amazon Q plugin, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeActions.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeActions.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To list all available actions for a specific plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. On the **Plugins** page, under each plugin type, you'll find all the plugins actions supported by Amazon Q Business.
------
#### [ AWS CLI ]
**To list all available actions for a specific plugin**
```
aws qbusiness list-plugin-type-actions \
--plugin-type SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM | QUICKSIGHT | SERVICENOW_NOW_PLATFORM | JIRA_CLOUD | SALESFORCE_CRM | ZENDESK_SUITE | ATLASSIAN_CONFLUENCE | GOOGLE_CALENDAR | MICROSOFT_TEAMS | MICROSOFT_EXCHANGE | PAGERDUTY_ADVANCE | SMARTSHEET | ASANA
```
------
## Listing plugin metadata
To list metadata for a specific Amazon Q plugin, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeMetadata.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeMetadata.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To list metadata for a specific plugin**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the Amazon Q console, in **Applications**, select the name of your application from the list of applications.
1. From the left navigation menu, choose **Actions**, and then choose **Plugins**.
1. On the **Plugins** page, under each plugin type, you'll find all the plugin metadata (category, description, and type) supported by Amazon Q Business.
------
#### [ AWS CLI ]
**To list metadata for a specific plugin**
```
aws qbusiness list-plugin-type-metadata
```
------