# Built-in plugins for Amazon Q Business
<a name="built-in-plugin"></a>

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
<a name="basic-plugins-prereqs"></a>

**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
<a name="asana-actions"></a>

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
<a name="asana-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="asana-plugin-iam"></a>

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
<a name="asana-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring an Atlassian Confluence plugin for Amazon Q Business
<a name="confluence-actions"></a>

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
<a name="confluence-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="confluence-plugin-iam"></a>

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
<a name="confluence-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Google Calendar plugin for Amazon Q Business
<a name="gcal-actions"></a>

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
<a name="gcal-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="gcal-plugin-iam"></a>

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
<a name="gcal-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Jira Cloud plugin for Amazon Q Business
<a name="jira-actions"></a>

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
<a name="jira-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="jira-plugin-iam"></a>

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
<a name="jira-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Microsoft Exchange plugin for Amazon Q Business
<a name="exchange-actions"></a>

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
<a name="exchange-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="exchange-plugin-iam"></a>

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
<a name="exchange-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Microsoft Teams plugin for Amazon Q Business
<a name="teams-actions"></a>

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
<a name="teams-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="teams-plugin-iam"></a>

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
<a name="teams-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a PagerDuty Advance plugin for Amazon Q Business
<a name="pagerduty-actions"></a>

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
<a name="pagerduty-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="pagerduty-plugin-iam"></a>

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
<a name="pagerduty-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Salesforce plugin for Amazon Q Business
<a name="salesforce-actions"></a>

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
<a name="salesforce-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="salesforce-plugin-iam"></a>

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
<a name="salesforce-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a ServiceNow plugin for Amazon Q Business
<a name="servicenow-actions"></a>

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
<a name="servicenow-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="servicenow-plugin-iam"></a>

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
<a name="servicenow-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Smartsheet plugin for Amazon Q Business
<a name="smartsheet-actions"></a>

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
<a name="smartsheet-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="smartsheet-plugin-iam"></a>

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
<a name="smartsheet-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Zendesk Suite plugin for Amazon Q Business
<a name="zendesk-actions"></a>

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
<a name="zendesk-plugin-prereqs"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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
<a name="zendesk-plugin-iam"></a>

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
<a name="zendesk-plugin-create"></a>

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 `<q-endpoint>`, use `<q-endpoint>/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=<secret-arn>,roleArn=<role-arn>,authorizationUrl=<auth-url>,tokenUrl=<token-url>}"
```

------

# Configuring a Jira plugin for Amazon Q Business
<a name="jira-plugin"></a>

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
<a name="jira-plugin-prereqs"></a>

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
<a name="jira-plugin-iam"></a>

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
<a name="jira-plugin-create"></a>

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=<secret-arn>,roleArn=<role-arn>}"
```

------

# Configuring a Salesforce plugin for Amazon Q Business
<a name="salesforce-plugin"></a>

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
<a name="salesforce-plugin-prereqs"></a>

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
<a name="salesforce-plugin-iam"></a>

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
<a name="salesforce-plugin-create"></a>

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=<secret-arn>,roleArn=<role-arn>}"
```

------

# Configuring a ServiceNow plugin for Amazon Q Business
<a name="servicenow-plugin"></a>

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
<a name="servicenow-plugin-prereqs"></a>

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
<a name="servicenow-plugin-iam"></a>

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
<a name="servicenow-plugin-create"></a>

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=<secret-arn>,roleArn=<role-arn>}"
```

------

# Configuring a Zendesk plugin for Amazon Q Business
<a name="zendesk-plugin"></a>

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
<a name="zendesk-plugin-prereqs"></a>

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
<a name="zendesk-plugin-iam"></a>

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
<a name="zendesk-plugin-create"></a>

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=<secret-arn>,roleArn=<role-arn>}"
```

------

# Using Amazon Q Business built-in plugins
<a name="using-plugins"></a>

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
<a name="end-user-plugin-flow"></a>

**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
<a name="plugin-prompts"></a>

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
<a name="quick-create"></a>

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
<a name="context-create"></a>

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
<a name="context-create-servicenow"></a>
+ **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
<a name="context-create-zendesk"></a>
+ **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
<a name="context-create-salesforce"></a>
+ **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
<a name="context-create-jira"></a>
+ **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`