# Work with integrations in Amazon Quick
<a name="working-with-integrations"></a>

Integrations in Amazon Quick connect you to external applications and services for AI-powered analysis and automation. With integrations, you can perform actions in external applications and bring data from external applications to enhance your AI agents and chat experiences.

You can create three types of integrations:

**Action connectors**  
Initiate real-time calls to perform actions in external services. Use action connectors to address user natural language chat requests, automate workflows, send notifications, and/or trigger processes in connected applications.

**Data access integrations**  
Connect Quick with external applications to access data. Data access integrations serve as the foundation for creating knowledge bases. You cannot use these integrations directly for analysis.

**Knowledge bases**  
Connect to data access integrations to make specific content accessible for AI analysis. Choose which data or knowledge to include from external applications. Add knowledge bases to spaces or use them directly with chat agents.

Use the Integrations tab in the Amazon Quick console to create these connections. You can connect to Model Context Protocol (MCP) servers, Google Drive, Amazon S3, web crawlers, OneDrive, and other supported applications.

**Note**  
Not all applications support all integration types. Available options depend on each application's capabilities.

**Topics**
+ [Supported integrations](supported-integrations.md)
+ [Set up integrations in the console](integration-console-setup-process.md)
+ [Integration workflows](integration-workflows.md)
+ [Knowledge bases](knowledge-base-integrations.md)
+ [Action connectors](action-integrations.md)
+ [Integration-specific guides](integration-guides.md)
+ [Bring Your Own Amazon Q Business Index (BYOI)](quick-byoa.md)

# Supported integrations
<a name="supported-integrations"></a>

Amazon Quick supports integrations with various third-party applications and services. Each integration supports different combinations of actions and knowledge base creation capabilities. The following table shows the supported integrations and their capabilities.


**Supported Integration Capabilities**  

| Integration | Actions | Knowledge Base | 
| --- | --- | --- | 
| Amazon S3 | ✓ | ✓ | 
| Asana | ✓ | — | 
| Atlassian Confluence Cloud | ✓ | ✓ | 
| BambooHR | ✓ | — | 
| Box | ✓ | — | 
| Canva | ✓ | — | 
| GitHub | ✓ | — | 
| Google Drive | — | ✓ | 
| HubSpot | ✓ | — | 
| HuggingFace | ✓ | — | 
| Intercom | ✓ | — | 
| Atlassian Jira Cloud | ✓ | — | 
| Linear | ✓ | — | 
| Microsoft Outlook | ✓ | — | 
| Microsoft OneDrive | ✓ | ✓ | 
| Microsoft SharePoint Cloud | ✓ | ✓ | 
| Microsoft Teams | ✓ | — | 
| Model Context Protocol (MCP) | ✓ | — | 
| Monday.com | ✓ | — | 
| Notion | ✓ | — | 
| OpenAPI Specification | ✓ | — | 
| PagerDuty | ✓ | — | 
| REST API | ✓ | — | 
| Salesforce | ✓ | — | 
| SAP Bill of Materials | ✓ | — | 
| SAP Business Partner | ✓ | — | 
| SAP Material Stock | ✓ | — | 
| SAP Physical Inventory Docs | ✓ | — | 
| SAP Product Master | ✓ | — | 
| ServiceNow | ✓ | — | 
| Slack | ✓ | — | 
| Smartsheet | ✓ | — | 
| Web Crawler | — | ✓ | 
| Zendesk Suite | ✓ | — | 

**Note**  
Not all applications support all integration types. The available options depend on the capabilities of each specific application and your user role.

## Integration capability definitions
<a name="integration-capability-definitions"></a>

**Actions**  
Call APIs and perform actions in external applications directly from Amazon Quick. You can share action connectors with other users and use them in automated workflows.

**Knowledge base**  
Create searchable repositories of information from external sources. Knowledge bases are children of data access integrations. Add them to spaces or use them directly in chat agents.

## Authentication method definitions
<a name="authentication-method-definitions"></a>

**User auth**  
Custom user-based OAuth authentication requiring base URL, client ID, client secret, token URL, auth URL, and redirect URL.

**Service auth**  
Service-to-service authentication using either API key (with base URL and email) or service-to-service OAuth (with base URL, client ID, client secret, and token URL).

**Managed OAuth 2.0**  
Managed OAuth 2.0 authentication flow with provider-specific sign-in interface.

**AWS credentials**  
AWS-specific authentication using AWS access keys and permissions.

**Basic auth**  
Username and password authentication.

**Form/SAML auth**  
Form-based or SAML authentication with configurable field selectors.

**JSON schema**  
Schema-based authentication for OpenAPI specifications.

# Set up integrations in the console
<a name="integration-console-setup-process"></a>

The Integrations console provides a streamlined interface for creating and managing integrations. When you access the Integrations tab, you see all available applications in a unified grid. The console setup process adapts based on the integration you select, your user tier, and existing integrations.

## Choose integration options
<a name="main-integration-choices"></a>

When you select an integration from the main grid, the console branches based on several factors:
+ **Integration capabilities** - Each application supports different combinations of actions and knowledge base creation. For example, Google Drive supports data ingestion not actions. OneDrive supports both data ingestion and actions.
+ **Subscription** – Configuring integrations requires an Enterprise subscription. This includes creating action connectors, setting up knowledge bases, and managing integration settings. Users with a Professional subscription can use integrations that have been shared with them.
+ **Existing integrations** - The console first shows existing integrations before offering to create new ones.

## View setup process examples
<a name="setup-process-examples"></a>

The following examples show how different integrations guide you through different console setup processes:

### Google Drive - Bring data for Q&A
<a name="confluence-setup-flow"></a>

Google Drive supports data access integrations and knowledge base creation.

1. In the console, choose **Integrations**.

1. From the integration grid, choose **Google Drive**, and select the add icon.

1. The OAuth popup appears. Complete the OAuth process and grant it all the necessary permissions. Choose **Continue**.

1. You are taken to the Create knowledge base page. Select the files you want to assign to your knowledge base, and choose Select.

1. Enter a name and description. Choose **Create**.

### OneDrive - Perform actions and bring data for Q&A
<a name="onedrive-setup-flow"></a>

OneDrive supports the capabilities to both perform actions and bring data for Q&A. The console provides options for both capabilities during setup.

1. In the console, choose **Integrations**.

1. From the integration grid, choose **OneDrive**.

1. In the Create Integration dialog, select your integration type:
   + **Perform actions in OneDrive** - Enables actions like creating, updating, or managing OneDrive files.
   + **Bring data from OneDrive** - Enables you to ask questions about and get insights from your OneDrive content.
   + **Both** - Combines task and data ingestion capabilities.

1. Enter integration details and configure Microsoft 365 authentication.

1. If you selected "Bring data from OneDrive", select the files you want to add to your knowledge base using the file picker interface.

1. Choose **Create** to complete the setup.

### Working with existing integrations
<a name="existing-integration-reuse"></a>

When you select an integration type that you've used before, the console first displays your existing integrations.

1. In the console, choose **Integrations**.

1. Choose an integration type you've used before (for example, **OneDrive**).

1. The console displays a table of existing integrations with columns for:
   + **Name** - Integration name
   + **Status** - The status of the integration (ex. Available, Completed with issues)
   + **Visibiliy** - The visilibity level of the integration (ex. Personal, Shared)
   + **Owner** - The integration creator
   + **Last Modified** - Most recent update
   + **Actions** - A dropdown menu to perform actions on existing integrations

1. Choose an existing integration to view details, or choose add **\$1** to set up an additional connection.

## Integration management options
<a name="integration-management-options"></a>

After creating integrations, you can manage them through several console options:
+ **Edit integration** - Modify integration settings, authentication details, and configuration options
+ **Delete integration** - Remove integrations with confirmation dialogs to prevent accidental deletion
+ **Knowledge base management** - Separate flows for creating, editing, and deleting knowledge bases associated with your integrations

# Integration workflows
<a name="integration-workflows"></a>

The following procedures describe the general workflows for creating and managing different types of integrations in Amazon Quick.

## Creating a knowledge base from scratch
<a name="creating-data-access-integration"></a>

Data access integrations establish the connection to external systems creating knowledge bases from external data sources.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Knowledge bases** tab.

1. From the integration grid, choose the application you want to connect to (for example, **Google Drive**, **OneDrive**, or **S3**).

1. In the Integration details section, select the "Add" option (**\$1**). If required, complete the authentication process in the popup that occurs.

1. Fill in the appropriate details, depending on your chosen integration. For example, for Amazon S3, select your AWS account and your Amazon S3 bucket url.

1. Enter a **Name** for your integration.

1. Enter the required connection details for your chosen application.

1. If required, choose **Create and continue** to continue to knowledge base creation.

1.  Specify a name for your knowledge base.

1.  Specify the files you want to include in your knowledge base using the file picker or appropriate sync options (for example, **S3** allows you to choose to add all content of specific content).

1.  Choose **Create**.

   Syncing of your content will automatically begin after creation of the knowledge base.

## Creating an action connector
<a name="creating-task-integration"></a>

Action Connectors enable you to perform actions in external applications directly from Amazon Quick. 

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. From the integration grid, choose an application that supports action connectors (for example, **OneDrive**, **Confluence**, or **Slack**).

1. In the Integration details section, select the "Add" option (**\$1**).

1. Enter a **Name** for your action connector.

1. Configure the task-specific settings for your chosen application. 

1. Choose **Next** to complete the authentication and setup process. 

After successful creation, your action connector is available for use in Amazon Quick workflows and can be triggered from analyses, dashboards, or automated processes.

## Managing existing integrations
<a name="managing-existing-integrations"></a>

You can edit, delete, share, and manage existing integrations from the Integrations console. You can access management options from the integrations list or from an integration's details page.

### To edit an integration
<a name="to-edit-integration"></a>

From the integrations list:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Knowledge bases** or **Actions** tab.

1. Choose the **Open menu** icon in the row of the integration you want to edit.

1. Choose **Edit**.

1. Modify the integration settings as needed and choose **Save changes**.

You can also edit from the integration details page by choosing the integration name, then choosing the menu icon (⋮) and selecting **Edit**.

### To delete an integration
<a name="to-delete-integration"></a>

From the integrations list:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Knowledge bases** or **Actions** tab.

1. Choose the **Open menu** icon in the row of the integration you want to delete.

1. Choose **Delete**.

1. In the confirmation dialog, review the integration details and choose **Delete** to confirm.

You can also delete from the integration details page by choosing the integration name, then choosing the menu icon (⋮) and selecting **Delete**.

The integration is permanently removed from your account. Any dependent resources (such as knowledge bases) that rely on this integration will be impacted.

### To share an integration
<a name="to-share-integration"></a>

From the integrations list, choose the **Open menu** icon in the row of the integration and choose **Share**. You can also choose **Share** from the integration details page.

### Managing action connectors
<a name="managing-action-connectors"></a>

Action connector integrations have additional management options available from the integration details page.

**Sign in or re-connect**  
For integrations that use user-based OAuth authentication, you must sign in to the server before you can use its actions. If you have not yet signed in, a **Sign in** button appears at the top of the details page. After you sign in, the button changes to **Re-Connect**, which you can use to re-authenticate if your session expires or the connection is interrupted.

**Test action APIs**  
Choose **Test action APIs** in the Actions section of the details page to test individual actions provided by the integration. This lets you verify that the connection is working correctly and that the server responds as expected.

**Note**  
The **Test action APIs** option is available for action connectors only. Knowledge base integrations do not support action testing.

# Knowledge bases
<a name="knowledge-base-integrations"></a>

A knowledge base is an organized, indexed collection of documents or content from data sources optimized for generative AI-powered retrieval and question answering. Whether your team stores documentation in Confluence, collaborates through SharePoint, or manages files in cloud storage, you can bring all this information into one unified search experience by creating knowledge bases.

 The built-in integrations can be set up with just a few clicks to sync your data in Quick and make it effortless to tap into your organization's knowledge across Google Drive, OneDrive, Confluence, SharePoint, S3, and Web Crawler. Whether your team stores documentation in Confluence, collaborates through SharePoint, or manages files in cloud storage, you can bring all this information into one unified search experience with the help of knowledge bases. 

## How knowledge bases work
<a name="how-knowledge-bases-work"></a>

Knowledge base is an indexed collection of documents or content from data sources such as Google Drive, optimized for generative AI-powered retrieval and question answering. Multiple knowledge bases can be created from the same source, and all can reside within a shared Quick Index. For example, if you sync two folders from Google Drive and create two knowledge bases — one for “Policy Documents” to answer queries such as *“What’s our refund policy”* and one for “Customer feedback” to answer queries such as *“What are the common customer complaints”* — both can be part of the same index. Quick distinguishes between them using the knowledge base id, so queries can be filtered to retrieve only the relevant documents from the desired knowledge base. This allows users to organize, secure, and retrieve information relevant to different domains or use cases, even though the underlying data is indexed together.

Your knowledge bases can be used individually or shared with team members through Amazon Quick spaces. Our coarse-grained access control enables security at the knowledge base level, ensuring that users only receive information from knowledge bases they're authorized to access.

### Creation process
<a name="knowledge-base-creation-process"></a>

You can create knowledge bases while setting up a new data access integration and use existing integrations to create additional knowledge bases:

1. **Data access integration setup** - Connect to your external data source

1. **Content selection** - Choose which content to include through filters and scope settings

1. **Indexing** - Amazon Quick processes and indexes the selected content

1. **Availability** - The knowledge base becomes available for use in spaces and by AI agents

### Capabilities
<a name="knowledge-base-capabilities"></a>

Each knowledge base provides the following capabilities:
+ **Content indexing** - Processes text, documents, and structured data from external sources
+ **Semantic search** - Enables AI-powered search across indexed content
+ **Automatic synchronization** - Keeps content up-to-date with configurable sync schedules
+ **Coarse-grained access control** - Ensures that users only receive information from knowledge bases they're authorized to access.
+ **Multi-space usage** - Can be used across multiple spaces and by different AI agents

## General workflow
<a name="general-workflow"></a>

The typical workflow for working with knowledge bases follows these steps:

1. **Set up data source integration** - Connect to your external application (such as SharePoint, Google Drive, or Confluence) with appropriate authentication. For more information, see [Integration-specific guides](integration-guides.md).

1. **Create a knowledge base** - You can create a knowledge base while configuring your new integration. Configure your content filters by setting up include filters, file type restrictions, and folder selections to focus on relevant content.

1. **Set sync schedule** - Data refresh frequency is set to daily by default. You can edit the sync frequency to configure how often the knowledge base should be updated with new content from the source.

1. **Monitor and manage** - Review sync status, manage access permissions.

## Common configuration settings
<a name="common-configuration-settings"></a>

Knowledge bases share common configuration patterns across different data source integrations. Understanding these settings helps you optimize content indexing and manage sync behavior effectively.

**Note**  
While these configuration options are available across most integrations, specific settings and available options may vary depending on your chosen data source integration.

### File size and content limits
<a name="file-size-and-content-limits"></a>

Configure file size limits to optimize processing performance and manage storage costs. The specific limits vary by content type and are displayed in the console when you configure your knowledge base.

**Standard text documents**  
Applies to documents like PDFs, Word files, and text files. File size limit is 500 MB.

**Video files**  
Available when video processing is enabled. Supported formats include `.mp4`, `.mov`, `.m4v`. File size limit is 10 GB (10240 MB). Quick Index supports up to **10 video files per GB of storage**. If your use case requires higher video volumes, please open a ticket with AWS support to extend this limit.

**Audio files**  
Available when audio processing is enabled. Supported formats include `.mp3`,` .wav`,` .m4a`, `.flac`, and` .ogg`. Limit is 2 GB (2048 MB) for audio files.  
Files with extracted text that exceeds the 30 MB system limit are not indexed, regardless of the original file size. The maximum amount of text that can be extracted from a single document is 30 MB.

**Images**  
Quick Index applies the following limits for images:  
+ **Per-document limit**: 500 images per document
+ **Per-GB limit**: 10K images per GB of index storage
+ **Per-index limit**: 2M images per index
If your use case requires higher image volumes, please open a ticket with AWS support to extend these limits.

### Sync schedule and safeguards
<a name="sync-schedule-and-safeguards"></a>

Configure how often your knowledge base updates and protect against unintended content deletion:

#### Sync frequency
<a name="sync-frequency"></a>

Data refresh frequency is set to daily by default. You can edit the sync frequency to configure how often the knowledge base should update with new content from the source

#### Document deletion safeguard
<a name="document-deletion-safeguard"></a>

Protect your indexed content from accidental mass deletion by setting a maximum deletion percentage threshold. If a sync job would delete more documents than your threshold allows, the deletion phase is skipped, preserving your existing indexed content.

This safeguard protects against temporary network issues, permission changes, or source system problems that might make content temporarily unavailable.

# Best practices for managing ACLs in knowledge bases
<a name="acl-best-practices-kb"></a>

When using knowledge bases with access control lists (ACLs), you're responsible for keeping user identities and permissions accurate. This ensures the right people can access the right documents. Quick automatically syncs identity and document-level ACL changes every 24 hours by default. Any updates to users or permissions will take up to a day to appear in the system unless you've configured a different refresh schedule for your knowledge bases.

For more information about configuring ACLs for a specific data source, see [Amazon S3 integration](s3-integration.md).

**Note**  
Quick treats all email addresses as case-insensitive. `JohnDoe@example.com`, `johndoe@example.com`, and `JOHNDOE@example.com` are all considered the same user.

## Important user management scenarios
<a name="acl-user-management-scenarios"></a>

**Understanding email binding**

Email addresses are bound to Quick users dynamically when users initiate chat interactions. This binding follows a first-come-first-serve approach. The first user to chat with a given email address establishes the binding for that identity within the namespace.

**When an employee leaves your organization**

When an employee leaves, clean up their access promptly:

1. Update the ACL configuration files to remove references to their email address. For example, in Amazon S3, update the global ACL file or metadata files.

1. Refresh the knowledge bases to apply the changes.

This prevents potential security issues if the email is later reassigned to someone else.

**When an email address is reassigned to a new employee**
+ ACL-aware knowledge base access is automatically locked for the reassigned email address to protect data security.
+ Contact Quick support to clean up the previous user's access before the new employee can access documents associated with that email.

## Limitations
<a name="acl-limitations"></a>

When configuring document-level ACLs for your knowledge bases, be aware of these limitations:
+ **Document-level ACL configuration is permanent** – You cannot enable ACLs on knowledge bases created without ACL support. You also cannot disable ACLs once enabled. To change ACL configuration, create a new knowledge base with your desired setting from the start.
+ **Shared email addresses within a namespace** – If multiple Quick users share the same email address within a namespace, the system denies access to everyone using that shared email. This safeguard prevents accidentally granting document access to the wrong person.
+ **ACL resolution scope** – All ACLs are resolved within the Quick namespace of the knowledge base creator. This applies whether ACLs are specified by email address or group name. Quick looks up identities in the creator's organizational context to ensure consistent identity resolution.
+ **Email address recycling timing** – If your organization reassigns an email address from one employee to another, there's an important timing consideration. If the previous employee never used Quick for chat or AI interactions, and the email is reassigned before the next ACL refresh, the new employee may temporarily access documents intended for the previous employee.

  To avoid this, complete the following steps in order:

  1. Update your ACLs (if applicable, such as in Amazon S3) to remove the old user and add the new user.

  1. Manually refresh your knowledge base, or wait for the automatic daily refresh.

  1. Assign the email address to the new employee.

  This ensures access permissions are properly synchronized before the new user begins using Quick.
+ **Research compatibility** – Knowledge bases with document-level ACLs enabled are not currently compatible with Quick Research. If you need to use documents from an ACL-enabled knowledge base for research purposes, create a separate knowledge base without ACLs for those documents.

# Troubleshooting knowledge bases
<a name="troubleshooting-knowledge-bases"></a>

When you encounter issues with your Quick knowledge base, you can use this troubleshooting guide to identify and resolve common problems. Knowledge base issues typically involve document synchronization, refresh job failures, or access permissions.

## Documents don't appear in your knowledge base
<a name="documents-not-appearing"></a>

When documents you expect to see don't appear in your knowledge base, several factors might cause this issue.

**Common causes:**
+ **Sync in progress** – Documents might still be processing. Check the refresh status to confirm the refresh is complete.
+ **Unsupported file format** – Verify your documents are in supported formats: Word, Excel, PowerPoint, PDF, CSV, TXT, RTF, JSON, XML, HTML
+ **File size too large** – Each file must be less than 50 MB.
+ **Insufficient access permissions** – Confirm the knowledge base has proper permissions to access the document source.
+ **Document filtering** – Check if filters or exclusion rules prevent certain documents from being indexed.

**To troubleshoot:**

1. Review the refresh history for error messages related to specific documents that failed to sync.

1. Verify your document formats and file sizes meet requirements.

1. Check your access permissions and connection settings.

## Refresh job fails
<a name="refresh-job-fails"></a>

A refresh job typically fails when there's a configuration error in the knowledge base or data source connection.

**Common causes:**
+ **Permission issues** – The integration lacks sufficient permissions to access the data source.
+ **Configuration errors** – Incorrect URLs or data source connection settings.
+ **Resource limitations** – Rate limiting from the source system.

**To resolve:**

1. Check the refresh history details for specific error messages.

1. Verify all connection settings and permissions are correctly configured.

1. Take the recommended action based on the error message.

## Refresh job completes with issues
<a name="refresh-job-completes-with-issues"></a>

When a refresh job completes with issues, the job processed successfully but encountered problems with some documents.

**What this means:**
+ **Partial success** – Some documents synced successfully while others failed.
+ **Document-level errors** – Individual files might have formatting issues, corruption, or access problems.
+ **Metadata issues** – Problems with document metadata or associated information.
+ **Size or format violations** – Some files might exceed size limits or be in unsupported formats.

**To resolve:**

1. Review the detailed refresh reports to identify which documents encountered issues.

1. Address the individual document problems.

1. Run another refresh after resolving the issues.

## Refresh job succeeds but no documents appear
<a name="refresh-job-succeeds-no-documents"></a>

If a refresh job shows as successful but no documents appear in your knowledge base, check these potential causes.

**Common causes:**
+ **Empty source** – The configured data source location contains no documents.
+ **Incorrect path configuration** – The source path or connection settings don't point to the correct location.
+ **Document filters** – Inclusion or exclusion criteria might filter out all documents.
+ **Read permissions missing** – The job connected successfully but lacked permissions to read the actual documents.

**To resolve:**

1. Verify your data source configuration points to the correct location.

1. Confirm documents are present in the specified location.

1. Check that appropriate access permissions are configured.

1. Review any document filters that might exclude content.

## File format issues during refresh
<a name="file-format-issues"></a>

Quick knowledge bases support specific file formats. Files must meet format, size, and character limit requirements.

**Requirements:**
+ **Supported formats:** Word, Excel, PowerPoint, PDF, CSV, TXT, RTF, JSON, XML, HTML
+ **File size limit:** 50 MB per file
+ **File condition:** Not corrupted or password-protected

**To resolve format issues:**

1. Verify your files meet the format and size requirements.

1. Convert unsupported formats to supported ones.

1. Remove password protection from files.

1. Check that files aren't corrupted.

## Access denied errors
<a name="access-denied-errors"></a>

Access denied errors typically occur due to authentication or authorization issues.

**Common causes:**
+ **Invalid credentials** – Authentication tokens or passwords might have expired.
+ **Insufficient permissions** – The account used in the integration lacks read access to the data source.
+ **Network restrictions** – Firewall or security policies block access.
+ **SSL/TLS issues** – Certificate problems with secure connections.

**To resolve:**

1. **Verify authentication credentials** – Confirm that authentication credentials are current and valid. Edit the integration to re-authenticate and generate a new token.

1. **For web crawler data sources** – Verify that secure connections are properly configured and SSL certificates are properly configured and trusted.

1. **Contact your system administrator** – If you continue experiencing access issues, contact your system administrator. They might need to adjust permissions or security settings.

# Action connectors
<a name="action-integrations"></a>

Action connectors use secure connections to external services and execute actions based on your authentication level and permissions.

# How action connectors work
<a name="int-actions-how-it-works"></a>

Action connectors in Amazon Quick create secure connections between Amazon Quick and external services. When you configure these integrations, you can perform actions based on your authentication level and permissions.

## Core components
<a name="qbs-actions-how-it-works-qbs-actions-core-components"></a>

**Action connectors**  
The foundational resources that integrate with external services. Amazon Quick supports 15 third-party integrations and 5 AWS service integrations. For information about setting up AWS built-in service action connectors, see [AWS service action connectors](builtin-services-integration.md).

**Authentication methods**  
Action connectors support multiple authentication methods including managed (3LO), custom user-based, API key, and 2LO. For detailed information about each authentication method, see [Authentication methods](action-connector-apis.md#action-connector-apis-authentication).

**Implementation types**  
+ **On-demand actions for immediate, user-triggered operations** - Real-time operations that execute immediately when you trigger them. You can initiate actions through chat interfaces, dashboards, or Amazon Q Apps. Examples include creating tickets, sending messages, or querying data.
+ **Automated workflows for scheduled or system-triggered tasks** - System-managed operations that execute based on schedules or triggers. They run in the background without user intervention. Examples include data synchronization, report generation, or system maintenance.

**Permission models**  
+ **Personal access permissions through 3LO** - You can grant specific permissions to Amazon Quick through Three-Legged OAuth, maintaining control over your service access. Permissions are tied to your identity and credentials in the target service.
+ **Service-level permissions for automated workflows** - Applied to automated workflows, these permissions support system-to-system interactions without user involvement. They're configured at the service level and typically use API keys or service account credentials.
+ **Entity-level access controls** - Govern access to actions within Amazon Quick, determining which users or groups can execute specific actions. These controls integrate with Amazon Quick's broader permission system for consistent access management across the platform.

# Types of actions
<a name="int-actions-types"></a>

Amazon Quick supports two methods of invoking actions, each serving different use cases and authentication models.

## On-demand actions
<a name="qbs-actions-types-qbs-actions-on-demand"></a>

On-demand actions execute immediately when you trigger them. These actions support interactive operations that require real-time response.

**Key characteristics:**
+ User-initiated execution - You trigger actions through natural language in the chat interface.
+ Interactive form completion - You fill out forms with required parameters before the action executes.
+ Immediate response - Actions execute in real-time and provide instant feedback on success or failure.
+ Personal authentication (3LO) - Uses your individual credentials and permissions from the target service.

**Common use cases:**
+ Creating tickets in Jira.
+ Sending messages in Slack.
+ Updating Salesforce records.
+ Retrieving information from SharePoint.

## Automated workflows
<a name="qbs-actions-types-qbs-actions-automated-workflows"></a>

Automated workflows execute actions on a schedule or in response to specific triggers. These are useful for background and system-level operations.

**Key characteristics:**
+ System-level execution - Actions run automatically without user intervention based on predefined triggers.
+ Scheduled or event-triggered - Execute on time-based schedules or in response to specific system events.
+ Non-interactive operation - Run in the background without requiring user input or form completion.
+ Service-level authentication - Use system credentials rather than individual user authentication.

**Common use cases:**
+ Regular data synchronization.
+ Scheduled report generation.
+ Automated ticket updates.
+ System health checks.

# Bounded and unbounded agents
<a name="int-actions-bounded-unbounded"></a>

Amazon Quick offers two types of agents that provide different levels of access and functionality: bounded and unbounded agents. Understanding the differences between these agent types helps you implement the right solution for your use case.

## Bounded agents
<a name="qbs-actions-bounded-unbounded-qbs-actions-bounded-agents"></a>

Bounded agents operate within defined parameters, specifically linked to one or more spaces within Amazon Quick. These agents can only access and perform actions on resources that are explicitly connected to their assigned spaces. For example, a bounded agent configured for the HR space can only access HR-related documents, datasets, and execute HR-related actions.

Use bounded agents for:
+ Department-specific workflows (HR, Finance, IT).
+ Project team collaborations.
+ Sensitive data handling.
+ Compliance-focused operations.

The bounded nature provides enhanced security by ensuring the agent can't access resources outside its designated spaces. This makes it ideal for scenarios where data isolation is important.

## Unbounded agents
<a name="qbs-actions-bounded-unbounded-qbs-actions-unbounded-agents"></a>

Unbounded agents have broader access capabilities and can work across all configured actions and resources within the Amazon Quick environment. These agents aren't restricted to specific spaces and can access any properly configured action connector available in the system.

Use unbounded agents for:
+ Organization-wide assistance.
+ Cross-departmental workflows.
+ General-purpose actions.
+ Scenarios requiring access to multiple systems.

# Prerequisites
<a name="int-actions-prerequisites"></a>

Before using actions in Amazon Quick, ensure you have the following:

## License requirements
<a name="qbs-actions-prerequisites-qbs-actions-license-requirements"></a>

One of the following Amazon Quick licenses:
+ Reader Pro - Provides read access to data and the ability to execute actions in connected services.
+ Author - Includes Reader Pro capabilities plus the ability to create and modify content and configurations.
+ Author Pro - Full feature access including advanced action configuration and administrative capabilities.

## Service requirements
<a name="qbs-actions-prerequisites-qbs-actions-service-requirements"></a>

For third-party services (such as Jira or Salesforce), ensure that you have:
+ Appropriate permissions in the target services.
+ Authentication credentials for each service.

For AWS action connectors, you need admin access to the relevant services.

## AWS account requirements
<a name="qbs-actions-prerequisites-qbs-actions-aws-account-requirements"></a>
+ Active AWS account - A valid AWS account with billing enabled and in good standing.
+ Appropriate IAM permissions - IAM roles and policies that allow Amazon Quick to access the required AWS services.
+ Required service quotas - Sufficient service limits for the AWS services you plan to integrate with your actions.

# Supported action connector types and available actions
<a name="action-connector-apis-supported-types"></a>

Amazon Quick supports multiple connector types, each with specific actions available:

## External service connectors
<a name="action-connector-apis-external-services"></a>
+ **Salesforce** - Create records, update opportunities, search accounts, manage leads.
+ **JIRA** - Create issues, update tickets, search projects, manage workflows.
+ **Microsoft Outlook** - Send emails, manage calendar events, access contacts.
+ **Slack** - Send messages, create channels, manage notifications.
+ **ServiceNow** - Create incidents, update requests, manage workflows.
+ **Zendesk** - Create tickets, update cases, search knowledge base.
+ **PagerDuty** - Create incidents, manage escalations, update on-call schedules.
+ **Asana** - Create actions, update projects, manage team workflows.
+ **BambooHR** - Access employee data, manage time-off requests.
+ **Box** - Manage files, folders, and collaborate on documents.
+ **Canva** - Create and edit designs, manage templates and assets.
+ **FactSet** - Access financial data, generate reports.
+ **GitHub** - Manage repositories, issues, pull requests, and code collaboration.
+ **HuggingFace** - Access AI models, datasets, and machine learning workflows.
+ **HubSpot** - Manage contacts, deals, marketing campaigns, and CRM data.
+ **Intercom** - Manage customer conversations, support tickets, and messaging.
+ **Linear** - Create and manage issues, projects, and development workflows.
+ **Monday** - Manage projects, tasks, and team collaboration workflows.
+ **Notion** - Create and manage pages, databases, and collaborative workspaces.
+ **Smartsheet** - Update sheets, manage project data.
+ **Confluence** - Create, update, and manage pages, spaces, and other Confluence objects.
+ **SharePoint** - Perform actions on SharePoint lists, items, and Excel files with 19 available actions for creating, updating, deleting, and retrieving SharePoint content.
+ **OneDrive** - Create, update, delete, and manage OneDrive files and folders.
+ **SAP** - Access SAP S/4HANA systems to perform Read only operation on enterprise data.

## AWS service connectors
<a name="action-connector-apis-aws-services"></a>
+ **Amazon S3** - Upload files, manage buckets, retrieve objects.
+ **Amazon Bedrock** - Generate content, analyze data, process requests.
+ **Amazon Textract** - Extract text and data from documents.
+ **Amazon Comprehend** - Natural language processing and sentiment analysis.
+ **Amazon Comprehend Medical** - Medical text analysis and entity extraction.

## Action connector compatibility matrix
<a name="action-connector-compatibility-matrix"></a>

The following table shows which Amazon Quick features each action connector type supports:


**Action Connector Feature Compatibility**  

| Action Connector | Chat Agents | Flows | Dashboard Visuals | Dashboard Alerts | Automations | Companions | 
| --- | --- | --- | --- | --- | --- | --- | 
| AWS Built-in Services | 
| AWS Bedrock Agent Runtime | — | — | — | — | ✓ | — | 
| AWS Bedrock Data Automation Runtime | — | — | — | — | ✓ | — | 
| AWS Bedrock Runtime | — | — | — | — | ✓ | — | 
| Amazon Comprehend | — | — | — | — | ✓ | — | 
| Amazon Comprehend Medical | — | — | — | — | — | — | 
| Amazon S3 | — | — | — | — | ✓ | — | 
| Amazon Textract | — | — | — | — | ✓ | — | 
| External Service Connectors | 
| Asana | ✓ | ✓ | — | — | — | ✓ | 
| Atlassian Confluence Cloud | ✓ | ✓ | — | — | ✓ | ✓ | 
| Atlassian Jira Cloud | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| BambooHR | ✓ | ✓ | — | — | — | ✓ | 
| Box | ✓ | ✓ | — | — | — | — | 
| Canva | ✓ | ✓ | — | — | — | — | 
| FactSet | ✓ | ✓ | — | — | — | — | 
| GitHub | ✓ | ✓ | — | — | — | — | 
| HuggingFace | ✓ | ✓ | — | — | — | — | 
| HubSpot | ✓ | ✓ | — | — | — | — | 
| Intercom | ✓ | ✓ | — | — | — | — | 
| Linear | ✓ | ✓ | — | — | — | — | 
| Monday | ✓ | ✓ | — | — | — | — | 
| Notion | ✓ | ✓ | — | — | — | — | 
| Microsoft OneDrive | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Outlook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Microsoft SharePoint | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Teams | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| PagerDuty | ✓ | ✓ | — | — | ✓ | ✓ | 
| Salesforce | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| SAP | ✓ | — | — | — | ✓ | ✓ | 
| ServiceNow | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Slack | ✓ | ✓ | ✓ | — | — | ✓ | 
| Smartsheet | ✓ | ✓ | — | — | — | ✓ | 
| Zendesk | ✓ | ✓ | — | — | — | ✓ | 
| Custom Connector Types | 
| Model Context Protocol (MCP) | ✓ | ✓ | — | — | ✓ | — | 
| OpenAPI | ✓ | ✓ | — | — | — | — | 
| REST API | — | — | — | — | ✓ | — | 

**Authentication Support:**
+ **Chat Agents and Companions** - Support user authentication (3LO, Basic)
+ **Dashboard Visuals** - Support user authentication (3LO)
+ **Dashboard Alerts** - Support system authentication (2LO or API Key)
+ **Automations** - Support system authentication (2LO)

# Action connector APIs
<a name="action-connector-apis"></a>

Action connector APIs let you programmatically create and manage connections between Amazon Quick and external services. These APIs support the action integration functionality that allows users to perform actions in third-party applications directly from Amazon Quick chat interfaces and automated workflows.

## What are action connector APIs?
<a name="action-connector-apis-overview"></a>

Action connectors serve as the foundational resources that enable integration with first and third party applications. Through these APIs, you can authenticate to applications, manage permissions, and control which actions are available to users within your Amazon Quick applications.

### How action connector APIs support action integrations
<a name="action-connector-apis-task-integrations"></a>

Action connector APIs provide the backend infrastructure for Amazon Quick action integrations. When you create an action connector through the API, you establish a secure connection that lets you:
+ Execute actions in external services through chat interfaces.
+ Perform automated workflows in background processes.
+ Integrate third-party services with Amazon Quick applications.
+ Manage authentication and permissions for service access.

The APIs handle the complex authentication flows, credential management, and permission controls needed to securely connect Amazon Quick with external services.

## Authentication methods
<a name="action-connector-apis-authentication"></a>

Action connector APIs support multiple authentication methods to accommodate different use cases and security requirements:

### Managed authentication (3LO)
<a name="qbs-action-connector-apis-managed-auth"></a>

Three-Legged OAuth provides the simplest setup for personal access to third-party services:
+ No initial configuration required.
+ User-specific authentication through service provider login.
+ Automatic token refresh with 90-day lifecycle.
+ Secure credential storage managed by Amazon Quick.

### Service-to-service authentication (2LO)
<a name="qbs-action-connector-apis-service-auth"></a>

For complex enterprise integrations:
+ Supports client credentials OAuth flow.
+ Enables system-to-system interactions.
+ Requires client ID, client secret, and token URL configuration.
+ Suitable for automated workflows requiring sophisticated security.
+ OAuth - Dynamic Client Registration (DCR - applicable only for select MCP servers).

### API key authentication
<a name="qbs-action-connector-apis-api-key"></a>

Simplified authentication for automated workflows:
+ Single token-based authentication.
+ Service-level permissions.
+ Ideal for background processes and scheduled actions.
+ Requires valid API key from target service.

### Basic Auth
<a name="qbs-action-connector-apis-basic-auth"></a>

Basic authentication provides a simple username/password authentication method:
+ Uses standard HTTP Basic Authentication headers.
+ Credentials are base64 encoded.
+ Suitable for services that don't support OAuth or API keys.
+ Requires secure HTTPS connection.
+ Not recommended for public-facing services.

### None
<a name="qbs-action-connector-apis-no-auth"></a>

No authentication required:
+ Used for public APIs and services.
+ No credentials or tokens needed.
+ Limited to read-only or public operations.
+ Typically used for public data feeds and documentation.
+ Should not be used for sensitive operations.

## Permissions and access control
<a name="qbs-action-connector-apis-permissions"></a>

Action connector APIs implement comprehensive permission controls through Access Control Lists (ACLs):

### Resource-level permissions
<a name="qbs-action-connector-apis-resource-permissions"></a>
+ **Owner** - Full control including delete and permission management.
+ **Contributor** - Can use and modify connector settings.
+ **Viewer** - Can view connector details and use enabled actions.

### API operations for permission management
<a name="qbs-action-connector-apis-permission-operations"></a>
+ `DescribeActionConnectorPermissions` - Retrieve current permission settings.
+ `UpdateActionConnectorPermissions` - Grant or revoke user permissions.

## Supported connector categories
<a name="qbs-action-connector-apis-categories"></a>

### Dual-purpose connectors
<a name="qbs-action-connector-apis-dual-purpose"></a>

These connectors support both action integrations and knowledge base creation:
+ **Amazon S3** - Use the Admin Console to create Actions for file operations, use the webapp to create knowledge bases from S3 content.
+ **Microsoft SharePoint** - Document management actions, content indexing.
+ **OneDrive** - File operations, document search capabilities.
+ **Confluence** - Content creation actions, knowledge base integration.

### Action-only connectors
<a name="qbs-action-connector-apis-task-only"></a>

Specialized for action execution without knowledge base capabilities:
+ **Salesforce** - Enterprise CRM integration supporting account and contact operations, custom object CRUD operations, Sales process automation.
+ **JIRA** - Issue tracking and project management.
+ **Microsoft Outlook** - Send emails, manage calendar events, access contacts.
+ **Slack** - Communication and notification workflows.
+ **ServiceNow** - IT service management operations.
+ **Zendesk** - Create tickets, update cases, search knowledge base.
+ **PagerDuty** - Create incidents, manage escalations, update on-call schedules.
+ **Asana** - Create actions, update projects, manage team workflows.
+ **BambooHR** - Access employee data, manage time-off requests.
+ **Smartsheet** - Update sheets, manage project data.
+ **FactSet** - Access financial data, generate reports.
+ **SAP** - Access SAP systems, execute business functions, and manage enterprise data.

### Knowledge base-only connectors
<a name="qbs-action-connector-apis-data-only"></a>

Focused on knowledge base integration without action capabilities:
+ **Google Drive** - Document indexing and search.
+ **Web Crawler** - Content discovery and indexing.

## API lifecycle management
<a name="qbs-action-connector-apis-lifecycle"></a>

### Credential management
<a name="qbs-action-connector-apis-credential-management"></a>
+ Automatic refresh token handling for OAuth action connectors.
+ Secure storage of authentication credentials using AWS KMS.
+ Support for credential rotation and updates.
+ Cross-account access for Amazon S3 connectors.

### Connection updates
<a name="qbs-action-connector-apis-connection-updates"></a>

Use the `UpdateActionConnector` API to:
+ Modify authentication credentials.
+ Update service configuration parameters.
+ Change action connector metadata.

### Monitoring and troubleshooting
<a name="qbs-action-connector-apis-monitoring"></a>
+ Track API usage through CloudWatch metrics.
+ Monitor connection health and authentication status.
+ Implement error handling for common failure scenarios.
+ Use validation APIs to diagnose configuration issues.

## Rate limiting and quotas
<a name="qbs-action-connector-apis-rate-limiting"></a>

Action connector APIs implement standard AWS API rate limiting:
+ Standard AWS API throttling applies to all operations.
+ Connection validation may have additional limits.
+ Action execution rates depend on target service capabilities.
+ Implement exponential backoff for retry logic.

## Cross-account support
<a name="qbs-action-connector-apis-cross-account"></a>

For Amazon S3 connectors, the APIs support cross-account access:
+ Specify different AWS account IDs during connector creation.
+ Configure appropriate IAM permissions for cross-account access.
+ Use AWS KMS for secure credential management across accounts.
+ Validate permissions before enabling cross-account connections.

## Error handling and troubleshooting
<a name="qbs-action-connector-apis-error-handling"></a>

Action connector APIs return standard AWS error responses:

### Common error types
<a name="qbs-action-connector-apis-common-errors"></a>
+ `AccessDeniedException` - Insufficient permissions for the operation.
+ `InvalidParameterValueException` - One or more parameter values are invalid for the operation.
+ Invalid configuration parameters - Service-specific configuration values are incorrect or missing.
+ `ResourceNotFoundException` - Connector or resource not found.
+ `ThrottlingException` - Rate limit exceeded.
+ `ConflictException` - Resource conflict or duplicate names.
+ `InternalFailureException` - Internal service error occurred during request processing.
+ `ResourceExistsException` - Attempt to create a resource that already exists.
+ `InvalidNextTokenException` - The pagination token provided is invalid or expired.
+ `AccessTokenNotFoundException` - User needs to authorize the connection (that is, sign-button). This exception is used by UX to ask users for authorization.
+ `TokenResponseException` - Action setup is not valid.

Implement proper error handling in your applications to manage these scenarios gracefully and provide meaningful feedback to users.

## Using Action Connector APIs with AWS CLI
<a name="qbs-action-connector-apis-cli-examples"></a>

You can use the AWS CLI to manage action connectors programmatically. The following examples demonstrate common operations using generic placeholder values.

### Creating an action connector
<a name="create-action-connector-cli"></a>

Use the `create-action-connector` command to create a new action connector for integrating with external services.

```
aws quicksight create-action-connector \
  --aws-account-id "123456789012" \
  --name "MyS3Connector" \
  --action-connector-id "my-s3-connector-id" \
  --type "AMAZON_S3" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/MyConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" \
  --description "S3 connector for automation workflows" \
  --region "us-east-1"
```

### Listing action connectors
<a name="list-action-connectors-cli"></a>

Use the `list-action-connectors` command to retrieve all action connectors in your account.

```
aws quicksight list-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 10 \
  --region "us-east-1"
```

### Describing an action connector
<a name="describe-action-connector-cli"></a>

Use the `describe-action-connector` command to get detailed information about a specific action connector.

```
aws quicksight describe-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### Updating an action connector
<a name="update-action-connector-cli"></a>

Use the `update-action-connector` command to modify an existing action connector's configuration.

```
aws quicksight update-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --name "UpdatedS3Connector" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/UpdatedConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" "DeleteBucket" \
  --region "us-east-1"
```

### Searching action connectors
<a name="search-action-connectors-cli"></a>

Use the `search-action-connectors` command to find action connectors based on specific criteria.

```
aws quicksight search-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 5 \
  --filters '[{
    "Name": "ACTION_CONNECTOR_NAME",
    "Operator": "StringLike",
    "Value": "S3"
  }]' \
  --region "us-east-1"
```

### Managing action connector permissions
<a name="update-action-connector-permissions-cli"></a>

Use the `update-action-connector-permissions` command to grant or revoke permissions for an action connector.

```
aws quicksight update-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --grant-permissions '[{
    "Actions": [
      "quicksight:DescribeActionConnector",
      "quicksight:UpdateActionConnector",
      "quicksight:DeleteActionConnector"
    ],
    "Principal": "arn:aws:quicksight:us-east-1:123456789012:user/default/myuser"
  }]' \
  --region "us-east-1"
```

### Viewing action connector permissions
<a name="describe-action-connector-permissions-cli"></a>

Use the `describe-action-connector-permissions` command to view current permissions for an action connector.

```
aws quicksight describe-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### Deleting an action connector
<a name="delete-action-connector-cli"></a>

Use the `delete-action-connector` command to remove an action connector from your account.

```
aws quicksight delete-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

## Next steps
<a name="qbs-action-connector-apis-next-steps"></a>

After understanding action connector APIs, you can:
+ Review the complete API reference documentation for detailed parameter specifications.
+ Explore specific connector setup guides for your target services.
+ Implement authentication flows appropriate for your use case.
+ Set up monitoring and error handling for production deployments.
+ Configure permissions and access controls for your organization.

# Authentication methods
<a name="quick-action-auth"></a>

Amazon Quick supports multiple authentication methods, each designed for specific use cases and security requirements.

## Managed authentication (3LO)
<a name="quick-managed-auth"></a>

Three-Legged OAuth (3LO) is the recommended authentication method for personal access to third-party services.

**Key features of 3LO:**
+ No initial configuration required.
+ User-specific authentication.
+ Secure credential storage.
+ Automatic token refresh.
+ 90-day refresh token lifecycle.

**3LO setup process:**

1. Select connector.

1. Choose managed authentication.

1. Complete service provider login.

1. Grant requested permissions.

1. Confirm connection.

## Custom user-based authentication
<a name="quick-custom-user-auth"></a>

For scenarios that require specific organizational control or custom configuration.

**Required information:**
+ Client ID.
+ Client Secret.
+ Domain URL.
+ Authorization URL.
+ Token URL.
+ Redirect URL.

**Configuration steps:**

1. Obtain credentials from service provider.

1. Configure authentication settings.

1. Validate connection.

1. Test access permissions.

When configuring user-based authentication in the Amazon Quick console, obtain the proper credentials from your service provider and configure your authentication settings. Then validate the connection and test your access permissions.

## API key authentication
<a name="quick-actions-api-key-auth"></a>

Used primarily for automated workflows and system-level access.

**Key features:**
+ Simple token-based authentication.
+ Single credential management.
+ Service-level permissions.
+ Suitable for automated processes.

**Setup requirements:**

When setting up API Key authentication, ensure that you have the following:
+ Valid API key from service.
+ Appropriate service permissions.
+ Secret storage configuration.

## Service-to-service authentication
<a name="quick-actions-service-to-service-auth"></a>

For automated workflows that require complex authentication.

**Configuration requirements:**
+ Client ID.
+ Client Secret.
+ Domain URL.
+ Token URL.
+ Service-specific parameters.

# Action execution methods
<a name="int-actions-execution"></a>

Amazon Quick provides multiple ways to execute actions, accommodating different use cases and interaction preferences.

## Chat interface
<a name="qbs-actions-execution-qbs-actions-chat-interface"></a>

You can execute implicit actions in the Amazon Quick chat.

### Implicit actions
<a name="qbs-actions-execution-qbs-actions-implicit-actions"></a>

Amazon Quick also supports implicit action execution through natural conversation with agents. Using advanced natural language processing, the system can identify when your conversation indicates the need for specific actions. Conversations are analyzed to determine which actions are required to fulfill your request.

A single request might require multiple actions to complete. When this happens, the system handles these actions sequentially, guiding you through each step. For each identified action, the system presents the appropriate form for you to complete. After each action completes, you receive a confirmation before moving on to the next action in the sequence.

For example, if you ask "Create a Jira ticket for this issue and notify the team in Slack," the system would:

1. First present the Jira ticket creation form.

1. After completing the ticket creation, show the Slack message form.

1. Complete both actions in sequence.

Throughout the process, you can track your progress through multiple actions. When all actions complete, the system provides a comprehensive summary showing all executed actions and their outcomes. You can access related documentation if needed and review any error states that may have occurred during the process.

# Monitoring and maintenance
<a name="int-actions-monitoring"></a>

Monitoring your action connectors helps ensure reliable performance and identify issues before they impact users. Regular monitoring allows you to track usage patterns, optimize performance, and maintain healthy connections to external services.

## Performance monitoring
<a name="qbs-actions-monitoring-qbs-actions-performance-monitoring"></a>

You can assess action connector performance using the following metrics and analytics.

### CloudWatch metrics
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics"></a>
+ Action execution success rates - Track the percentage of successful action executions to identify reliability issues.
+ Response times - Monitor how long actions take to complete and identify performance bottlenecks.
+ Error frequencies - Track error patterns to identify common failure points and areas for improvement.
+ API quota usage - Monitor usage against service limits to prevent throttling and plan for capacity.

### Usage analytics
<a name="qbs-actions-monitoring-qbs-actions-usage-analytics"></a>

The following usage analytics are collected for action connectors:
+ Active users - Track how many users are actively using action connectors to understand adoption and usage patterns.
+ Popular actions - Identify which actions are used most frequently to prioritize optimization efforts.
+ Execution patterns - Analyze when and how often actions are executed to optimize resource allocation.
+ Error trends - Monitor error patterns over time to identify systemic issues and improvement opportunities.

## Connection health
<a name="qbs-actions-monitoring-qbs-actions-connection-health"></a>

You can assess action connector health using the following connection health tools:

### Status monitoring
<a name="qbs-actions-monitoring-qbs-actions-status-monitoring"></a>
+ Connection state - Monitor whether connectors are actively connected and functioning properly.
+ Authentication validity - Track the status of authentication tokens and credentials to prevent access failures.
+ Token expiration tracking - Monitor when authentication tokens will expire and need renewal.
+ Service availability - Track the availability and response status of connected external services.

### Automated maintenance
<a name="qbs-actions-monitoring-qbs-actions-automated-maintenance"></a>
+ Token refresh handling.
+ Connection recovery.
+ Error retry logic.
+ Performance optimization.

## CloudWatch metrics reference
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics-table"></a>


**Available CloudWatch metrics**  

| Metric | Description | Unit | 
| --- | --- | --- | 
| ActionSuccess | Successful executions | Count | 
| ActionLatency | Execution time | Milliseconds | 
| AuthFailures | Failed authentications | Count | 
| APIThrottling | API throttling events | Count | 

# Best practices
<a name="int-actions-best-practices"></a>

Following best practices for action connectors helps ensure secure, reliable, and efficient operations. These practices help you maintain optimal performance, protect sensitive data, and minimize operational issues.

## Security
<a name="qbs-actions-best-practices-qbs-actions-security-best-practices"></a>

### Authentication management
<a name="qbs-actions-best-practices-qbs-actions-authentication-management"></a>
+ Regular credential rotation - Update API keys and OAuth tokens on a scheduled basis to maintain security.
+ Periodic permission reviews - Audit user and service permissions quarterly to ensure least-privilege access.
+ Token lifecycle monitoring - Track token expiration dates and set up alerts before credentials expire.
+ Access audit logging - Enable comprehensive logging to track who accessed which services and when.

### Access control
<a name="qbs-actions-best-practices-qbs-actions-access-control"></a>
+ Implement least-privilege access - Grant only the minimum permissions necessary for each action to function properly.
+ Regular permission audits - Review and validate that current permissions align with actual usage patterns and business needs.
+ Document access patterns - Maintain clear documentation of who has access to which connectors and why.
+ Monitor usage anomalies - Set up alerts for unusual access patterns that might indicate security issues.

## Performance
<a name="qbs-actions-best-practices-qbs-actions-performance-best-practices"></a>

### Action configuration
<a name="qbs-actions-best-practices-qbs-actions-action-configuration"></a>
+ Optimize form defaults - Pre-populate commonly used values to reduce user input time and errors.
+ Configure appropriate timeouts - Set realistic timeout values based on typical response times for each service.
+ Set up error handling - Implement robust error handling with clear user messages and retry logic where appropriate.
+ Document dependencies - Clearly document any prerequisites or dependencies between different actions.

### Resource management
<a name="qbs-actions-best-practices-qbs-actions-resource-management"></a>
+ Monitor API quotas.
+ Track usage patterns.
+ Optimize refresh schedules.
+ Regular cleanup of unused connectors.

## Maintenance
<a name="qbs-actions-best-practices-qbs-actions-maintenance-best-practices"></a>

### Regular actions
<a name="qbs-actions-best-practices-qbs-actions-regular-tasks"></a>
+ Review connector status.
+ Update configurations.
+ Validate connections.
+ Document changes.

### Troubleshooting
<a name="qbs-actions-best-practices-qbs-actions-troubleshooting-tasks"></a>
+ Monitor error patterns.
+ Review CloudWatch logs.
+ Track resolution times.
+ Document solutions.

# Troubleshooting
<a name="int-actions-troubleshooting"></a>

When action connectors encounter issues, systematic troubleshooting helps you quickly identify and resolve problems. This guidance covers common issues and their solutions to minimize downtime and restore functionality.

## Common issues and solutions
<a name="qbs-actions-troubleshooting-qbs-actions-common-issues"></a>

### Authentication problems
<a name="qbs-actions-troubleshooting-qbs-actions-authentication-problems"></a>

#### Token expiration
<a name="qbs-actions-troubleshooting-qbs-actions-token-expiration"></a>

```
Symptom: "Authentication token expired" error
Resolution:
```

1. Choose "Reconnect" in console.

1. Complete authentication flow.

1. Retry action.

#### Permission errors
<a name="qbs-actions-troubleshooting-qbs-actions-permission-errors"></a>

```
Symptom: "Insufficient permissions" message
Resolution:
```

1. Verify service permissions.

1. Check connector configuration.

1. Review action requirements.

#### Connection failures
<a name="qbs-actions-troubleshooting-qbs-actions-connection-failures"></a>

```
Symptom: "Unable to connect to service" error
Resolution:
```

1. Verify service availability.

1. Check network connectivity.

1. Validate credentials.

1. Review service quotas.

### Action-specific issues
<a name="qbs-actions-troubleshooting-qbs-actions-action-specific-issues"></a>

#### Form submission failures
<a name="qbs-actions-troubleshooting-qbs-actions-form-submission-failures"></a>

##### Validation errors
<a name="qbs-actions-troubleshooting-qbs-actions-validation-errors"></a>
+ Check required fields.
+ Verify data formats.
+ Review field limitations.
+ Check for special characters.

##### Timeout issues
<a name="qbs-actions-troubleshooting-qbs-actions-timeout-issues"></a>
+ Reduce form complexity.
+ Check network latency.
+ Review service response times.
+ Consider breaking into multiple actions.

#### Sync and performance issues
<a name="qbs-actions-troubleshooting-qbs-actions-sync-performance-issues"></a>

##### Slow response times
<a name="qbs-actions-troubleshooting-qbs-actions-slow-response-times"></a>

```
Resolution:
```

1. Check API rate limits.

1. Review concurrent executions.

1. Monitor service health.

1. Optimize action configuration.

##### Failed executions
<a name="qbs-actions-troubleshooting-qbs-actions-failed-executions"></a>

```
Resolution:
```

1. Review CloudWatch logs.

1. Check error messages.

1. Verify service status.

1. Test connection health.

## Common error messages
<a name="qbs-actions-troubleshooting-qbs-actions-error-messages"></a>


**Error codes and resolutions**  

| Error code | Description | Resolution | 
| --- | --- | --- | 
| AUTH\$1001 | Authentication failed | Verify credentials and retry | 
| CONN\$1002 | Connection timeout | Check network and service status | 
| PERM\$1003 | Insufficient permissions | Review required permissions | 
| TOKEN\$1004 | Token expired | Reinitiate authentication | 

# Integration-specific guides
<a name="integration-guides"></a>

Use these guides to configure integrations with specific applications. Each guide includes setup instructions for both action and data ingestion capabilities when the integration supports them.

# Amazon S3 integration
<a name="s3-integration"></a>

With Amazon S3 integration in Amazon Quick, you can create knowledge bases from documents stored in S3 buckets. This integration supports data ingestion capabilities for indexing and searching S3 content.

**Note**  
This guide covers Amazon S3 data ingestion integration for knowledge base creation. For Amazon S3 action connectors that perform Amazon S3 operations such as uploading, downloading, and deleting files, see [AWS service action connectors](builtin-services-integration.md). Amazon S3 actions are only supported for Quick Automate.

## What you can do
<a name="s3-integration-capabilities"></a>

Amazon S3 users can ask questions about content stored in their Amazon S3 buckets. For example, users can inquire about key findings from documents, search for specific information across multiple file types, or analyze data patterns.

The integration enables users to quickly access and understand information from their Amazon S3 content, regardless of file location or type. It also provides contextual details such as modification dates and file metadata, contributing to more efficient information discovery and better-informed decision making.

## Before you begin
<a name="s3-integration-prerequisites"></a>

Before you set up Amazon S3 integration, make sure you have the following:
+ AWS account with Amazon S3 access.
+ Amazon S3 bucket with documents to index.
+ Amazon Quick Enterprise subscription.
+ Necessary permissions to create Amazon S3 integrations.
+ Your administrator must grant Amazon Quick access to the Amazon S3 buckets you want to use. For more information, see [Grant Amazon Quick access to Amazon S3 buckets](s3-admin-setup.md#s3-grant-bucket-access).

**Note**  
Cross-account Amazon S3 access is only supported within the same AWS region.

# Administrator setup
<a name="s3-admin-setup"></a>

Before users can create Amazon S3 integrations and knowledge bases, an Amazon Quick administrator must complete the following setup tasks.

## Grant Amazon Quick access to Amazon S3 buckets
<a name="s3-grant-bucket-access"></a>

Grant Amazon Quick access to the Amazon S3 buckets your organization needs. This applies whether the buckets are in the same AWS account or a different account.

1. In the Amazon Quick admin console, under **Permissions**, choose **AWS resources**.

1. Under **Allow access and autodiscovery for these resources**, select the **Amazon S3** checkbox.

1. Choose **Select S3 buckets**.

1. In the **Select Amazon S3 buckets** dialog, choose the tab that matches your bucket location:
   + **S3 Buckets Linked To Quick Account** – Select the buckets from the list that you want Amazon Quick to access. Selected buckets have read-only permissions by default.
   + **S3 Buckets You Can Access Across AWS** – For cross-account buckets, make sure the account owner has authorized your account. Choose **Use a different bucket**, enter the bucket name, and choose **Add S3 bucket**.

1. (Optional) For cross-account buckets, select **Restrict bucket access to knowledge base creator** to limit access so that only the user who creates the knowledge base can use the bucket.

1. Choose **Finish**.

The selected buckets are now accessible to users during knowledge base creation.

## Prepare IAM role and policy setup
<a name="s3-integration-authentication"></a>

Amazon S3 integration uses AWS authentication to access your Amazon S3 buckets. Prepare your IAM role and policy configuration before users set up the integration.

### Required IAM permissions
<a name="s3-integration-iam-permissions"></a>

Make sure your AWS account has the following minimum permissions for the Amazon S3 bucket:
+ `s3:GetObject` – Read objects from the bucket.
+ `s3:ListBucket` – List bucket contents.
+ `s3:GetBucketLocation` – Get bucket region information.
+ `s3:GetObjectVersion` – Get object versions.
+ `s3:ListBucketVersions` – List bucket versions.

### Configure Amazon S3 bucket permissions for cross-account access
<a name="s3-cross-account-bucket-policy"></a>

If you're accessing Amazon S3 buckets in a different AWS account, you must configure IAM policies in the source AWS account.

**To configure Amazon S3 bucket permissions for cross-account access**

1. Sign in to the AWS Management Console for the account that contains the Amazon S3 bucket.

1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Choose the bucket that you want to grant access to.

1. Choose **Permissions**, and then choose **Bucket Policy**.

1. Add a bucket policy with the following elements:
   + `Version` – Set to "2012-10-17"
   + `Statement` – Array containing policy statements with:
     + `Sid` – "AllowQuickSuiteS3Access"
     + `Effect` – "Allow"
     + `Principal` – AWS ARN for the Amazon Quick service role in your account. For example, the principal should look like this:` "Principal": { "AWS": "arn:aws:iam::<quick_account_id>:role/service-role/aws-quicksight-service-role-v0" }`
     + `Action` – Array of Amazon S3 permissions: s3:GetObject, s3:ListBucket, s3:GetBucketLocation, s3:GetObjectVersion, s3:ListBucketVersions
     + `Resource` – "\$1" (applies to the current key), the Amazon S3 bucket path should look like the following: `"Resource": [ "arn:aws:s3:::bucket_name"]`

1. Choose **Save changes**.

### Configure KMS key permissions (if your bucket uses encryption)
<a name="s3-kms-permissions"></a>

If your Amazon S3 bucket uses AWS KMS encryption, complete the following steps.

**To configure KMS key permissions**

1. Open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).

1. Choose the KMS key that is used to encrypt your Amazon S3 bucket.

1. Choose **Key policy**, and then choose **Edit**.

1. Add a statement to the key policy with the following structural elements:
   + `Sid` – "AllowQuickSuiteKMSAccess"
   + `Effect` – "Allow"
   + `Principal` – AWS ARN for the Amazon Quick service role in your account. For example, the principal should look like this:` "Principal": { "AWS": "arn:aws:iam::<quick_account_id>:role/service-role/aws-quicksight-service-role-v0" }`
   + `Action` – Array of KMS permissions: kms:Decrypt, kms:DescribeKey
   + `Resource` – "\$1" (applies to the current key), the Amazon S3 bucket path should look like the following: `"Resource": [ "arn:aws:s3:::bucket_name"]`

1. Choose **Save changes**.

1. Wait 2-3 minutes for the policy changes to propagate.

## Configure VPC access for Amazon S3 Connector in Amazon Quick
<a name="s3-vpc-support"></a>

VPC permissions ensure Amazon Quick can only access your Amazon S3 bucket through secure VPC or VPC endpoint connections.

### Required policy change
<a name="s3-vpc-required-policy"></a>

Add this statement to your bucket access policy to allow Amazon Quick to access your bucket through VPC endpoints:

```
{
  "Sid": "Allow-Quick-access"		 	 	 ,
  "Principal": "arn:aws:iam::Quick Account:role/service-role/aws-quicksight-service-role-v0",
  "Action": "s3:*",
  "Effect": "Allow",
  "Resource": [
    "arn:aws:s3:::amzn-s3-demo-bucket",
    "arn:aws:s3:::amzn-s3-demo-bucket/*"
  ],
  "Condition": {
    "Null": {
      "aws:SourceVpce": "false"
    }
  }
}
```
+ Replace `amzn-s3-demo-bucket` with your bucket name.
+ Replace `Quick Account` with your Amazon Quick account.

The `"aws:SourceVpce": "false"` condition ensures Amazon Quick can only access your bucket through VPC endpoints, maintaining your security requirements.

### Deny policies
<a name="s3-vpc-deny-policies"></a>

If your bucket has a policy that restricts traffic to a specific VPC or VPC endpoint via Deny Policy, you must reverse this policy because deny policies take precedence over allow policies.

For example:

```
{
   "Version":"2012-10-17"		 	 	 ,                   
   "Id": "Policy1415115909152",
   "Statement": [
     {
       "Sid": "Access-to-specific-VPCE-only",
       "Principal": "*",
       "Action": "s3:*",
       "Effect": "Deny",
       "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket",
                    "arn:aws:s3:::amzn-s3-demo-bucket/*"],
       "Condition": {
         "StringNotEquals": {
           "aws:SourceVpce": "vpce-0abcdef1234567890"
         }
       }
     }
   ]
}
```

Should be reversed into:

```
{
   "Version":"2012-10-17"		 	 	 ,                   
   "Id": "Policy1415115909152",
   "Statement": [
     {
       "Sid": "Access-to-specific-VPCE-only",
       "Principal": "*",
       "Action": "s3:*",
       "Effect": "Allow",
       "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket",
                    "arn:aws:s3:::amzn-s3-demo-bucket/*"],
       "Condition": {
         "StringEquals": {
           "aws:SourceVpce": "vpce-0abcdef1234567890"
         }
       }
     }
   ]
}
```

### Best practices
<a name="s3-vpc-best-practices"></a>

**Restrict access to your Amazon Quick role**

Access policies should enforce that the caller is your Amazon Quick role ARN or, at minimum, your Amazon Quick account. This ensures that despite allowing VPC traffic, calls come only from expected sources.

### Security recommendations
<a name="s3-vpc-security-recommendations"></a>
+ Restrict policies to your Amazon Quick role for most secure traffic
+ Review your bucket policies regularly to ensure they follow the principle of least privilege

## Restrict Amazon S3 bucket access with IAM policy assignments
<a name="s3-restrict-bucket-access"></a>

You can control which Amazon S3 buckets your Amazon Quick users can use to create knowledge bases by creating IAM policies and assigning them to specific users, groups, or all users through Amazon Quick IAM policy assignments. This allows you to restrict who can create knowledge bases against specific buckets, including ACL-aware knowledge bases.

**Note**  
IAM policies assigned through Amazon Quick take precedence over AWS resource-level policies. To ensure your access requirements are met, configure your IAM policies appropriately.

For example, you can assign a restrictive policy to specific users who need access to ACL-aware buckets, while assigning a broader policy to all users for non-ACL buckets.

### Step 1: Create an Amazon S3 access policy in IAM
<a name="s3-create-iam-policy"></a>

Create an IAM policy in the AWS IAM console that defines which Amazon S3 buckets users can access for knowledge base creation. The following example policy grants access to two specific buckets:

```
{
    "Version": "2012-10-17"		 	 	 ,
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Action": [
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1",
                "arn:aws:s3:::amzn-s3-demo-bucket-2"
            ]
        },
        {
            "Action": [
                "s3:GetObject",
                "s3:GetObjectVersion"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1/*",
                "arn:aws:s3:::amzn-s3-demo-bucket-2/*"
            ]
        },
        {
            "Action": [
                "s3:ListBucketMultipartUploads",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1",
                "arn:aws:s3:::amzn-s3-demo-bucket-2"
            ]
        },
        {
            "Action": [
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1/*",
                "arn:aws:s3:::amzn-s3-demo-bucket-2/*"
            ]
        }
    ]
}
```

Replace `amzn-s3-demo-bucket-1` and `amzn-s3-demo-bucket-2` with the names of the Amazon S3 buckets you want to grant access to.

### Step 2: Assign the policy in Amazon Quick
<a name="s3-assign-iam-policy"></a>

After creating the IAM policy, assign it to Amazon Quick users or groups.

1. In the Amazon Quick admin console, under **Permissions**, choose **IAM policy assignments**.

1. Choose **Add new assignment**.

1. Enter a name for the assignment.

1. On the **Select an IAM policy** page, search for and select the IAM policy you created in Step 1. Choose **Next**.

1. On the **Assign users and groups** page, choose one of the following:
   + Select **Assign to all users and groups** to apply the policy to all current and future users.
   + Search for and select specific users or groups to assign the policy to.

   Choose **Next**.

1. On the **Review and enable changes** page, verify your assignment details and choose **Save and enable**.

Users who are not explicitly granted access through an IAM policy assignment will not be able to access the restricted Amazon S3 buckets for creating integrations or knowledge bases.

# Document-level ACLs
<a name="s3-acl"></a>

You can enable access control lists (ACLs) at the Amazon S3 knowledge base level using one of two configuration methods, each optimized for different use cases.

**Important**  
Document-level ACL configuration is permanent. You cannot enable ACLs on knowledge bases created without ACL support, and you cannot disable ACLs once enabled. To change ACL configuration, create a new knowledge base with your desired setting from the start.

**Note**  
For ACL-enabled knowledge bases, documents without an associated ACL entry are not ingested. Make sure every document has an ACL defined either through the global ACL file or in its metadata file.

**Global ACL configuration file**  
Create a single centralized file that defines access permissions at the folder level. This provides a streamlined way to manage permissions across large document hierarchies. This method is ideal for organizations with stable permission structures. Any changes to the global file require reindexing the entire affected prefix, which can take hours for knowledge bases with tens of millions of documents. For the file format, see [Global ACL file structure](#s3-global-acl).

**Document-level metadata files**  
Each document has its own metadata file containing specific access control information. This approach requires you to create and maintain individual metadata files for each document. It enables significantly faster index updates when permissions change because only the affected documents need to be reindexed rather than entire folder structures. For more information about configuring ACLs in metadata files, see [Document metadata](s3-metadata.md).

Choose the method that best fits your operational needs: centralized management with the global ACL file for simpler administration, or document-level metadata files for faster permission updates and more granular control.

Keep your document-level ACLs current by regularly updating the Amazon S3 ACL configuration to match your organization's access requirements. For more information about common best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).

## Global ACL file structure
<a name="s3-global-acl"></a>

The global file provides centralized access control management at the folder level. Each entry in the file maps an Amazon S3 key prefix to a set of ACL entries that apply to all documents under that prefix.

The global ACL json file uses the following structure:

```
[
    {
        "keyPrefix": "s3://BUCKETNAME/prefix1/",
        "aclEntries": [
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    },
    {
        "keyPrefix": "s3://BUCKETNAME/prefix1/document_1.txt",
        "aclEntries": [
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    },
    {
        "keyPrefix": "s3://BUCKETNAME/prefix2/",
        "aclEntries": [
            {
                "Name": "user2@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "DENY"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    }
]
```

Each entry in the array contains the following fields:

`keyPrefix`  
The Amazon S3 path prefix that the ACL entries apply to. All documents under this prefix inherit the specified permissions.

`aclEntries`  
An array of access control entries, each containing the following fields:  
+ `Name` – For `USER` type, the email address of the user in Quick. For `GROUP` type, the group name in Quick.
+ `Type` – Either `USER` or `GROUP`.
+ `Access` – Either `ALLOW` or `DENY`.

# Document metadata
<a name="s3-metadata"></a>

You can add metadata to documents in your Amazon S3 bucket to customize chat results and control document-level access. Metadata is additional information about a document, such as its title, creation date, and access permissions.

Amazon Quick supports source attribution with citations. If you specify the `_source_uri` metadata field, the source attribution links in chat results direct users to the configured URL. If you don't specify a `_source_uri`, users can still access source documents through clickable citation links that download the file at query time.

## Document metadata location
<a name="s3-metadata-location"></a>

In Amazon S3, each metadata file can be associated with an indexed document. Your metadata files must be stored in the same Amazon S3 bucket as your indexed files. You can specify a location within the Amazon S3 bucket for your metadata files when configuring your Amazon S3 integration in Amazon Quick.

If you don't specify an Amazon S3 prefix, your metadata files must be stored in the same location as your indexed documents. If you specify an Amazon S3 prefix for your metadata files, they must be in a directory structure parallel to your indexed documents. Amazon Quick looks only in the specified directory for your metadata. If the metadata isn't read, check that the directory location matches the location of your metadata.

The following examples show how the indexed document location maps to the metadata file location. The document's Amazon S3 key is appended to the metadata's Amazon S3 prefix and then suffixed with `.metadata.json` to form the metadata file's Amazon S3 path.

**Note**  
The combined Amazon S3 key, the metadata's Amazon S3 prefix, and the `.metadata.json` suffix must be no more than a total of 1,024 characters. We recommend that your Amazon S3 key is less than 1,000 characters to account for additional characters when combining your key with the prefix and suffix.

**Example 1: No metadata path specified**  

```
Bucket name:
     s3://bucketName
Document path:
     documents
Metadata path:
     none
File mapping
     s3://bucketName/documents/file.txt -> 
        s3://bucketName/documents/file.txt.metadata.json
```

**Example 2: Metadata path specified**  

```
Bucket name:
     s3://bucketName
Document path:
     documents/legal
Metadata path:
     metadata
File mapping
     s3://bucketName/documents/legal/file.txt -> 
        s3://bucketName/metadata/documents/legal/file.txt.metadata.json
```

## Document metadata structure
<a name="s3-metadata-structure"></a>

You define your document metadata itself in a JSON file. The file must be a UTF-8 text file without a BOM marker. The file name of the JSON file must be `<document>.<extension>.metadata.json`. In this example, `document` is the name of the document that the metadata applies to and `extension` is the file extension for the document. The document ID must be unique in `<document>.<extension>.metadata.json`.

The content of the JSON file uses the following template:

```
{
    "DocumentId": "document ID",
    "Attributes": {
        "_authors": ["author of the document"],
        "_category": "document category",
        "_created_at": "ISO 8601 encoded string",
        "_last_updated_at": "ISO 8601 encoded string",
        "_source_uri": "document URI",
        "_version": "file version",
        "_view_count": number of times document has been viewed
    },
    "AccessControlList": [
        {
            "Name": "user1@example.com",
            "Type": "GROUP | USER",
            "Access": "ALLOW | DENY"
        }
    ],
    "Title": "document title",
    "ContentType": "PDF | HTML | MS_WORD | PLAIN_TEXT | PPT | RTF | XML | XSLT | MS_EXCEL | CSV | JSON | MD"
}
```

If you provide a metadata path, make sure that directory structure inside the metadata directory exactly matches the directory structure of data file.

For example, if the data file location is at `s3://bucketName/documents/legal/file.txt`, the metadata file location should be at `s3://bucketName/metadata/documents/legal/file.txt.metadata.json`.

All of the attributes and fields are optional, so it's not necessary to include all attributes. However, you must provide a value for each attribute that you want to include; the value can't be empty.

The `_created_at` and `_last_updated_at` metadata fields are ISO 8601 encoded dates. For example, 2012-03-25T12:30:10\$101:00 is the ISO 8601 date-time format for March 25, 2012, at 12:30PM (plus 10 seconds) in the Central European Time time zone.

The `AccessControlList` field is an optional array that defines document-level access control. Each entry in the array contains the following fields:
+ `Name` – For `USER` type, the email address of the user in Quick. For `GROUP` type, the group name in Quick.
+ `Type` – Either `USER` or `GROUP`.
+ `Access` – Either `ALLOW` or `DENY`.

**Note**  
To use the `AccessControlList` field, you must enable document-level ACLs when creating the knowledge base. For more information, see [Document-level ACLs](s3-acl.md).

# Set up and manage Amazon S3 integration
<a name="s3-setup-manage"></a>

## Set up Amazon S3 integration
<a name="s3-integration-setup"></a>

After your administrator has completed the setup tasks, follow these steps to create your Amazon S3 knowledge base.

1. In the Amazon Quick console, choose **Integrations**.

1. Under **Amazon S3**, choose **Add** (the plus **\$1** button).

1. On the **Connect S3 bucket** page, choose your data source:
   + To reuse an existing Amazon S3 data source, select it from the dropdown. Then choose **Next** to skip to the knowledge base details step.
   + To connect a new Amazon S3 bucket, choose **\$1 Add account** from the dropdown.

1. If you are connecting a new bucket, fill in the connection details:
   + **Name** – A descriptive name for your Amazon S3 integration.
   + **S3 bucket location** – Choose **Quick Suite instance account** to access Amazon S3 buckets in the same AWS account where Amazon Quick is enabled, or choose **Other AWS account** to access buckets in a different account.
   + **S3 bucket URL** – The Amazon S3 bucket path containing your documents. Your Amazon S3 bucket must be in the same region as your Amazon Quick region.

   Choose **Next**. The system validates your configuration. If errors occur, review the error message for specific remediation steps.
**Note**  
If you receive an access error, contact your administrator to verify that your user has the required permissions for the Amazon S3 bucket.

1. On the **Create knowledge base** page, complete the following:
   + **Name** – Enter a descriptive name for your knowledge base.
   + **Description** – Describe the purpose of this knowledge base (optional).
   + **Content** – Choose **Add all content** to sync everything from the bucket, or choose **Add specific content** to specify S3 prefixes for the folders and files you want to include. Filters are case-sensitive.

1. Choose **Next: Additional settings** to configure ACL and metadata options, or choose **Create** to create the knowledge base with default settings.

1. On the **Additional settings** page, configure ACL management and metadata:
**Important**  
The decision to enable or disable ACLs must be made during knowledge base creation. You cannot change this option after this step. For more information about ACLs, see [Document-level ACLs](s3-acl.md).
   + To enable document-level ACLs, select **Control document access with ACLs**. When enabled, the following options appear:
     + **Global ACL file location** – Enter the Amazon S3 path to your global ACL file (e.g. acl.json) if you are using a global ACL configuration file for centralized access control management at the folder level.
     + **Metadata files folder location** – Enter the Amazon S3 path to your metadata folder if you are using document-level metadata files that include ACL entries.
     + If your metadata files use the sidecar method (stored in the same folder as the original documents), you can leave both fields blank.
   + You can optionally specify a **Metadata files folder location** even without ACLs enabled.

1. Choose **Create**.

After you choose create, the data sync starts automatically.

## Manage knowledge bases
<a name="s3-integration-knowledge-base"></a>

After setting up your Amazon S3 integration, you can create and manage knowledge bases from your Amazon S3 content.

### Edit existing knowledge bases
<a name="s3-edit-knowledge-base"></a>

You can modify your existing Amazon S3 knowledge bases:

1. In the Amazon Quick console, choose **Knowledge bases**.

1. Select your Amazon S3 knowledge base from the list.

1. Choose the three-dot icon under **Actions**, then choose **Edit knowledge base**.

1. Update your configuration settings as needed and choose **Save**.

### Create additional knowledge bases
<a name="s3-create-additional-knowledge-base"></a>

You can create multiple knowledge bases from the same Amazon S3 integration:

1. In the Amazon Quick console, choose **Integrations**, and then select the **Data** tab.

1. Choose your existing Amazon S3 integration from the list.

1. Choose the three-dot icon under **Actions**, then choose **Create knowledge base**.

1. Configure your knowledge base settings and choose **Create**.

For detailed information about knowledge base configuration options, see [Common configuration settings](knowledge-base-integrations.md#common-configuration-settings).

**Note**  
When you create a knowledge base in Amazon Quick, by default only you can get insights from the knowledge base. For shared content, you can provide access to different users and groups by updating the knowledge base permissions. To control document-level access within a knowledge base, see [Document-level ACLs](s3-acl.md).

# Troubleshooting Amazon S3 integration issues
<a name="s3-integration-troubleshooting"></a>

If you encounter issues connecting to your Amazon S3 bucket, review the following common causes and solutions.

## Documents not appearing in ACL-enabled knowledge base
<a name="s3-troubleshooting-acl-documents-missing"></a>

**Issue:** Documents are not ingested into an ACL-enabled knowledge base.

**Solution:** For ACL-enabled knowledge bases, documents without an associated ACL entry are not ingested. Verify that every document has an ACL defined either through the global ACL file or in its metadata file. For more information, see [Document-level ACLs](s3-acl.md).

## Cross-account access not configured
<a name="s3-troubleshooting-cross-account"></a>

**Issue:** Your administrator hasn't granted access to use Amazon S3 buckets from other AWS accounts in Amazon Quick.

**Solution:** Ask your administrator to grant cross-account Amazon S3 access. For more information, see [Grant Amazon Quick access to Amazon S3 buckets](s3-admin-setup.md#s3-grant-bucket-access).

## Bucket not in approved list
<a name="s3-troubleshooting-bucket-not-approved"></a>

**Issue:** The bucket you're trying to access hasn't been authorized by your administrator.

**Solution:**
+ Confirm the bucket name is spelled correctly.
+ Verify with your administrator that the bucket is included in the approved list.
+ Request your administrator to add the bucket to the authorized buckets list if needed.

## Insufficient IAM permissions
<a name="s3-troubleshooting-iam-permissions"></a>

**Issue:** Your IAM role or user lacks the necessary permissions to access the Amazon S3 bucket.

**Solution:**
+ Verify your IAM policy includes the required Amazon S3 permissions:
  + `s3:GetObject`
  + `s3:ListBucket`
  + `s3:GetBucketLocation`
  + `s3:GetObjectVersion`
  + `s3:ListBucketVersions`
+ Check your own buckets for any explicit Deny statements that might be blocking access.

**Note**  
The ARN `arn:aws:iam::account-id:role/service-role/aws-quicksight-service-role-v0` is the default service role used when no custom role has been created. If a custom service role exists, contact your administrator to obtain the custom service role ARN and use it instead of the default.

## Cross-region restrictions
<a name="s3-troubleshooting-cross-region"></a>

**Issue:** The Amazon S3 bucket is located in a different AWS region than your Amazon Quick account or service.

**Solution:**
+ Verify the bucket region matches your Amazon Quick service region.
+ Check bucket region using AWS CLI: `aws s3api get-bucket-location --bucket bucket-name`
+ Use a bucket in the same region as your service.

## Additional troubleshooting steps
<a name="s3-troubleshooting-additional-steps"></a>
+ **Test bucket accessibility** using AWS CLI:

  ```
  aws s3 ls s3://bucket-name --profile your-profile
  ```
+ **Review CloudTrail logs** for AccessDenied errors to identify the specific permission issue.
+ **Check Amazon S3 Block Public Access settings** - while these typically don't affect authenticated access, verify they're not interfering with your specific use case.
+ **Verify bucket ownership** - ensure the bucket exists and you have the correct bucket name.

# Limitations
<a name="s3-limitations"></a>

When using Amazon S3 integrations in Amazon Quick, be aware of the following limitations:
+ The Amazon S3 bucket must be in the same AWS Region as your Amazon Quick application.
+ Each document can have a maximum of 2,500 individual user or group ACL entries.
+ Global ACL configuration file maximum size: 100 MB.
+ Document metadata file maximum size: 5 MB.

For more information about document-level ACL limitations, see [Limitations](acl-best-practices-kb.md#acl-limitations).

# Asana integration
<a name="asana-integration"></a>

Connect Amazon Quick to your Asana workspace to manage projects, tasks, and team collaboration. You can create, update, and manage Asana content without leaving your Amazon Quick environment. This integration requires Amazon Quick Pro tier or higher.

## What you can do
<a name="asana-integration-capabilities"></a>

With Asana integration, you can perform actions within your Asana workspaces through the Asana API.

**Action connector**  
Create, update, and manage projects, tasks, and team assignments through the Asana API.

## Set up Asana integration
<a name="asana-integration-setup"></a>

Follow these steps to connect Amazon Quick to your Asana workspace.

1. In the Amazon Quick console, choose **Integrations**.

1. Click **Add** (plus "\$1" button).

1. Fill in the following details:
   + **Name** - Enter a descriptive name for your Asana integration.
   + **Description** - Describe the purpose of this integration.

1. Choose the connection type and configure the network type settings.

1. Configure the authentication settings based on your chosen authentication method.

1. Select **Create and continue**.

1. Add users to share the integration with.

1. Click **Next**.

## Configure authentication
<a name="asana-integration-authentication"></a>

Asana integration uses custom user-based OAuth authentication. Configure the following authentication fields:
+ **Base URL** - Asana API base URL.
+ **Client ID** - Your Asana OAuth app client ID.
+ **Client Secret** - Your Asana OAuth app client secret.
+ **Authorization URL** - Asana OAuth authorization endpoint.
+ **Redirect URL** - OAuth redirect URI for your application.

### Required OAuth scopes
<a name="asana-oauth-scopes"></a>

When you create your Asana OAuth application, configure these scopes:
+ `tasks:write` - Create and modify tasks.
+ `tasks:read` - Read task information.
+ `workspaces:read` - Access workspace information.
+ `workspaces.typeahead:read` - Search within workspaces.
+ `stories:read` - Read task stories and comments.
+ `users:read` - Access user information.
+ `projects:read` - Read project information.
+ `project_templates:read` - Access project templates.

## Manage Asana integrations
<a name="asana-integration-management"></a>

You can perform these management tasks for your Asana integrations:
+ **Edit integration settings** - Update authentication settings or Asana configuration.
+ **Share integration access** - Make the integration available to other users.
+ **Delete integration** - Remove the integration and revoke authentication.

# Atlassian Confluence Cloud integration
<a name="confluence-integration"></a>

Use the Atlassian Confluence Cloud integration to perform actions on Confluence content, or to create knowledge bases from Confluence spaces, pages, and blog posts for AI-powered search and Q&A.

## Integration capabilities
<a name="confluence-integration-capabilities"></a>

**Action connector**  
Create and update Confluence pages, and search Confluence content through Atlassian API calls.

**Knowledge base**  
Index Confluence pages, blog posts, and space content. Amazon Quick agents can then search and answer questions about the content.

# Atlassian Confluence Cloud action integration
<a name="confluence-action-integration"></a>

Use the Atlassian Confluence Cloud action connector to create, update, and manage Confluence pages and spaces directly in Amazon Quick through natural language.

To set up this integration, you first create an OAuth 2.0 (3LO) app in the Atlassian Developer Console and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Atlassian app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="confluence-action-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ Atlassian Confluence Cloud.
+ Access to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) to create or manage an OAuth app.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure the Atlassian Developer Console
<a name="confluence-action-atlassian-setup"></a>

If you plan to use user authentication (3LO), create an OAuth 2.0 app in the Atlassian Developer Console before you configure Amazon Quick. Complete all of the following steps before moving to the Amazon Quick console.

If you plan to use service authentication (API Key) only, you can skip this section and proceed to [Prepare authentication](#confluence-action-auth-setup).

For more information about OAuth 2.0 (3LO) apps, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) in the Atlassian developer documentation.

### Create an OAuth 2.0 (3LO) app
<a name="atlassian-oauth-app"></a>

Amazon Quick uses an Atlassian OAuth 2.0 (3LO) app to authenticate with your Atlassian Cloud product on behalf of your users. Create this app in the Atlassian Developer Console before you configure Amazon Quick.

1. Open the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and sign in with your Atlassian account.

1. Choose **Create**, then choose **OAuth 2.0 integration**.

1. For **Name**, enter a descriptive name for your integration, for example `your-app-name connector`.

1. Review and accept the Atlassian developer terms.

1. Choose **Create**.

### Configure permissions
<a name="atlassian-oauth-permissions"></a>

After you create the OAuth 2.0 app, add the API permissions that Amazon Quick needs to interact with your Atlassian product.

1. From your app in the Atlassian Developer Console, choose **Permissions** in the left navigation.

1. Find the API for your Atlassian product (for example, **Jira API** or **Confluence API**) and choose **Add**. The button changes to **Configure** after the API is added.

1. Choose **Configure**. The scopes page opens with **Classic scopes** and **Granular scopes** tabs.

1. On the **Classic scopes** tab, choose **Edit Scopes**. Select the required classic scopes and choose **Save**.

1. Choose the **Granular scopes** tab, then choose **Edit Scopes**. Select the required granular scopes and choose **Save**.

For the specific scopes required for your integration, see the scopes section that follows.

### Required scopes for Confluence
<a name="confluence-action-oauth-scopes"></a>

Add the following scopes to your OAuth 2.0 app for the Confluence Cloud action integration.

**Classic scope**

On the **Classic scopes** tab, choose **Edit Scopes** and select the following scope.


**Confluence action integration – classic scope**  

| Scope | Description | 
| --- | --- | 
| search:confluence | Search Confluence content and space summaries. | 

**Granular scopes**

Choose the **Granular scopes** tab, then choose **Edit Scopes**. Select the following scopes.


**Confluence action integration – granular scopes**  

| Scope | Description | 
| --- | --- | 
| read:page:confluence | View page content. | 
| write:page:confluence | Create and update pages. | 
| read:space:confluence | Access space information. | 

### Configure authorization
<a name="atlassian-oauth-authorization"></a>

Set the callback URL so that Atlassian can redirect users back to Amazon Quick after they authorize the app.

1. From your app in the Atlassian Developer Console, choose **Authorization** in the left navigation.

1. Next to **OAuth 2.0 (3LO)**, choose **Add**.

1. For **Callback URLs**, enter `https://region.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *region* with the AWS Region where your Amazon Quick instance is deployed, for example `us-east-1`.

1. Choose **Save changes**.

### Record your credentials
<a name="atlassian-oauth-credentials"></a>

Before you leave the Atlassian Developer Console, confirm that you have the following values. You need them for the Amazon Quick configuration.

1. From your app in the Atlassian Developer Console, choose **Settings** in the left navigation.

1. Under **Authentication details**, copy the **Client ID** and **Secret** values.


**Required credentials from Atlassian Developer Console**  

| Value | Where to find it | 
| --- | --- | 
| Client ID | Settings page, under Authentication details | 
| Secret | Settings page, under Authentication details | 

## Prepare authentication
<a name="confluence-action-auth-setup"></a>

Confluence Cloud action connectors support two authentication methods. Gather the required credentials before configuring Amazon Quick.

**User authentication (3LO)**  
If you completed the Atlassian Developer Console setup in the previous section, you should have the following values ready. Enter these when you configure the integration in Amazon Quick.  
+ **Base URL** – Your Confluence instance URL for API calls. This is not the same URL that users log into. It resembles the following: `https://api.atlassian.com/ex/confluence/yourInstanceId`. To find your instance ID, navigate to `https://your-domain.atlassian.net/_edge/tenant_info`.
+ **Client ID** – From the Settings page of your Atlassian OAuth app.
+ **Client secret** – From the Settings page of your Atlassian OAuth app.
+ **Token URL** – `https://auth.atlassian.com/oauth/token`
+ **Authorization URL** – `https://auth.atlassian.com/authorize`
+ **Redirect URL** – `https://region.quicksight.aws.amazon.com/sn/oauthcallback`

**Service authentication (API Key)**  
Gather the following information from your Confluence Cloud administrator:  
+ **API Key** – Confluence API token.
+ **Base URL** – Your Confluence instance URL for API calls.
+ **Email** – Associated user account email.

## Set up the integration in Amazon Quick
<a name="confluence-action-integration-setup"></a>

After you prepare your authentication credentials, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. Under **Set up a new app integration for Actions**, find **Atlassian Confluence Cloud** and choose the Add (plus "\$1") button.

1. On the **Integration type** page, select **Perform actions in Atlassian Confluence Cloud** and choose **Next**.

1. In the **Create integration** form, fill in the following fields:
   + **Name** – Descriptive name for your Confluence integration.
   + **Description** (Optional) – Notes about how this connection will be used.
   + **Connection type** – Choose **Public network**.

1. Under **Authentication settings**, choose your authentication method and fill in the required fields:

   1. For **User authentication**, configure the following fields:
      + **Base URL** – Your Confluence instance URL for API calls, in the format `https://api.atlassian.com/ex/confluence/yourInstanceId`. To find your instance ID, navigate to `https://your-domain.atlassian.net/_edge/tenant_info`.
      + **Client ID** – Client ID from the Settings page of your Atlassian OAuth app.
      + **Client secret** – Secret from the Settings page of your Atlassian OAuth app.
      + **Token URL** – `https://auth.atlassian.com/oauth/token`
      + **Authorization URL** – `https://auth.atlassian.com/authorize`
      + **Redirect URL** – This field is pre-populated with your Amazon Quick callback URL.

   1. For **Service authentication**, configure the following fields:
      + **API Key** – Confluence API token.
      + **Base URL** – Your Confluence instance URL for API calls.
      + **Email** – Associated user account email.

1. Choose **Create and continue**.

1. (Optional) On the **Share integration** page, choose users to share the integration with.

## Available actions
<a name="confluence-action-available-actions"></a>

After you set up the integration, the following actions are available.


**Confluence Cloud available actions**  

| Action | Description | 
| --- | --- | 
| Create Page | Create a new page. | 
| Get Pages | View all pages. | 
| Search | Search content using CQL. | 
| Update Page | Update page content. | 

## Manage and troubleshoot
<a name="confluence-action-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="confluence-action-troubleshooting-auth"></a>
+ **Incorrect app configuration** – Verify the OAuth app in the Atlassian Developer Console includes the required scopes and that the redirect URI matches your Amazon Quick configuration.
+ **Expired API token** – If using service authentication, check that the API token has not expired and generate a new one if needed.
+ **Incorrect Base URL** – The Base URL for API calls is not the same as the Confluence Cloud login URL. Verify you are using the API URL format: `https://api.atlassian.com/ex/confluence/yourInstanceId`. To find your instance ID, navigate to `https://your-domain.atlassian.net/_edge/tenant_info`.

### Common error messages
<a name="confluence-action-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions in Confluence Cloud. Contact your Confluence Cloud administrator to verify and grant appropriate permissions.
+ **`OAuth 2.0 authorization failed`** – Verify the client ID, client secret, and OAuth scopes are configured correctly in both the Atlassian Developer Console and Amazon Quick.

# Atlassian Confluence Cloud knowledge base integration
<a name="confluence-knowledge-base"></a>

Use the Atlassian Confluence Cloud knowledge base integration to index Confluence content so that Amazon Quick agents can search and answer questions about it.

## Before you begin
<a name="confluence-kb-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ Atlassian Confluence Cloud.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Authentication
<a name="confluence-kb-auth-setup"></a>

For knowledge base integrations, Amazon Quick handles authentication through a popup flow during setup. Complete the following steps.

1. Complete the Confluence Cloud authentication popup that appears.

1. Grant permissions for Amazon Quick to access your Confluence content.

1. Review and complete the authentication process.

## Set up the knowledge base integration
<a name="confluence-kb-setup"></a>

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Atlassian Confluence Cloud** and choose the Add (plus "\$1") button.

1. In the **Create Confluence knowledge base** dialog, under **Connected account**, complete the following fields:
   + **Name** – A descriptive name for your data access integration.
   + **Confluence URL** – The URL of your Atlassian site (for example, `your-site.atlassian.net`).

1. Choose **Sign in** and complete the Confluence Cloud authentication flow in the popup window.

1. Under **Create knowledge base**, complete the following fields:
   + **Name** – A name for your knowledge base.
   + **Description** (Optional) – Notes about how the knowledge base will be used.

1. Under **Content**, paste the URLs of the Confluence spaces, blogs, or pages that you want to include. Choose **Add** after each URL.
**Note**  
URLs that follow the structure `https://company.atlassian.net/wiki/spaces/space-key/overview` are treated as page URLs.

1. Choose **Create**.

## Supported content types
<a name="confluence-kb-content-types"></a>
+ Confluence pages and blog posts
+ Spaces content
+ Page and blog attachments

## Access controls
<a name="confluence-kb-access-controls"></a>

**Important**  
Amazon Quick doesn't sync access control lists (ACLs) from data sources. When you create a knowledge base in Amazon Quick, by default, only you can get insights from the knowledge base. For shared content, you can provide access to different users and groups by updating the knowledge base permissions.

## Manage knowledge bases
<a name="confluence-kb-management"></a>

### Edit existing knowledge bases
<a name="confluence-kb-edit"></a>

1. In the Amazon Quick console, choose **Knowledge bases**.

1. Select your Confluence Cloud knowledge base from the list.

1. Choose the three-dot icon under **Actions**, then choose **Edit knowledge base**.

1. Update your configuration settings as needed and choose **Save**.

## Troubleshoot
<a name="confluence-kb-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

For general knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).

### Blocked OAuth app authorization
<a name="confluence-kb-troubleshooting-blocked-oauth"></a>

**Symptoms:**
+ Error message: "Your site admin must authorize this app for the site *instance-name*.atlassian.net before the app can access your account."
+ Clicking **Accept** in the consent dialog has no effect.

**Cause:**

Your Atlassian site administrator has blocked user-installed OAuth apps. When this setting is enabled, only a site or organization administrator can authorize new third-party apps.

**Resolution steps:**

Use one of the following options to resolve this issue.
+ **Option 1 (Recommended): Admin authorizes the app directly**

  1. An Atlassian site administrator navigates to Amazon Quick and starts a new knowledge base setup with Confluence Cloud.

  1. Because the administrator has site-level permissions, a clean consent screen appears without the error.

  1. The administrator chooses **Accept** to install the app.

  After the administrator authorizes the app, all other users on the site can connect without issues.
+ **Option 2: Temporarily allow user-installed apps** – An administrator goes to `admin.atlassian.com`, navigates to **Apps**, **Atlassian Apps**, then chooses the link for third-party and Marketplace apps. Under **Settings**, find **User Installed Apps** and toggle to allow user apps. After the user authorizes Amazon Quick, toggle the setting back to block user apps.

**Important**  
Admin authorization applies per Atlassian site, not per organization. If your company has multiple sites (for example, `team-a.atlassian.net` and `team-b.atlassian.net`), each site requires separate authorization.

**Note**  
While user-installed apps are unblocked (Option 2), any user on the site can authorize any OAuth app. Re-enable the block promptly after the user has connected.

### Authentication popup fails
<a name="confluence-kb-troubleshooting-auth-popup"></a>

**Symptoms:**
+ Authentication popup does not appear or closes immediately.
+ Popup appears but fails to complete the OAuth flow.

**Resolution steps:**

1. Verify that your browser allows popups from the Amazon Quick console domain.

1. Verify that your Confluence Cloud instance is accessible from your network.

1. Try using a different browser or clearing your browser cache.

### Missing content in knowledge base
<a name="confluence-kb-troubleshooting-missing-content"></a>

**Symptoms:**
+ Knowledge base sync completes but expected content is not indexed.
+ Search results do not include content from specific spaces or pages.
+ Only one document is indexed for an entire space.

**Resolution steps:**

1. Verify that the Confluence Cloud user who authenticated has access to the spaces and pages you selected during setup.

1. Check that the selected content types are supported (pages, blog posts, and attachments).

1. Review the content selection in your knowledge base configuration to confirm the correct spaces and pages are included.

1. Check your Confluence URLs for the `/overview` suffix. URLs that end with `/wiki/spaces/space-key/overview` are treated as a single page URL, not a full space. If you intended to index the entire space, use the space URL without `/overview` (for example, `https://company.atlassian.net/wiki/spaces/space-key`).

# Atlassian Jira Cloud integration
<a name="jira-integration"></a>

Use the Atlassian Jira Cloud action connector to create, update, search, and manage Jira issues, projects, sprints, and users directly in Amazon Quick through natural language.

Setting up this integration involves two steps. First, you create an OAuth 2.0 (3LO) app in the Atlassian Developer Console and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Atlassian app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="jira-integration-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ Atlassian Jira Cloud.
+ Access to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) to create or manage an OAuth app.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure the Atlassian Developer Console
<a name="jira-atlassian-setup"></a>

If you plan to use user authentication (3LO), create an OAuth 2.0 app in the Atlassian Developer Console before you configure Amazon Quick. Complete all of the following steps before moving to the Amazon Quick console.

If you plan to use service authentication (API Key) only, you can skip this section and proceed to [Set up the integration in Amazon Quick](#jira-integration-setup).

For more information about OAuth 2.0 (3LO) apps, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) in the Atlassian developer documentation.

### Create an OAuth 2.0 (3LO) app
<a name="atlassian-oauth-app"></a>

Amazon Quick uses an Atlassian OAuth 2.0 (3LO) app to authenticate with your Atlassian Cloud product on behalf of your users. Create this app in the Atlassian Developer Console before you configure Amazon Quick.

1. Open the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and sign in with your Atlassian account.

1. Choose **Create**, then choose **OAuth 2.0 integration**.

1. For **Name**, enter a descriptive name for your integration, for example `your-app-name connector`.

1. Review and accept the Atlassian developer terms.

1. Choose **Create**.

### Configure permissions
<a name="atlassian-oauth-permissions"></a>

After you create the OAuth 2.0 app, add the API permissions that Amazon Quick needs to interact with your Atlassian product.

1. From your app in the Atlassian Developer Console, choose **Permissions** in the left navigation.

1. Find the API for your Atlassian product (for example, **Jira API** or **Confluence API**) and choose **Add**. The button changes to **Configure** after the API is added.

1. Choose **Configure**. The scopes page opens with **Classic scopes** and **Granular scopes** tabs.

1. On the **Classic scopes** tab, choose **Edit Scopes**. Select the required classic scopes and choose **Save**.

1. Choose the **Granular scopes** tab, then choose **Edit Scopes**. Select the required granular scopes and choose **Save**.

For the specific scopes required for your integration, see the scopes section that follows.

### Configure API permissions
<a name="jira-oauth-scopes"></a>

Add the following scopes to your OAuth 2.0 app for the Jira Cloud action integration.

**Classic scopes**

On the **Classic scopes** tab, choose **Edit Scopes** and select the following scopes.


**Jira action integration – classic scopes**  

| Scope | Description | 
| --- | --- | 
| read:jira-work | Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs. | 
| manage:jira-project | Create and edit project settings and create new project-level objects (for example, versions and components). | 
| manage:jira-configuration | Take Jira administration actions (for example, create projects and custom fields, view workflows, manage issue link types). | 
| read:jira-user | View user information in Jira that the user has access to, including usernames, email addresses, and avatars. | 
| write:jira-work | Create and edit issues in Jira, post comments as the user, create worklogs, and delete issues. | 
| manage:jira-webhook | Fetch, register, refresh, and delete dynamically declared Jira webhooks. | 

**Granular scopes**

Choose the **Granular scopes** tab, then choose **Edit Scopes**. Use the search bar to find the scopes below. For example, search for `sprint:jira-software` to find sprint-related scopes.


**Jira action integration – granular scopes**  

| Scope | Description | 
| --- | --- | 
| read:board-scope:jira-software | Read board configurations. | 
| read:sprint:jira-software | Read sprint information. | 
| write:sprint:jira-software | Create and modify sprints. | 
| delete:sprint:jira-software | Delete sprints. | 
| write:board-scope:jira-software | Manage board configurations. | 
| read:project:jira | Read project details. | 

### Configure authorization
<a name="atlassian-oauth-authorization"></a>

Set the callback URL so that Atlassian can redirect users back to Amazon Quick after they authorize the app.

1. From your app in the Atlassian Developer Console, choose **Authorization** in the left navigation.

1. Next to **OAuth 2.0 (3LO)**, choose **Add**.

1. For **Callback URLs**, enter `https://region.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *region* with the AWS Region where your Amazon Quick instance is deployed, for example `us-east-1`.

1. Choose **Save changes**.

### Record your credentials
<a name="atlassian-oauth-credentials"></a>

Before you leave the Atlassian Developer Console, confirm that you have the following values. You need them for the Amazon Quick configuration.

1. From your app in the Atlassian Developer Console, choose **Settings** in the left navigation.

1. Under **Authentication details**, copy the **Client ID** and **Secret** values.


**Required credentials from Atlassian Developer Console**  

| Value | Where to find it | 
| --- | --- | 
| Client ID | Settings page, under Authentication details | 
| Secret | Settings page, under Authentication details | 

## Set up the integration in Amazon Quick
<a name="jira-integration-setup"></a>

After you prepare your authentication credentials, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. Under **Set up a new app integration for Actions**, find **Atlassian Jira Cloud** and choose the Add (plus "\$1") button.

1. In the **Create integration** wizard, fill in the following fields:
   + **Name** – Descriptive name for your Jira integration.
   + **Description** (Optional) – Notes about how this connection will be used.
   + **Connection type** – Choose **Public network**.

1. Under **Authentication settings**, choose your authentication method and fill in the required fields:

   1. For **User authentication**, configure the following fields:
      + **Base URL** – Your Jira instance URL for API calls. This is not the same URL that users log into. It resembles the following: `https://api.atlassian.com/ex/jira/yourInstanceId`. To find your instance ID, navigate to `https://your-domain.atlassian.net/_edge/tenant_info`.
      + **Client ID** – Client ID from the Settings page of your Atlassian OAuth app.
      + **Client secret** – Secret from the Settings page of your Atlassian OAuth app.
      + **Token URL** – `https://auth.atlassian.com/oauth/token`
      + **Authorization URL** – `https://auth.atlassian.com/authorize`
      + **Redirect URL** – This field is pre-populated with your Amazon Quick callback URL.

   1. For **Service authentication**, configure the following fields:
      + **API Key** – Jira API token.
      + **Base URL** – Your Jira instance URL for API calls.
      + **Email** – Associated user account email.

1. Choose **Create and continue**.

1. (Optional) On the **Share integration** page, choose users to share the integration with.

**Important**  
Jira Cloud may return HTTP 200 success responses even when API tokens are revoked or improperly configured. For more information, see [JRACLOUD-82932](https://jira.atlassian.com/browse/JRACLOUD-82932). If your integration appears to connect successfully but actions fail unexpectedly, verify that your API token is valid and has not been revoked.

## Available actions
<a name="jira-integration-actions"></a>

After you set up the integration, the following actions are available.


**Jira Cloud available actions**  

| Action | Description | 
| --- | --- | 
| Add Attachment | Add an attachment to an issue. | 
| Add Comment | Add new comment. | 
| Change Issue Status | Change task status of an issue. | 
| Create Issue | Create new issue or subtask. | 
| Create Project | Create new project. | 
| Create Sprint | Create a sprint in a project. | 
| Delete Comment | Remove comment. | 
| Delete Issue | Delete an issue in a project. | 
| Delete Project | Remove project. | 
| Delete Sprint | Delete a sprint in a project. | 
| Edit Issue | Modify issue. | 
| Find Users | Search for a Jira user. | 
| Get All Labels | View all labels. | 
| Get All Users | List all Jira users. | 
| Get Attachment Content | View the contents of an attachment. | 
| Get Comments | View issue comments. | 
| Get Issue | View details of an issue in a project. | 
| Get Issue Types For Project | View project issue types. | 
| Get Priorities | View issue priorities. | 
| Get Project | View project details. | 
| Get Sprint | View details of a sprint in a project. | 
| Move Issues to Backlog | Move issues to backlog. | 
| Move Issues To Sprint And Rank | Assign an issue to a sprint. | 
| Search Issues | Search for issues. | 
| Search Projects | Find visible projects. | 
| Search Statuses | Search issue statuses. | 
| Update Comment | Edit comment. | 
| Update Project | Modify project. | 
| Update Sprint | Update sprint details. | 

**Note**  
The actions you can use depend on the permissions configured in your Jira Cloud instance and your authentication method.

## Manage and troubleshoot
<a name="jira-integration-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="jira-troubleshooting-auth"></a>
+ **Incorrect app configuration** – Verify the OAuth app in the Atlassian Developer Console includes the required scopes and that the redirect URI matches your Amazon Quick configuration.
+ **Expired or revoked API token** – If using service authentication, check that the API token has not expired or been revoked. Due to a known Jira Cloud behavior ([JRACLOUD-82932](https://jira.atlassian.com/browse/JRACLOUD-82932)), the integration may appear to connect successfully even with invalid tokens.
+ **Incorrect Base URL** – The Base URL for API calls is not the same as the Jira Cloud login URL. Verify you are using the API URL format: `https://api.atlassian.com/ex/jira/yourInstanceId`. To find your instance ID, navigate to `https://your-domain.atlassian.net/_edge/tenant_info`.

### Common error messages
<a name="jira-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions in Jira Cloud. Contact your Jira Cloud administrator to verify and grant appropriate permissions.
+ **`OAuth 2.0 authorization failed`** – Verify the client ID, client secret, and OAuth scopes are configured correctly in both the Atlassian Developer Console and Amazon Quick.

# BambooHR integration
<a name="bamboohr-integration"></a>

Connect Amazon Quick to your BambooHR system to manage employee data, time-off requests, and HR processes. You can create, update, and manage HR content without leaving your Amazon Quick environment. This integration requires Amazon Quick Pro tier or higher.

## What you can do
<a name="bamboohr-integration-capabilities"></a>

With BambooHR integration, you can perform actions within your BambooHR systems through the BambooHR API.

**Action connector**  
Create, update, and manage employee records, time-off requests, and other HR processes through the BambooHR API.

## Set up BambooHR integration
<a name="bamboohr-integration-setup"></a>

Follow these steps to connect Amazon Quick to your BambooHR system.

1. In the Amazon Quick console, choose **Integrations**.

1. Click **Add** (plus "\$1" button).

1. Complete the integration details:
   + **Name** - Enter a descriptive name for your BambooHR integration.
   + **Description** (Optional) - Describe the purpose of this integration.

1. Choose connection type (user or service authentication).

1. Complete the connection settings based on authentication method:
   + **For User authentication (OAuth):**
     + **Base URL** - Your BambooHR instance URL.
     + **Client ID** - OAuth client identifier.
     + **Client Secret** - OAuth client secret.
     + **Token URL** - OAuth token endpoint.
     + **Auth URL** - OAuth authorization endpoint.
     + **Redirect URL** - OAuth callback URL.

     **Required OAuth scopes**: When you create your BambooHR OAuth application, configure the scopes you need for your use case. Common scopes include:
     + `employee` - Access employee information.
     + `employee.write` - Write employee information.
     + `time_off` - Access time off information.
     + `time_off.write` - Write time off information.
     + `company:info` - Access company information.
     + `payroll` - Access payroll data.
**Note**  
Additional scopes may be required depending on the specific BambooHR actions you plan to use. Consult your BambooHR administrator for the complete list of available scopes.
   + **For Service authentication (API Key):**
     + **Base URL** - Your BambooHR instance URL.
     + **API Key** - Your BambooHR API key.
     + **Email** - Email address associated with the API key.

1. Select **Create and continue**.

1. Select users to share the integration with.

1. Click **Next**.

## Manage BambooHR integration
<a name="bamboohr-integration-management"></a>

You can perform these management tasks for your BambooHR integration:

### Edit integration settings
<a name="bamboohr-integration-editing"></a>

To modify your BambooHR integration settings:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **BambooHR** from the integration grid.

1. Select your integration from the list and choose **Edit**.

1. Modify your integration settings as needed.

1. Choose **Save changes**.

### Share integration
<a name="bamboohr-integration-sharing"></a>

You can share your BambooHR action connector with other users in your organization.

1. From the BambooHR integration details page, choose **Share**.

1. Configure your sharing options and permission levels.

1. Choose **Share integration**.

### Delete integration
<a name="bamboohr-integration-deletion"></a>

To permanently remove your BambooHR integration:

1. From the BambooHR integration details page, choose **Delete**.

1. Review the deletion impact, including any workflows or automations using this integration.

1. Type the integration name to confirm deletion.

1. Choose **Delete integration**.

## What happens next
<a name="bamboohr-integration-setup-results"></a>

After you complete the setup, your BambooHR integration appears in the integrations list. You can use it in Amazon Quick workflows, automations, and AI agents to perform HR-related tasks.

## Troubleshoot BambooHR integration
<a name="bamboohr-integration-troubleshooting"></a>

If you encounter issues with your BambooHR integration, try these solutions:

Authentication failures  
Verify that your BambooHR credentials are correct and that the API key or OAuth application has the necessary permissions.

Connection timeouts  
Check that your BambooHR instance URL is correct and accessible from Amazon Quick.

Permission errors  
Ensure that the authenticated user or API key has the required permissions to perform the requested HR operations in BambooHR.

Action execution failures  
Review the action parameters and ensure they match the expected format for BambooHR API calls.

# Box integration
<a name="box-integration"></a>

With Box integration in Amazon Quick, you can manage files, folders, and collaborate on documents directly from your Amazon Quick environment through Model Context Protocol (MCP) server connectivity.

## What you can do
<a name="box-integration-capabilities"></a>

The Box integration provides action capabilities through MCP server connectivity, enabling you to:
+ Upload and download files
+ Create and manage folders
+ Share files and folders
+ Search for content
+ Manage file permissions
+ Use AI-powered tools to ask questions, extract insights, and analyze content across files and hubs.

## Available tools
<a name="box-integration-tools"></a>

The Box MCP server typically provides the following tools:
+ `who_am_i` - Returns detailed information about the currently authenticated Box user.
+ `get_file_content` - Returns the content of a file stored in Box.
+ `get_file_details` - Gets comprehensive file information from Box including metadata, permissions, and version details.
+ `update_file_properties` - Updates file properties, including name, description, tags, and collections.
+ `upload_file` - Uploads a new file to Box.
+ `upload_file_version` - Uploads a new file version by providing the entire file contents to update an existing file in Box.
+ `create_folder` - Creates a new folder in Box.
+ `get_folder_details` - Retrieves comprehensive folder information including metadata, permissions, and collaboration settings.
+ `list_folder_content_by_folder_id` - Lists files, folders, and web links in a folder.
+ `update_folder_properties` - Updates folder properties, including name, description, tags, and collections.
+ `search_files_keyword` - Searches for files using keywords. Supports metadata filters, file extension filtering, and field selection.
+ `search_folders_by_name` - Searches for folders within Box by name using keyword matching.
+ `ai_qa_hub` - Asks a question to a Box Hub using Box AI.
+ `ai_qa_single_file` - Asks a question to a single file using Box AI.
+ `ai_qa_multi_file` - Asks a question to multiple files using Box AI.
+ `ai_extract_freeform` - Extracts metadata from files using Box AI in freeform format without requiring predefined template structures.
+ `ai_extract_structured` - Extracts structured metadata from files using Box AI based on either custom fields definition or an existing metadata template.
+ `create_file_comment` - Creates a new comment on a specific file.
+ `list_file_comments` - Lists all comments on a specific file.
+ `list_tasks` - Lists all tasks associated with a specific file, including status, message, and due dates.
+ `add_items_to_hub` - Adds files, folders, or web links to a specific hub.
+ `create_hub` - Creates a new hub.
+ `get_hub_details` - Retrieves detailed information about a specific hub.
+ `get_hub_items` - Gets items (files and folders) associated with a specific hub.
+ `list_hubs` - Lists all hubs accessible to the authenticated user.
+ `update_hub` - Updates the title and description of a specific hub.

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official Box documentation and MCP server repository.

## Setup requirements
<a name="box-integration-setup"></a>

To set up Box integration, you need:
+ Box account with appropriate permissions
+ Box API credentials (Client ID and Client Secret)
+ Amazon Quick with MCP integration enabled

## Compatibility
<a name="box-integration-compatibility"></a>

Box integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Canva integration
<a name="canva-integration"></a>

With Canva integration in Amazon Quick, you can create, edit, and manage designs and visual content through MCP server connectivity. This integration provides action capabilities for design operations and content creation.

## What you can do
<a name="canva-integration-capabilities"></a>

Canva integration provides action connector capabilities through MCP server connectivity:
+ Create new designs from templates
+ Edit existing designs and presentations
+ Manage design assets and media
+ Export designs in various formats
+ Share designs and collaborate with team members

## Available tools
<a name="canva-integration-tools"></a>

The Canva MCP server typically provides these tools:
+ `comment-on-design` - Add a comment on a Canva design. You need to provide the design ID and the message text. The comment will be added to the design and visible to all users with access to the design.
+ `create-design-from-candidate` - Create a new Canva design from a generation job candidate ID. This converts an AI-generated design candidate into an editable Canva design. If successful, returns a design summary containing a design ID that can be used with the editing\$1transaction\$1tools. To make changes to the design, first call this tool with the candidate\$1id from generate-design results, then use the returned design\$1id with start-editing-transaction and subsequent editing tools.
+ `create-folder` - Create a new folder in Canva. You can create it at the root level or inside another folder.
+ `export-design` - Export a Canva design, doc, presentation, whiteboard, videos and other Canva content types to various formats (PDF, JPG, PNG, PPTX, GIF, MP4). You should use the get-export-formats tool first to check which export formats are supported for the design. This tool provides a download URL for the exported file that you can share with users. Always display this download URL to users so they can access their exported content.
+ `generate-design` - Generate designs with AI. Use the 'query' parameter to tell AI what you want to create.
+ `get-design` - Get detailed information about a Canva design, such as a doc, presentation, whiteboard, video, or sheet. This includes design owner information, title, URLs for editing and viewing, thumbnail, created/updated time, and page count. This tool doesn't work on folders or images. You must provide the design ID, which you can find by using the search-designs or list-folder-items tools.
+ `get-design-content` - Get the text content of a doc, presentation, whiteboard, social media post, sheet, and other designs in Canva. Use this when you only need to read text content without making changes. IMPORTANT: If the user wants to edit, update, change, translate, or fix content, use start-editing-transaction instead as it shows content AND enables editing. You must provide the design ID, which you can find with the search-designs tool. When given a URL to a Canva design, you can extract the design ID from the URL. Do not use web search to get the content of a design as the content is not accessible to the public. Example URL: https://www.canva.com/design/\$1design\$1id\$1.
+ `get-design-pages` - Get a list of pages in a Canva design, such as a presentation. Each page includes its index and thumbnail. This tool doesn't work on designs that don't have pages (e.g. Canva docs). You must provide the design ID, which you can find using tools like search-designs or list-folder-items. You can use 'offset' and 'limit' to paginate through the pages. Use get-design to find out the total number of pages, if needed.
+ `get-export-formats` - Get the available export formats for a Canva design. This tool lists the formats (PDF, JPG, PNG, PPTX, GIF, MP4) that are supported for exporting the design. Use this tool before calling export-design to ensure the format you want is supported.
+ `import-design-from-url` - Import a file from a URL as a new Canva design
+ `list-comments` - Get a list of comments for a particular Canva design. Comments are discussions attached to designs that help teams collaborate. Each comment can contain replies, mentions, and can be marked as resolved or unresolved. You need to provide the design ID, which you can find using the search-designs tool. Use the continuation token to get the next page of results, if needed. You can filter comments by their resolution status (resolved or unresolved) using the comment\$1resolution parameter.
+ `list-folder-items` - List items in a Canva folder. An item can be a design, folder, or image. You can filter by item type and sort the results. Use the continuation token to get the next page of results if needed.
+ `list-replies` - Get a list of replies for a specific comment on a Canva design. Comments can contain multiple replies from different users. These replies help teams collaborate by allowing discussion on a specific comment. You need to provide the design ID and comment ID. You can find the design ID using the search-designs tool and the comment ID using the list-comments tool. Use the continuation token to get the next page of results, if needed.
+ `move-item-to-folder` - Move items (designs, folders, images) to a specified Canva folder
+ `reply-to-comment` - Reply to an existing comment on a Canva design. You need to provide the design ID, comment ID, and your reply message. The reply will be added to the specified comment and visible to all users with access to the design.
+ `resize-design` - Resize a Canva design to a preset or custom size. The tool will provide a summary of the new resized design, including its metadata.
+ `search-designs` - Search docs, presentations, videos, whiteboards, sheets, and other designs in Canva. Use 'query' parameter to search by title or content. If 'query' is used, 'sortBy' must be set to 'relevance'. Filter by 'any' ownership unless specified. Sort by relevance unless specified. Use the continuation token to get the next page of results, if needed.
+ `search-folders` - Search the user's folders and folders shared with the user based on folder names and tags. Returns a list of matching folders with pagination support.
+ `upload-asset-from-url` - Upload an asset (e.g. an image, a video) from a URL into Canva If the API call returns "Missing scopes: [asset:write]", you should ask the user to disconnect and reconnect their connector. This will generate a new access token with the required scope for this tool.

## Setting up Canva integration
<a name="canva-integration-setup"></a>

Canva integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ Canva account with appropriate permissions

## Compatibility
<a name="canva-integration-compatibility"></a>

Canva integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# GitHub integration
<a name="github-integration"></a>

With GitHub integration in Amazon Quick, you can manage repositories, create and review pull requests, track issues, and collaborate on code through MCP server connectivity. This integration provides action capabilities for development workflow operations.

## What you can do
<a name="github-integration-capabilities"></a>

GitHub integration provides action connector capabilities through MCP server connectivity:
+ Create and manage repositories
+ Create, review, and merge pull requests
+ Track and manage issues
+ Manage branches and commits
+ Review code and provide feedback
+ Manage project boards and milestones

## Available tools
<a name="github-integration-tools"></a>

The GitHub MCP server typically provides these tools:
+ `create_repository` - Create new repositories
+ `get_repository` - Get repository information
+ `list_issues` - List repository issues
+ `create_issue` - Create new issues
+ `create_pull_request` - Create pull requests
+ `list_pull_requests` - List pull requests
+ `get_file_contents` - Read file contents
+ `create_commit` - Create commits
+ `search_repositories` - Search for repositories

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official GitHub documentation and MCP server repository.

## Setting up GitHub integration
<a name="github-integration-setup"></a>

GitHub integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ GitHub account with appropriate repository permissions
+ Personal access token or GitHub App credentials

## Compatibility
<a name="github-integration-compatibility"></a>

GitHub integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Google Drive knowledge base integration
<a name="google-drive-integration"></a>

With the Google Drive knowledge base integration, you can index your Google Drive content. Your Amazon Quick agents can then search this content and answer questions about it.

Amazon Quick supports two authentication methods for connecting to Google Drive:
+ **User-managed setup** – You sign in to Google Drive directly to authorize the connection. This is the simplest way to get started. For more information, see [User-managed setup](google-drive-kb-user-managed.md).
+ **Admin-managed setup (service credentials)** – A Google Workspace administrator creates a service account with domain-wide delegation to authorize the connection. A key benefit of admin-managed setup is built-in document-level access control (ACL). Amazon Quick automatically syncs access control lists from Google Drive. It verifies each user's permissions at query time, so users see answers only from documents that they are authorized to access. For more information, see [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).

After you connect, Amazon Quick indexes your Google Drive files and folders into a knowledge base. Your Amazon Quick agents can then search this content and generate answers that are grounded in your Google Drive data.

## Prerequisites
<a name="google-drive-kb-prerequisites"></a>

Before you set up the Google Drive integration, make sure that you have the following:
+ A Google account with Google Drive access.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

For admin-managed setup, additional prerequisites apply. For more information, see [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).

## Supported content types
<a name="google-drive-kb-content-types"></a>

The Google Drive connector supports all of the common file types that Amazon Quick knowledge bases support. These include PDF, Word, Excel, PowerPoint, and text files. The connector also supports the following Google Workspace-specific formats:
+ Google Docs
+ Google Sheets
+ Google Slides

For more information about supported file types, size limits, and content processing options, see [Common configuration settings](knowledge-base-integrations.md#common-configuration-settings).

# User-managed setup
<a name="google-drive-kb-user-managed"></a>

With user-managed setup, you sign in to Google Drive directly to authorize the connection. Amazon Quick handles authentication through a managed OAuth flow. No Google Cloud project, service account, or domain-wide delegation is required.

## Prerequisites
<a name="google-drive-kb-user-managed-prereqs"></a>

Before you set up a user-managed Google Drive knowledge base, verify the following:
+ You have a Google account with access to Google Drive.
+ Your Google Workspace administrator allows third-party app access, or can allow the Amazon Quick app on your behalf.
+ Your browser allows popups from the Amazon Quick console domain.

**Note**  
If your organization restricts third-party app access in Google Workspace, your Google Workspace administrator might need to allow the Amazon Quick app before users can sign in. Contact your Google Workspace administrator if you encounter an error during sign-in.

**Note**  
User-managed setup does not support document-level access control (ACL). ACL is a mechanism that controls which users can access specific documents. If you need document-level access control, use [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md) instead.

## Permissions granted during consent
<a name="google-drive-kb-user-managed-permissions"></a>

When you authorize the connection, Amazon Quick requests the following permissions from your Google account:

See and download all your Google Drive files  
+ Allows Amazon Quick to see your Google Drive files
+ Allows Amazon Quick to download your files
+ Allows Amazon Quick to see the names and email addresses of people you share files with

See information about your Google Drive files  
+ Allows Amazon Quick to see the titles and descriptions of your files
+ Allows Amazon Quick to see the names and email addresses of people you share files with
+ Allows Amazon Quick to see your folders and how files are organized

**Note**  
You can review and remove this access at any time from your Google Account permissions settings.

## Set up a Google Drive knowledge base
<a name="google-drive-kb-user-managed-setup"></a>

To create a user-managed Google Drive knowledge base, complete the following steps in the Amazon Quick console.

1. In the Amazon Quick console, choose **Integrations**.

1. Find **Google Drive** and choose the **Add** (\$1) icon.

1. In the **Create Google Drive knowledge base** dialog, under **Authentication method**, choose **Sign in to Google Drive** and complete the Google sign-in and consent flow.

1. Under **Create knowledge base**, enter a name and an optional description for your knowledge base.

1. In the **Content** section, choose **Add content** and select the Google Drive files and folders that you want to index. You can browse content from your personal drive, files shared with you, and shared drives in your organization.

1. Choose **Create**.

After you choose **Create**, the data sync starts automatically.

## Access controls
<a name="google-drive-kb-user-managed-access"></a>

**Important**  
When Amazon Quick indexes Google Drive content through user-managed setup, it does not sync access control lists (ACLs) from Google Drive. All indexed content is accessible to any user who has access to the knowledge base in Amazon Quick, regardless of their permissions in Google Drive. Carefully review which content you include when you create a knowledge base.

If you require document-level access control, use the [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md) instead.

## Manage and troubleshoot your integration
<a name="google-drive-kb-user-managed-manage"></a>

For instructions on editing, sharing, or deleting your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

For more information about knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).

### Google Drive-specific issues
<a name="google-drive-kb-user-managed-issues"></a>
+ **App blocked by administrator** – If your Google Workspace administrator restricts third-party app access, you might see an error when you attempt to sign in. Contact your Google Workspace administrator to allow the Amazon Quick app.
+ **Authentication popup fails** – Verify that your browser allows popups from the Amazon Quick console domain. Try using a different browser or clearing your browser cache.
+ **Permissions revoked** – If you previously revoked Amazon Quick access from your Google Account permissions settings, you need to re-authenticate by editing the integration and signing in again.
+ **Missing content** – Verify that the Google account that you used for authentication has access to the files and folders that you selected. Content that was shared with you after the initial sync requires a resync to be indexed.
+ **Google API rate limiting** – Google Drive might limit requests during high usage periods. If syncs fail or are incomplete, retry during off-peak hours.

## Known limitations
<a name="google-drive-kb-user-managed-limitations"></a>
+ Document-level access control (ACL) is not supported with user-managed setup. If you require document-level access control, use [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).
+ Synchronization of file comments is not supported.

# Admin-managed Google Drive knowledge base setup
<a name="google-drive-kb-admin-managed"></a>

With admin-managed setup, a Google Workspace administrator creates a service account and delegates domain-wide access. Individual users don't need to authorize through sign-in.

Admin-managed setup includes built-in document-level access control list (ACL) support. Amazon Quick automatically syncs ACLs from Google Drive and verifies each user's permissions at query time.

For more information about ACL best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).

## Prerequisites
<a name="google-drive-kb-admin-managed-prerequisites"></a>

Make sure that you have the following before you set up the integration.
+ Administrator access to your organization's Google Workspace.
+ An Amazon Quick enterprise user account. Administrator access is not required.
+ A Google Workspace account with an email domain that matches the email domain that is used for your Amazon Quick identity.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Setup overview
<a name="google-drive-kb-admin-managed-overview"></a>

The setup involves the following phases:

1. **Configure Google Workspace** – Create a Google Cloud service account with read-only API access and domain-wide delegation. Then create a dedicated admin user for the service account to impersonate. For more information, see [Configure Google Workspace](google-drive-kb-google-config.md).

1. **Create the knowledge base in Amazon Quick** – Create a Google Drive knowledge base by using the service account credentials from Phase 1. For more information, see [Creating a knowledge base in Amazon Quick](google-drive-kb-connection.md).

Document-level access control is automatically enabled for all admin-managed knowledge bases. For more information about how access controls work, see [Document-level access controls](google-drive-kb-acl.md).

# Configure Google Workspace
<a name="google-drive-kb-google-config"></a>

To connect Amazon Quick to Google Drive, complete the following tasks in the Google Cloud console and Google Workspace Admin Console. You create a Google Cloud project, turn on the required APIs, generate service account credentials, and configure domain-wide delegation. You also create a dedicated admin user for the service account to impersonate.

**Prerequisites**  
Before you begin, make sure that you have the following:  
A Google Workspace account with administrator access
Permission to create projects in the Google Cloud console

## Creating a Google Cloud project
<a name="google-drive-kb-create-project"></a>

1. Open the Google Cloud console.

1. From the project selector at the top of the page, choose **New Project**.

1. Enter a project name, then choose **Create**.

1. After the project is created, choose **Select Project** to switch to it. This might take a few moments.

## Turning on the required APIs
<a name="google-drive-kb-enable-apis"></a>

Amazon Quick requires three Google APIs. Turn on each one from the API Library.

1. In the navigation menu, choose **APIs & Services**, then choose **Library**.

1. Search for each of the following APIs and choose **Enable**:
   + Google Drive API
   + Google Drive Activity API
   + Admin SDK API

## Creating the service account
<a name="google-drive-kb-create-service-account"></a>

1. In the navigation menu, choose **APIs & Services**, then choose **Credentials**.

1. Choose **Create Credentials**, then choose **Service account**.

1. Enter a name and optional description for the service account, then choose **Done**.

## Generating a private key
<a name="google-drive-kb-generate-key"></a>

1. On the **Credentials** page, choose the service account you created.

1. Choose the **Keys** tab, then choose **Add Key**, **Create new key**.

1. Confirm that **JSON** is selected, then choose **Create**.

The browser downloads a JSON file containing the private key. Store this file securely. You upload it to Amazon Quick in a later step.

**Note**  
If you receive an error stating that service account key creation is disabled by an organization policy, see [Resolving organization policy restrictions](#google-drive-kb-admin-troubleshooting-org-policy).

## Recording the service account unique ID
<a name="google-drive-kb-record-unique-id"></a>

1. On the service account detail page, choose the **Details** tab.

1. Copy the value in the **Unique ID** field. You need this value when you configure domain-wide delegation.

## Configuring domain-wide delegation
<a name="google-drive-kb-domain-delegation"></a>

Domain-wide delegation allows the service account to access Google Workspace data on behalf of users in your organization.

1. On the service account detail page, expand **Advanced settings**.

1. Choose **View Google Workspace Admin Console**. The admin console opens in a new tab.

1. In the admin console navigation pane, choose **Security**, **Access and data control**, **API controls**.

1. Choose **Manage Domain Wide Delegation**, then choose **Add new**.

1. For **Client ID**, enter the unique ID you copied earlier.

1. For **OAuth scopes**, enter the following comma-separated values:

   ```
   https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/forms.body.readonly
   ```

1. Choose **Authorize**.

## Creating a delegated admin user
<a name="google-drive-kb-create-admin-user"></a>

The service account acts on behalf of a Google Workspace admin user. Create a dedicated user for this purpose and assign the minimum required roles.

1. In the Google Workspace Admin Console, choose **Directory**, then choose **Users**.

1. Choose **Add new user**.

1. Enter a first name, last name, and primary email address for the new user, then choose **Add new user**.

1. Choose **Done**.

1. From the user list, choose the user you created. If the user does not appear, refresh the page.

1. On the user detail page, expand the **Admin roles and privileges** section.

1. Under **Roles**, assign the following roles:
   + Groups Reader
   + User Management Admin
   + Storage Admin

1. Choose **Save**.

Record the email address of this user. You need it when you create the knowledge base in Amazon Quick.

## Troubleshooting the Google Workspace configuration
<a name="google-drive-kb-google-config-troubleshooting"></a>

### Resolving organization policy restrictions
<a name="google-drive-kb-admin-troubleshooting-org-policy"></a>

If you receive the following error when creating a service account key:

```
The organization policy constraint iam.disableServiceAccountKeyCreation
is enforced on your organization.
```

**Note**  
For Google Cloud organizations created on or after May 3, 2024, this constraint is enforced by default.

You must override the policy for your project.

1. Open the Google Cloud console and confirm that the correct project is selected.

1. In the navigation menu, choose **IAM & Admin**, then choose **Organization Policies**.

1. In the **Filter** field, enter `iam.disableServiceAccountKeyCreation`. Then, in the policy list, choose **Disable service account key creation**.

1. Choose **Manage policy**.
**Note**  
If **Manage policy** is unavailable, you need the Organization Policy Administrator role (`roles/orgpolicy.policyAdmin`) at the organization level. See [Granting the Organization Policy Administrator role](#google-drive-kb-admin-troubleshooting-org-admin-role).

1. In the **Policy source** section, ensure that **Override parent's policy** is selected.

1. Under **Enforcement**, turn off enforcement for this organization policy constraint.

1. Choose **Set policy**.

The change can take several minutes to propagate.

### Granting the Organization Policy Administrator role
<a name="google-drive-kb-admin-troubleshooting-org-admin-role"></a>

The Organization Policy Administrator role (`roles/orgpolicy.policyAdmin`) must be granted at the organization level, not the project level. It does not appear in the role list when assigning roles to a project.

To grant this role, select your organization (not a project) from the project selector in the Google Cloud console. Then, choose **IAM & Admin**, **IAM**, and assign the role to your account. For detailed instructions, see [Manage access to projects, folders, and organizations](https://cloud.google.com/iam/docs/granting-changing-revoking-access) in the Google Cloud documentation.

The role assignment can take several minutes to propagate.

# Creating a knowledge base in Amazon Quick
<a name="google-drive-kb-connection"></a>

In this phase, you create a knowledge base in Amazon Quick and provide the service account credentials from the Google Workspace configuration. Any enterprise user can complete this phase. Amazon Quick administrator access is not required.

If a Google Workspace administrator completed the Google Workspace configuration on your behalf, you need the JSON key file and the delegated admin email address before you proceed.

## Setting up the knowledge base
<a name="google-drive-kb-connection-setup"></a>

1. In the Amazon Quick console, choose **Integrations**.

1. Under **Knowledge bases**, find **Google Drive**, and then choose the **Add** (\$1) icon.

1. In the **Create Google Drive knowledge base** dialog, choose **Have admin credentials? Configure document-level access control.**

1. In the **Connected account** dropdown, choose **Add account**.

1. For **Name**, enter a name for the connection. Use a descriptive name such as your Google Workspace domain.
**Important**  
You cannot change the connection name after you save it.

1. Choose **Upload .JSON key**, and then choose the JSON file that you downloaded during the Google Workspace configuration.

1. For **Google workspace admin email**, enter the email address of the delegated admin user that you created during the Google Workspace configuration.

1. Choose **Next**.

## Choosing content to sync
<a name="google-drive-kb-connection-content"></a>

1. Enter a **Name** and optional **Description** for your knowledge base.

1. Choose which Google Drive content to include:
   + **My Drive (all users)** – Includes files from all users' My Drive in your organization.
   + **Shared with me (all users)** – Includes files that are shared with your users.
   + **Shared drives** – All shared drives sync by default. To include or exclude specific drives, use the **Filter type** dropdown and **Add shared drive IDs** field. You can enter 1 to 100 shared drive IDs.

1. Choose **Next** to configure advanced settings.

## Configuring advanced settings
<a name="google-drive-kb-connection-advanced"></a>

In the **Advanced settings** step, you can configure optional settings for the knowledge base.

Filter content by date  
Limit which documents are crawled based on their last modified date. The start date defaults to one year before today. You can change or clear the start date, and optionally set an end date.

Multi-media content, file size, and file patterns  
Choose which content types to include in the knowledge base.  
+ **Visual content in documents** – Extracts and indexes visual elements from supported document formats. This option is enabled by default.
+ **Audio files** – Transcribes and indexes audio files.
+ **Video files** – Transcribes and indexes video files.

Choose **Create** to create the knowledge base. After you choose **Create**, the data sync starts automatically.

## Managing and troubleshooting
<a name="google-drive-kb-admin-managed-manage"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

For information about knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).

### Admin-managed setup issues
<a name="google-drive-kb-admin-troubleshooting"></a>
+ **Google API rate limiting** – Google Drive might throttle requests during high usage periods. If syncs fail or are incomplete, retry during off-peak hours.
+ **SSL certificate errors** – If you receive an error about SSL certificate errors when you create your knowledge base, verify the OAuth scopes that you configured during domain-wide delegation.

# Document-level access controls
<a name="google-drive-kb-acl"></a>

Admin-managed Google Drive knowledge bases include built-in document-level access control. Amazon Quick syncs access control lists (ACLs) from Google Drive during each crawl and verifies each user's permissions at query time, so users only see answers from documents that they are authorized to access.

## How it works
<a name="google-drive-kb-acl-how-it-works"></a>

When a user submits a query to an Amazon Quick agent that uses an admin-managed Google Drive knowledge base, the system enforces access controls in two stages:

1. **Pre-retrieval filtering** – Amazon Quick performs a semantic search against the vector index to find the most relevant document passages. The system applies access control lists that are already stored in the index. This produces a preliminary set of candidate documents. This stage is necessary because real-time API calls for every document in the index would be too costly at scale.

1. **Real-time verification** – The system verifies the candidate documents in real time by calling the Google Drive APIs. It uses the service account credential that the administrator provided to generate user-specific access tokens through impersonation. Google Drive maintains the source of truth for access control lists that are associated with each document. The system removes any documents that the user is not authorized to access from the result set.

The system passes only the verified and authorized document passages to the model as context. The model uses this knowledge to generate a response. This two-stage approach provides document-level access control guarantees and maintains performance at scale.

## Enable ACL management
<a name="google-drive-kb-acl-enable"></a>

Document-level access control is automatically enabled for all admin-managed knowledge bases. No additional configuration is required.

For more information about ACL best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).

## Known limitations
<a name="google-drive-kb-admin-managed-limitations"></a>
+ File comments synchronization is not supported.

For more information about general ACL limitations and best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).

# HubSpot integration
<a name="hubspot-integration"></a>

With HubSpot integration in Amazon Quick, you can manage contacts, deals, marketing campaigns, and customer relationships through MCP server connectivity. This integration provides action capabilities for CRM and marketing operations.

## What you can do
<a name="hubspot-integration-capabilities"></a>

HubSpot integration provides action connector capabilities through MCP server connectivity:
+ Create and manage contacts and companies
+ Track and update deals in the sales pipeline
+ Create and manage marketing campaigns
+ Log and track customer interactions
+ Generate reports and analytics
+ Manage tickets and customer support cases

## Available tools
<a name="hubspot-integration-tools"></a>

The HubSpot MCP server typically provides these tools:
+ `create_contact` - Create new contacts
+ `get_contact` - Retrieve contact information
+ `update_contact` - Update contact details
+ `create_deal` - Create new deals
+ `update_deal` - Update deal information
+ `list_deals` - List deals in pipeline
+ `create_ticket` - Create support tickets
+ `search_contacts` - Search for contacts
+ `create_company` - Create company records

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official HubSpot documentation and MCP server repository.

## Setting up HubSpot integration
<a name="hubspot-integration-setup"></a>

HubSpot integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ HubSpot account with appropriate permissions
+ HubSpot API key or private app credentials

## Compatibility
<a name="hubspot-integration-compatibility"></a>

HubSpot integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# HuggingFace integration
<a name="huggingface-integration"></a>

With HuggingFace integration in Amazon Quick, you can access machine learning models, datasets, and spaces through MCP server connectivity. This integration provides action capabilities for ML workflow operations and model management.

## What you can do
<a name="huggingface-integration-capabilities"></a>

HuggingFace integration provides action connector capabilities through MCP server connectivity:
+ Browse and download models from HuggingFace Hub
+ Access and manage datasets
+ Interact with HuggingFace Spaces
+ Upload and manage your own models
+ Run inference on hosted models
+ Manage model repositories and versions

## Available tools
<a name="huggingface-integration-tools"></a>

The HuggingFace MCP server typically provides these tools:
+ `search_models` - Search for models on HuggingFace Hub
+ `get_model_info` - Get detailed model information
+ `download_model` - Download models locally
+ `list_datasets` - List available datasets
+ `get_dataset_info` - Get dataset information
+ `run_inference` - Run inference on hosted models
+ `upload_model` - Upload models to Hub
+ `list_spaces` - List HuggingFace Spaces

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official HuggingFace documentation and MCP server repository.

## Setting up HuggingFace integration
<a name="huggingface-integration-setup"></a>

HuggingFace integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ HuggingFace account with appropriate permissions
+ HuggingFace API token for authentication

## Compatibility
<a name="huggingface-integration-compatibility"></a>

HuggingFace integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Intercom integration
<a name="intercom-integration"></a>

With Intercom integration in Amazon Quick, you can manage customer conversations, support tickets, and user engagement through MCP server connectivity. This integration provides action capabilities for customer support and communication operations.

## What you can do
<a name="intercom-integration-capabilities"></a>

Intercom integration provides action connector capabilities through MCP server connectivity:
+ Manage customer conversations and messages
+ Create and update support tickets
+ Manage user profiles and contact information
+ Send targeted messages and campaigns
+ Track customer engagement and activity
+ Manage team assignments and workflows

## Available tools
<a name="intercom-integration-tools"></a>

The Intercom MCP server typically provides these tools:
+ `create_conversation` - Start new conversations
+ `reply_to_conversation` - Reply to existing conversations
+ `list_conversations` - List customer conversations
+ `create_user` - Create new user profiles
+ `update_user` - Update user information
+ `send_message` - Send messages to users
+ `create_ticket` - Create support tickets
+ `search_users` - Search for users

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official Intercom documentation and MCP server repository.

## Setting up Intercom integration
<a name="intercom-integration-setup"></a>

Intercom integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ Intercom account with appropriate permissions
+ Intercom API access token

## Compatibility
<a name="intercom-integration-compatibility"></a>

Intercom integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Linear integration
<a name="linear-integration"></a>

With Linear integration in Amazon Quick, you can manage issues, track projects, and streamline development workflows through MCP server connectivity. This integration provides action capabilities for project management and issue tracking operations.

## What you can do
<a name="linear-integration-capabilities"></a>

Linear integration provides action connector capabilities through MCP server connectivity:
+ Create and manage issues and tasks
+ Track project progress and milestones
+ Manage team workflows and assignments
+ Update issue status and priorities
+ Create and manage project cycles
+ Generate reports and track metrics

## Available tools
<a name="linear-integration-tools"></a>

The Linear MCP server typically provides these tools:
+ `create_issue` - Create new issues
+ `update_issue` - Update issue details
+ `list_issues` - List team issues
+ `search_issues` - Search for specific issues
+ `create_project` - Create new projects
+ `list_projects` - List team projects
+ `assign_issue` - Assign issues to team members
+ `create_cycle` - Create project cycles

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official Linear documentation and MCP server repository.

## Setting up Linear integration
<a name="linear-integration-setup"></a>

Linear integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ Linear account with appropriate team permissions
+ Linear API key for authentication

## Compatibility
<a name="linear-integration-compatibility"></a>

Linear integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Model Context Protocol (MCP) integration
<a name="mcp-integration"></a>

Model Context Protocol (MCP) is an open standard that defines how AI applications communicate with external tools and data sources. MCP uses a client-server architecture. AI applications act as clients that connect to MCP servers. Each MCP server exposes a set of tools. These tools are structured operations that the AI application can invoke to perform tasks, such as querying databases, calling APIs, or interacting with third-party services.

With MCP integration in Amazon Quick, you can connect to remote MCP servers so that your AI assistant can use the tools that those servers provide. For example, you can connect to an MCP server that provides access to your project management system. This connection allows the assistant to create tickets, look up issues, or update statuses as part of a conversation. Because MCP is an open standard, you can connect to any compatible server without building custom integrations for each tool.

## What you can do
<a name="mcp-integration-capabilities"></a>

MCP integration registers MCP server tools as actions in Amazon Quick.

**Action connector**  
Each tool that is exposed by an MCP server is registered as an action that your AI assistant can invoke during conversations. The integration secures these connections by using Proof Key for Code Exchange (PKCE) with the S256 challenge method and Resource Indicators (RFC 8707) to bind access tokens to specific MCP servers.

## Before you begin
<a name="mcp-integration-prerequisites"></a>

Before you set up MCP integration, make sure that you have the following:
+ An MCP server endpoint with appropriate access.
+ Authentication credentials for the MCP server, if required. For more information, see [Prepare MCP server setup and authentication](#mcp-integration-authentication).
+ An Amazon Quick Enterprise subscription.

**Note**  
MCP integration supports remote servers only. HTTP streaming is preferred over Server-Sent Events (SSE). Local stdio connections and VPC connectivity are not supported.

## Prepare MCP server setup and authentication
<a name="mcp-integration-authentication"></a>

When you connect to an MCP server, Amazon Quick uses OAuth 2.0 Protected Resource Metadata (RFC 9728) to automatically discover authorization server information. The client sends an initial unauthenticated request to the MCP server. If the server responds with a 401 status that contains a `WWW-Authenticate` header with a `resource_metadata` URL, then Amazon Quick uses that URL to fetch the metadata document. If the header is not present, Amazon Quick falls back to the well-known URI at the server root.

If the authorization server supports Dynamic Client Registration (DCR), Amazon Quick automatically registers itself by using the discovered `registration_endpoint` from the authorization server metadata. No manual credential configuration is required. Both confidential and public client flows are supported. DCR applies regardless of the authentication method that you choose.

If the authorization server does not support DCR, you must manually provide credentials. Choose the authentication method that matches your MCP server requirements.

**User authentication (OAuth)**  
Gather the following information from your MCP server configuration:  
+ **Client ID** – The OAuth client ID.
+ **Client Secret** – The OAuth client secret.
+ **Token URL** – The OAuth token endpoint.
+ **Authorization URL** – The OAuth authorization endpoint.
+ **Redirect URL** – The OAuth redirect URI.

**Service authentication (Service-to-Service)**  
Gather the following information from your MCP server configuration:  
+ **Client ID** – The service client ID.
+ **Client Secret** – The service client secret.
+ **Token URL** – The service token endpoint.

**No authentication**  
If the MCP server does not require authentication, no credentials are needed. Select this option for MCP servers that allow unauthenticated access.

## Set up MCP integration
<a name="mcp-integration-setup"></a>

After you prepare your MCP server configuration and authentication credentials, create your MCP integration.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Add**.

1. On the **Create Integration** page, enter the integration details:
   + **Name** – A descriptive name for your MCP integration.
   + **Description** (Optional) – The purpose of the integration.
   + **MCP server endpoint** – The URL of the MCP server.

1. Choose **Next**.

1. Select the authentication method (user, service, or no authentication).

1. Provide the appropriate configuration details.

1. Choose **Create and continue**.

1. Review the integration details.

1. Choose **Next**.

1. Share the integration with other users if needed.

After you create your MCP integration, the available tools are discovered and registered as actions.

## Review integration
<a name="mcp-integration-review"></a>

After you configure authentication, review the MCP integration capabilities:

1. The system connects to the MCP server and discovers available capabilities.

1. Review the list of available actions and tasks that the MCP server provides.

1. Confirm the integration configuration and capabilities.

### Capability discovery
<a name="mcp-integration-capabilities-discovery"></a>

During the connection process that is described in [Prepare MCP server setup and authentication](#mcp-integration-authentication), Amazon Quick also discovers and registers the tools that are available on the MCP server. After discovery completes, each tool is listed as an action that you can review and turn on.

## Manage MCP integrations
<a name="mcp-integration-management"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

## Limitations
<a name="mcp-integration-limitations"></a>

When you use MCP integrations in Amazon Quick, be aware of the following limitations:
+ MCP operations have a fixed 60-second timeout. Operations that exceed this limit automatically fail with an HTTP 424 error.
+ Custom HTTP headers are not supported in MCP operations. Only standard system headers are transmitted.
+ Tool lists remain static after initial registration. To pick up server-side tool changes, you must delete the integration and recreate it. 
+ Connector creation might fail if the Amazon Quick callback URI is not allow-listed by third-party providers.
+ Server connectivity issues result in immediate failure without retry attempts.
+ Step-up authorization is not supported. If an MCP server requires additional scopes after the initial authorization (HTTP 403 with `insufficient_scope`), you must re-authorize the entire connection. Incremental permission upgrades are not available.
+ Scope handling has the following limitations:
  + Amazon Quick does not extract the `scope` parameter from the server's initial 401 `WWW-Authenticate` challenge. Scopes are determined from the Protected Resource Metadata document instead.
  + When the metadata does not specify supported scopes, Amazon Quick applies default scopes rather than omitting them. This behavior might cause authentication failures with servers that do not recognize the default scopes.
+ Only Dynamic Client Registration (DCR) is supported for automatic client registration. Client ID Metadata Documents are not supported.
+ Well-known URI discovery uses the server root path only. Path-specific metadata locations (path-insertion discovery) are not supported. This limitation might prevent discovery of servers that serve metadata only at path-specific URIs.

# Monday.com integration
<a name="monday-integration"></a>

With Monday.com integration in Amazon Quick, you can manage project boards, track items, and coordinate team workflows through MCP server connectivity. This integration provides action capabilities for project management and team collaboration operations.

## What you can do
<a name="monday-integration-capabilities"></a>

Monday.com integration provides action connector capabilities through MCP server connectivity:
+ Create and manage project boards
+ Add and update board items and tasks
+ Manage team assignments and workloads
+ Track project timelines and deadlines
+ Update item status and progress
+ Generate reports and analytics

## Available tools
<a name="monday-integration-tools"></a>

The Monday.com MCP server typically provides these tools:
+ `create_board` - Create new project boards
+ `get_board` - Get board information
+ `create_item` - Create new board items
+ `update_item` - Update item details
+ `list_items` - List board items
+ `create_column` - Create board columns
+ `update_column_value` - Update column values
+ `search_boards` - Search for boards

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official Monday.com documentation and MCP server repository.

## Setting up Monday.com integration
<a name="monday-integration-setup"></a>

Monday.com integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ Monday.com account with appropriate board permissions
+ Monday.com API token for authentication

## Compatibility
<a name="monday-integration-compatibility"></a>

Monday.com integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# Microsoft OneDrive integration
<a name="onedrive-integration"></a>

Use the Microsoft OneDrive integration to perform actions on OneDrive files and folders, or to create knowledge bases from OneDrive content for AI-powered search and Q&A.

## What you can do
<a name="onedrive-integration-capabilities"></a>

**Action connector**  
Create, update, delete, and manage OneDrive files and folders through Microsoft Graph API calls.

**Knowledge base**  
Index OneDrive documents, spreadsheets, and presentations. Amazon Quick agents can then search and answer questions about the content.

# Microsoft OneDrive action integration
<a name="onedrive-action-integration"></a>

Use the Microsoft OneDrive action connector to manage OneDrive files, folders, and Excel workbooks directly in Amazon Quick through natural language.

Setting up this integration involves two steps. First, you register an application in Microsoft Entra and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Entra app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="onedrive-action-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with OneDrive access.
+ Access to the [Microsoft Entra admin center](https://entra.microsoft.com/) with at least Application Developer permissions.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure Microsoft Entra
<a name="onedrive-entra-setup"></a>

Before you configure Amazon Quick, create an app registration in Microsoft Entra. Complete all of the following steps in Entra before moving to the Amazon Quick console.

For more information about app registrations, see [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft documentation.

### Register the application
<a name="entra-app-registration"></a>

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/).

1. In the left navigation, choose **Entra ID**, then choose **App registrations**.

1. Choose **New registration**.

1. For **Name**, enter a descriptive name for your integration.

1. For **Supported account types**, choose **Accounts in this organizational directory only**.

1. For **Redirect URI**, select **Web** and enter `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *\$1region\$1* with the AWS Region where your Amazon Quick instance is deployed.

1. Choose **Register**.

1. On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need these values for the Amazon Quick configuration.

### Create a client secret
<a name="entra-client-secret"></a>

Amazon Quick needs a client secret to authenticate with Microsoft Entra. This secret acts as a password for the app registration.

1. From your app registration, choose **Certificates & secrets**.

1. Choose **New client secret**.

1. Enter a description and choose an expiration period.

1. Choose **Add**.

1. Copy the **Value** immediately. This value is only displayed once.

**Important**  
Copy the secret **Value**, not the Secret ID. The Value is the longer string used for authentication.

### Configure API permissions
<a name="onedrive-entra-api-permissions"></a>

This integration uses delegated permissions, which allow the app to act on behalf of a signed-in user. For more information, see [Overview of Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-overview) in the Microsoft documentation.

1. From your app registration, choose **API permissions**.

1. Choose **Add a permission**, then choose **Microsoft Graph**.

1. Choose **Delegated permissions** and add the permissions from the table below.

1. Choose **Grant admin consent for [your tenant name]** to approve the permissions.

Add the following as Delegated permissions in your Entra app registration. For the full permissions reference, see [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) in the Microsoft documentation.


**OneDrive action integration – delegated permissions**  

| Permission | Description | 
| --- | --- | 
| Files.ReadWrite | Allows the app to read, create, update, and delete the signed-in user's files. | 
| User.Read.All | Allows the app to read the full set of profile properties of all users in the organization on behalf of the signed-in user. | 
| offline\$1access | Allows the app to refresh access tokens without requiring the user to sign in again. This reduces how often users need to re-authenticate. | 

### Record your credentials
<a name="entra-record-credentials"></a>

Before leaving the Microsoft Entra admin center, confirm you have the following values. You need them for the Amazon Quick configuration.


**Required credentials from Microsoft Entra**  

| Value | Where to find it | 
| --- | --- | 
| Application (client) ID | App registration overview page | 
| Directory (tenant) ID | App registration overview page | 
| Client secret value | Certificates & secrets page | 

## Set up the integration in Amazon Quick
<a name="onedrive-action-integration-setup"></a>

After you complete the Entra configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Microsoft OneDrive** and choose the Add (plus "\$1") button.

1. Choose the **Actions** tab.

1. Choose **Perform actions in Microsoft OneDrive**.

1. Fill in the integration details:
   + **Name** – Descriptive name for your OneDrive integration.
   + **Description** (Optional) – Purpose of the integration.

1. Fill in the connection settings:
   + **Base URL** – `https://graph.microsoft.com/v1.0`
   + **Client ID** – Application (client) ID from your Entra app registration.
   + **Client Secret** – Client secret value from your Entra app registration.
   + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
   + **Auth URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
   + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

## Available actions
<a name="onedrive-integration-actions"></a>

After you set up the integration, the following actions are available.


**Microsoft OneDrive available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Drive and items | Get Drive | Retrieve the properties and relationships of a drive. | 
| Drive and items | List Item | Get all items contained in the drive. | 
| Drive and items | Get Item | Get an item contained in the drive. | 
| Drive and items | Create Folder | Create a new folder in the user's drive. | 
| Drive and items | Update Item | Update the metadata for a file or folder. | 
| Drive and items | Delete Item | Delete a file or folder. Moves the item to the recycle bin. | 
| Drive and items | List Child Folders | Return a collection of items in the children of a folder. | 
| Drive and items | Copy Item | Create a copy of a file or folder to another location. | 
| Drive and items | Add Permissions | Send a sharing invitation for a file or folder. | 
| Drive and items | Upload File | Upload a new file or update an existing file. Supports files up to 250 MB. | 
| Excel workbooks | List Sheets | Retrieve a list of worksheet objects. | 
| Excel workbooks | Add Sheet | Add a new worksheet to the workbook. | 
| Excel workbooks | Read Sheet | Retrieve the properties of a worksheet object. | 
| Excel workbooks | Update Sheet | Update the properties of a worksheet object. | 
| Excel workbooks | Delete Sheet | Delete the worksheet from the workbook. | 
| Excel workbooks | Read Cell | Get the value of a single cell by row and column number. | 
| Excel workbooks | Write Cell | Set the value of a single cell by row and column number. | 
| Excel workbooks | Read Range | Get the values of a range. | 
| Excel workbooks | Write Range | Update the values of a range. | 
| Excel workbooks | Clear Range | Clear range values, format, fill, and border. | 
| Excel workbooks | Delete Range | Delete the cells associated with the range. | 
| Excel workbooks | Get Used Range | Get the smallest range that encompasses cells with a value or formatting. | 

## Manage and troubleshoot
<a name="entra-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="entra-troubleshooting-auth"></a>
+ **Incorrect app registration** – Verify the app registration in Microsoft Entra includes the required API permissions and that admin consent has been granted.
+ **Expired client secret** – Check if the client secret has expired in **Certificates & secrets** and generate a new one if needed.
+ **Incorrect redirect URI** – Verify the redirect URI in Microsoft Entra matches `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`.

### Common error messages
<a name="entra-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions. Contact your administrator to verify and grant appropriate permissions.
+ **`AADSTS50020: User account from identity provider does not exist in tenant`** – The user account is not configured in the correct Microsoft Entra tenant. Verify the user account exists in the tenant that matches the Directory (tenant) ID in your app registration.

# Microsoft OneDrive knowledge base integration
<a name="onedrive-kb-integration"></a>

Use the Microsoft OneDrive knowledge base integration to index OneDrive content so that Amazon Quick agents can search and answer questions about it.

Amazon Quick uses a pre-registered multi-tenant application to connect to OneDrive for knowledge bases. You do not need to create an app registration. When a user first connects, Microsoft presents a consent dialog. An administrator can grant consent on behalf of the entire organization, or individual users can consent for themselves.

## Before you begin
<a name="onedrive-kb-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with OneDrive access.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).
+ Your Microsoft administrator may need to grant organizational consent before users can create a OneDrive knowledge base. Administrators can grant organization-wide consent by signing in and choosing **Consent on behalf of your organization** during the integration creation flow.

**Note**  
When an administrator grants organizational consent, Microsoft Entra automatically creates an Enterprise Application (service principal) in your tenant. You can disable or delete this service principal at any time from **Enterprise applications** in the Microsoft Entra admin center, which immediately revokes all access.

## Set up the knowledge base integration
<a name="onedrive-kb-setup"></a>

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Microsoft OneDrive** and choose the Add (plus "\$1") button.

1. In the **Create OneDrive knowledge base** dialog, under **Connected account**, choose **Sign in to OneDrive** and complete the Microsoft sign-in and consent flow.

1. Under **Create knowledge base**, enter a name and an optional description for your knowledge base.

1. In the **Content** section, choose **Add content** and select the OneDrive files or folders you want to index.

1. Choose **Create**.

## Supported content types
<a name="onedrive-kb-content-types"></a>
+ **Microsoft Office documents:** Word, Excel, PowerPoint
+ **PDF files**
+ **Text files and rich text documents**
+ **Text documents with embedded images**
+ **Audio and video files**

## Access controls
<a name="onedrive-kb-access-controls"></a>

**Important**  
When Amazon Quick indexes OneDrive content, it does not sync access control lists (ACLs) from OneDrive. All indexed content is accessible to any user who has access to the knowledge base in Amazon Quick, regardless of their permissions in OneDrive. Review which content you include when creating a knowledge base.

## Limitations
<a name="onedrive-kb-limitations"></a>
+ File comments synchronization is not supported.

## Manage and troubleshoot
<a name="onedrive-kb-management"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

For general knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).

# Microsoft Outlook integration
<a name="microsoft-outlook-integration"></a>

Use the Microsoft Outlook action connector to access Outlook's email, calendar, and contact APIs directly in Amazon Quick through natural language.

Setting up this integration involves two steps. First, you register an application in Microsoft Entra and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Entra app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="exchange-integration-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with Outlook or Exchange Online access.
+ Access to the [Microsoft Entra admin center](https://entra.microsoft.com/) with at least Application Developer permissions.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure Microsoft Entra
<a name="exchange-entra-setup"></a>

Before you configure Amazon Quick, create an app registration in Microsoft Entra. Complete all of the following steps in Entra before moving to the Amazon Quick console.

For more information about app registrations, see [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft documentation.

### Register the application
<a name="entra-app-registration"></a>

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/).

1. In the left navigation, choose **Entra ID**, then choose **App registrations**.

1. Choose **New registration**.

1. For **Name**, enter a descriptive name for your integration.

1. For **Supported account types**, choose **Accounts in this organizational directory only**.

1. For **Redirect URI**, select **Web** and enter `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *\$1region\$1* with the AWS Region where your Amazon Quick instance is deployed.

1. Choose **Register**.

1. On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need these values for the Amazon Quick configuration.

### Create a client secret
<a name="entra-client-secret"></a>

Amazon Quick needs a client secret to authenticate with Microsoft Entra. This secret acts as a password for the app registration.

1. From your app registration, choose **Certificates & secrets**.

1. Choose **New client secret**.

1. Enter a description and choose an expiration period.

1. Choose **Add**.

1. Copy the **Value** immediately. This value is only displayed once.

**Important**  
Copy the secret **Value**, not the Secret ID. The Value is the longer string used for authentication.

### Configure API permissions
<a name="exchange-entra-api-permissions"></a>

Microsoft Graph supports two permission types for this integration. Delegated permissions allow the app to act on behalf of a signed-in user. Application permissions allow the app to act without a signed-in user. For more information, see [Overview of Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-overview) in the Microsoft documentation.

1. From your app registration, choose **API permissions**.

1. Choose **Add a permission**, then choose **Microsoft Graph**.

1. Choose **Delegated permissions** or **Application permissions** based on your authentication method, and add the permissions from the appropriate table below.

1. Choose **Grant admin consent for [your tenant name]** to approve the permissions.

**For user authentication (delegated permissions):**

Add the following as Delegated permissions in your Entra app registration. For the full permissions reference, see [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) in the Microsoft documentation.


**Outlook action integration – delegated permissions**  

| Permission | Description | 
| --- | --- | 
| Mail.ReadWrite | Allows the app to create, read, update, and delete email in user mailboxes. | 
| Mail.Send | Allows the app to send mail as users in the organization. | 
| Calendars.ReadWrite | Allows the app to create, read, update, and delete events in user calendars. | 
| Calendars.ReadWrite.Shared | Allows the app to create, read, update and delete events in all calendars the user has permissions to access, including delegate and shared calendars. | 
| User.Read | Allows users to sign in to the app and allows the app to read the profile of signed-in users. | 
| User.Read.All | Allows the app to read the full set of profile properties of other users in your organization. | 
| Contacts.Read | Allows the app to read user contacts. | 
| Place.Read.All | Allows the app to read company places (conference rooms and room lists) for calendar events and other applications. | 
| MailboxSettings.Read | Allows the app to read the user's mailbox settings. | 
| offline\$1access | Allows the app to refresh access tokens without requiring the user to sign in again. This reduces how often users need to re-authenticate. | 

**Note**  
`User.Read.All` and `Place.Read.All` require administrator consent. An administrator must grant consent before users can authenticate.

**For service authentication (application permissions):**

Add the following as Application permissions in your Entra app registration.


**Outlook action integration – application permissions**  

| Permission | Description | 
| --- | --- | 
| Mail.ReadWrite | Allows the app to create, read, update, and delete mail in all mailboxes. | 
| Mail.Send | Allows the app to send mail as any user. | 
| Calendars.ReadWrite | Allows the app to create, read, update, and delete events of all calendars. | 
| User.Read.All | Allows the app to read user profiles. | 
| Contacts.Read | Allows the app to read all contacts in all mailboxes. | 
| Place.Read.All | Allows the app to read company places (conference rooms and room lists) for calendar events and other applications. | 
| MailboxSettings.Read | Allows the app to read user's mailbox settings. | 

**Important**  
With service authentication, all actions execute as the service account. Any user with access to this integration can perform actions across all mailboxes that the service account can access. Scope the application permissions appropriately for your organization's security requirements.

### Record your credentials
<a name="entra-record-credentials"></a>

Before leaving the Microsoft Entra admin center, confirm you have the following values. You need them for the Amazon Quick configuration.


**Required credentials from Microsoft Entra**  

| Value | Where to find it | 
| --- | --- | 
| Application (client) ID | App registration overview page | 
| Directory (tenant) ID | App registration overview page | 
| Client secret value | Certificates & secrets page | 

## Set up the integration in Amazon Quick
<a name="exchange-integration-setup"></a>

After you complete the Entra configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. Choose **Microsoft Outlook** and choose the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** – Descriptive name for your Outlook integration.
   + **Description** (Optional) – Purpose of the integration.

1. Choose your connection type and fill in the connection settings:

   1. For **User authentication (OAuth)**, configure the following fields:
      + **Base URL** – `https://graph.microsoft.com/v1.0`
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Auth URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
      + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

   1. For **Service authentication**, configure the following fields:
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Scope** – `.default`

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

## Available actions
<a name="exchange-integration-actions"></a>

After you set up the integration, the following actions are available.


**Microsoft Outlook available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Email | List User Mails | View emails in a mailbox. | 
| Email | List Folder Messages | View messages in a specific mail folder. | 
| Email | View Email | Get email details by ID. | 
| Email | Send User Email | Send a new email message. | 
| Email | Reply To Email | Reply to an existing email. | 
| Email | Forward User Email | Forward an email to other recipients. | 
| Email | Update Email | Edit email properties. | 
| Email | Delete Email | Remove an email from a mailbox. | 
| Email | Move Email To Folder | Move an email to a different folder. | 
| Email | List Email Attachments | View attachments on an email. | 
| Email | Get Attachment | Get attachment details and content by ID. | 
| Calendar | List Calendar Events | View events on a calendar. | 
| Calendar | List Calendar View | View meetings in a specified date range. | 
| Calendar | Create Calendar Event | Create a new meeting or appointment. | 
| Calendar | Update Calendar Event | Modify an existing event. | 
| Calendar | Delete Calendar Event | Remove an event from a calendar. | 
| Calendar | Find Meeting Times | Suggest meeting times based on attendee availability. | 
| Contacts | List Contacts | View contacts. | 
| Users | List Users | View users in the organization. | 
| Settings | Get Mailbox Settings | Read mailbox configuration. | 
| Places | List Places | View meeting rooms and room lists. | 

## Manage and troubleshoot
<a name="entra-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="entra-troubleshooting-auth"></a>
+ **Incorrect app registration** – Verify the app registration in Microsoft Entra includes the required API permissions and that admin consent has been granted.
+ **Expired client secret** – Check if the client secret has expired in **Certificates & secrets** and generate a new one if needed.
+ **Incorrect redirect URI** – Verify the redirect URI in Microsoft Entra matches `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`.

### Common error messages
<a name="entra-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions. Contact your administrator to verify and grant appropriate permissions.
+ **`AADSTS50020: User account from identity provider does not exist in tenant`** – The user account is not configured in the correct Microsoft Entra tenant. Verify the user account exists in the tenant that matches the Directory (tenant) ID in your app registration.

# Microsoft SharePoint integration
<a name="microsoft-sharepoint-integration"></a>

Use the Microsoft SharePoint integration to perform actions on SharePoint lists, items, and files, or to create knowledge bases from SharePoint content for AI-powered search and Q&A.

## What you can do
<a name="sharepoint-integration-capabilities"></a>

**Action connector**  
Manage SharePoint lists, items, files, and Excel workbooks through Microsoft Graph API calls.

**Knowledge base**  
Index SharePoint document libraries, sites, and pages. Amazon Quick agents can then search and answer questions about the content.

# Microsoft SharePoint action integration
<a name="sharepoint-action-integration"></a>

Use the Microsoft SharePoint action connector to manage lists, items, files, and Excel workbooks directly in Amazon Quick through natural language.

Setting up this integration involves two steps. First, you register an application in Microsoft Entra and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Entra app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="sharepoint-action-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with SharePoint access.
+ Access to the [Microsoft Entra admin center](https://entra.microsoft.com/) with at least Application Developer permissions.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure Microsoft Entra
<a name="sharepoint-entra-setup"></a>

Before you configure Amazon Quick, create an app registration in Microsoft Entra. Complete all of the following steps in Entra before moving to the Amazon Quick console.

For more information about app registrations, see [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft documentation.

### Register the application
<a name="entra-app-registration"></a>

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/).

1. In the left navigation, choose **Entra ID**, then choose **App registrations**.

1. Choose **New registration**.

1. For **Name**, enter a descriptive name for your integration.

1. For **Supported account types**, choose **Accounts in this organizational directory only**.

1. For **Redirect URI**, select **Web** and enter `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *\$1region\$1* with the AWS Region where your Amazon Quick instance is deployed.

1. Choose **Register**.

1. On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need these values for the Amazon Quick configuration.

### Create a client secret
<a name="entra-client-secret"></a>

Amazon Quick needs a client secret to authenticate with Microsoft Entra. This secret acts as a password for the app registration.

1. From your app registration, choose **Certificates & secrets**.

1. Choose **New client secret**.

1. Enter a description and choose an expiration period.

1. Choose **Add**.

1. Copy the **Value** immediately. This value is only displayed once.

**Important**  
Copy the secret **Value**, not the Secret ID. The Value is the longer string used for authentication.

### Configure API permissions
<a name="sharepoint-entra-api-permissions"></a>

Microsoft Graph supports two permission types for this integration. Delegated permissions allow the app to act on behalf of a signed-in user. Application permissions allow the app to act without a signed-in user. For more information, see [Overview of Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-overview) in the Microsoft documentation.

1. From your app registration, choose **API permissions**.

1. Choose **Add a permission**, then choose **Microsoft Graph**.

1. Choose **Delegated permissions** or **Application permissions** based on your authentication method, and add the permissions from the appropriate table below.

1. Choose **Grant admin consent for [your tenant name]** to approve the permissions.

**For user authentication (delegated permissions):**

Add the following as Delegated permissions in your Entra app registration. For the full permissions reference, see [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) in the Microsoft documentation.


**SharePoint action integration – delegated permissions**  

| Permission | Description | 
| --- | --- | 
| Files.ReadWrite | Allows the app to read, create, update, and delete the signed-in user's files. | 
| Sites.ReadWrite.All | Allows the application to edit or delete documents and list items in all site collections on behalf of the signed-in user. | 
| offline\$1access | Allows the app to refresh access tokens without requiring the user to sign in again. This reduces how often users need to re-authenticate. | 

**For service authentication (application permissions):**

Add the following as Application permissions in your Entra app registration.


**SharePoint action integration – application permissions**  

| Permission | Description | 
| --- | --- | 
| Sites.ReadWrite.All | Allows the app to create, read, update, and delete documents and list items in all site collections without a signed-in user. | 

**Important**  
With service authentication, all actions execute as the service account. Any user with access to this integration can perform actions across all site collections that the service account can access. Scope the application permissions appropriately for your organization's security requirements.

### Record your credentials
<a name="entra-record-credentials"></a>

Before leaving the Microsoft Entra admin center, confirm you have the following values. You need them for the Amazon Quick configuration.


**Required credentials from Microsoft Entra**  

| Value | Where to find it | 
| --- | --- | 
| Application (client) ID | App registration overview page | 
| Directory (tenant) ID | App registration overview page | 
| Client secret value | Certificates & secrets page | 

## Set up the integration in Amazon Quick
<a name="sharepoint-action-integration-setup"></a>

After you complete the Entra configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Microsoft SharePoint** and choose the Add (plus "\$1") button.

1. Choose the **Actions** tab.

1. Choose **Perform actions in Microsoft SharePoint**.

1. Fill in the integration details:
   + **Name** – Descriptive name for your SharePoint integration.
   + **Description** (Optional) – Purpose of the integration.

1. Choose your connection type and fill in the connection settings:

   1. For **User authentication (OAuth)**, configure the following fields:
      + **Base URL** – `https://graph.microsoft.com/v1.0`
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Auth URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
      + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

   1. For **Service authentication**, configure the following fields:
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Scope** – `.default`

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

## Available actions
<a name="sharepoint-integration-task-actions"></a>

After you set up the integration, the following actions are available.


**Microsoft SharePoint available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Lists and items | View items | Get the collection of items in a list. | 
| Lists and items | Get Item | Returns the metadata for an item in a list. | 
| Lists and items | Get List | Returns the metadata for a list. | 
| Lists and items | Update Item | Update the properties on a list item. | 
| Lists and items | Delete Item | Removes an item from a list. | 
| Files | Upload File | Upload a new file or update an existing file. Supports files up to 250 MB. | 
| Files | Search Site Drive Items | Search the hierarchy of items matching a query. | 
| Excel workbooks | List Sheets | Retrieve a list of worksheet objects. | 
| Excel workbooks | Add Sheet | Add a new worksheet to the workbook. | 
| Excel workbooks | Read Sheet | Retrieve the properties of a worksheet object. | 
| Excel workbooks | Update Sheet | Update the properties of a worksheet object. | 
| Excel workbooks | Delete Sheet | Delete the worksheet from the workbook. | 
| Excel workbooks | Read Cell | Get the value of a single cell by row and column number. | 
| Excel workbooks | Write Cell | Set the value of a single cell by row and column number. | 
| Excel workbooks | Read Range | Get the values of a range. | 
| Excel workbooks | Write Range | Update the values of a range. | 
| Excel workbooks | Clear Range | Clear range values, format, fill, and border. | 
| Excel workbooks | Delete Range | Delete the cells associated with the range. | 
| Excel workbooks | Get Used Range | Get the smallest range that encompasses cells with a value or formatting. | 

## Manage and troubleshoot
<a name="entra-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="entra-troubleshooting-auth"></a>
+ **Incorrect app registration** – Verify the app registration in Microsoft Entra includes the required API permissions and that admin consent has been granted.
+ **Expired client secret** – Check if the client secret has expired in **Certificates & secrets** and generate a new one if needed.
+ **Incorrect redirect URI** – Verify the redirect URI in Microsoft Entra matches `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`.

### Common error messages
<a name="entra-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions. Contact your administrator to verify and grant appropriate permissions.
+ **`AADSTS50020: User account from identity provider does not exist in tenant`** – The user account is not configured in the correct Microsoft Entra tenant. Verify the user account exists in the tenant that matches the Directory (tenant) ID in your app registration.

# Microsoft SharePoint knowledge base integration
<a name="sharepoint-knowledge-base"></a>

Use the Microsoft SharePoint knowledge base integration to index SharePoint content so that Amazon Quick agents can search and answer questions about it.

Amazon Quick uses a pre-registered multi-tenant application to connect to SharePoint for knowledge bases. You do not need to create an app registration. When a user first connects, Microsoft presents a consent dialog. An administrator can grant consent on behalf of the entire organization, or individual users can consent for themselves.

## Before you begin
<a name="sharepoint-kb-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with SharePoint access.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).
+ Your Microsoft administrator may need to grant organizational consent before users can create a SharePoint knowledge base. Administrators can grant organization-wide consent by signing in and choosing **Consent on behalf of your organization** during the integration creation flow.

**Note**  
When an administrator grants organizational consent, Microsoft Entra automatically creates an Enterprise Application (service principal) in your tenant. You can disable or delete this service principal at any time from **Enterprise applications** in the Microsoft Entra admin center, which immediately revokes all access.

## Permissions granted during consent
<a name="sharepoint-kb-permissions"></a>


**SharePoint knowledge base – permissions**  

| Permission | API | Description | 
| --- | --- | --- | 
| Files.Read.All | Microsoft Graph | Allows the app to read all files that the user can access. | 
| Notes.Read.All | Microsoft Graph | Allows the app to read all OneNote notebooks that the user can access. | 
| User.Read | Microsoft Graph | Allows users to sign in and allows the app to read the signed-in user's profile. | 
| Sites.Read.All | Microsoft Graph | Allows the app to read documents and list items in all site collections. | 
| offline\$1access | Microsoft Graph | Allows the app to maintain access when the user is not actively signed in. | 
| AllSites.Read | Office 365 SharePoint Online | Allows the app to read items in all site collections. | 

## Set up the knowledge base integration
<a name="sharepoint-kb-setup"></a>

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Microsoft SharePoint** and choose the Add (plus "\$1") button.

1. In the **Create SharePoint knowledge base** dialog, under **Connected account**, choose **Sign in to SharePoint** and complete the Microsoft sign-in and consent flow.

1. Under **Create knowledge base**, enter a name and an optional description for your knowledge base.

1. In the **Content** section, choose **Add content** and select the SharePoint pages, files, or folders you want to index.

1. Choose **Create**.

## Supported content types
<a name="sharepoint-kb-content-types"></a>
+ **Document libraries:** Word, Excel, PowerPoint, PDF, OneNote (.one)
+ **Media files:** MP3, MP4, MOV, WMV
+ **Site pages and wiki pages**

## Access controls
<a name="sharepoint-kb-access-controls"></a>

**Important**  
When Amazon Quick indexes SharePoint content, it does not sync access control lists (ACLs) from SharePoint. All indexed content is accessible to any user who has access to the knowledge base in Amazon Quick, regardless of their permissions in SharePoint. Review which content you include when creating a knowledge base.

## Manage and troubleshoot
<a name="sharepoint-kb-management"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

For general knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).

### SharePoint-specific issues
<a name="sharepoint-troubleshooting-kb-consent"></a>
+ **Admin consent required** – Some organizations require an administrator to grant consent before individual users can connect. An administrator must sign in and choose **Consent on behalf of your organization** during the consent flow.
+ **Enterprise Application disabled** – If the service principal was previously disabled in **Enterprise applications** in the Microsoft Entra admin center, re-enable it to restore access.
+ **SharePoint throttling** – SharePoint may throttle requests during high usage periods. Retry the sync during off-peak hours.

# Microsoft Teams integration
<a name="microsoft-teams-integration"></a>

Use the Microsoft Teams action connector to send messages, manage channels, schedule meetings, and manage team collaboration directly in Amazon Quick through natural language.

Setting up this integration involves two steps. First, you register an application in Microsoft Entra and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Entra app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="msteams-integration-prerequisites"></a>

Make sure you have the following before you set up the integration.
+ A Microsoft 365 account with Teams access.
+ Access to the [Microsoft Entra admin center](https://entra.microsoft.com/) with at least Application Developer permissions.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure Microsoft Entra
<a name="msteams-entra-setup"></a>

Before you configure Amazon Quick, create an app registration in Microsoft Entra. Complete all of the following steps in Entra before moving to the Amazon Quick console.

For more information about app registrations, see [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft documentation.

### Register the application
<a name="entra-app-registration"></a>

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/).

1. In the left navigation, choose **Entra ID**, then choose **App registrations**.

1. Choose **New registration**.

1. For **Name**, enter a descriptive name for your integration.

1. For **Supported account types**, choose **Accounts in this organizational directory only**.

1. For **Redirect URI**, select **Web** and enter `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`. Replace *\$1region\$1* with the AWS Region where your Amazon Quick instance is deployed.

1. Choose **Register**.

1. On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need these values for the Amazon Quick configuration.

### Create a client secret
<a name="entra-client-secret"></a>

Amazon Quick needs a client secret to authenticate with Microsoft Entra. This secret acts as a password for the app registration.

1. From your app registration, choose **Certificates & secrets**.

1. Choose **New client secret**.

1. Enter a description and choose an expiration period.

1. Choose **Add**.

1. Copy the **Value** immediately. This value is only displayed once.

**Important**  
Copy the secret **Value**, not the Secret ID. The Value is the longer string used for authentication.

### Configure API permissions
<a name="msteams-entra-api-permissions"></a>

Microsoft Graph supports two permission types for this integration. Delegated permissions allow the app to act on behalf of a signed-in user. Application permissions allow the app to act without a signed-in user. For more information, see [Overview of Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-overview) in the Microsoft documentation.

1. From your app registration, choose **API permissions**.

1. Choose **Add a permission**, then choose **Microsoft Graph**.

1. Choose **Delegated permissions** or **Application permissions** based on your authentication method, and add the permissions from the appropriate table below.

1. Choose **Grant admin consent for [your tenant name]** to approve the permissions.

**For user authentication (delegated permissions):**

Add the following as Delegated permissions in your Entra app registration. For the full permissions reference, see [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) in the Microsoft documentation.


**Teams action integration – delegated permissions**  

| Permission | Description | 
| --- | --- | 
| Chat.ReadWrite | Allows the app to read and write the signed-in user's chat messages. | 
| ChatMessage.Send | Allows the app to send chat messages on behalf of the signed-in user. | 
| Team.ReadBasic.All | Allows the app to read the names and descriptions of teams on behalf of the signed-in user. | 
| Channel.ReadBasic.All | Allows the app to read channel names and descriptions on behalf of the signed-in user. | 
| Channel.Create | Allows the app to create channels in any team on behalf of the signed-in user. | 
| ChannelMessage.Read.All | Allows the app to read all channel messages on behalf of the signed-in user. | 
| ChannelMessage.Send | Allows the app to send messages in channels on behalf of the signed-in user. | 
| ChannelMember.ReadWrite.All | Allows the app to add and remove members from channels on behalf of the signed-in user. | 
| TeamMember.ReadWrite.All | Allows the app to add and remove members from all teams on behalf of the signed-in user. | 
| User.Read.All | Allows the app to read the full set of profile properties of all users on behalf of the signed-in user. | 
| OnlineMeetings.ReadWrite | Allows the app to read and create online meetings on behalf of the signed-in user. | 
| OnlineMeetingTranscript.Read.All | Allows the app to read all transcripts of online meetings on behalf of the signed-in user. | 
| Calendars.ReadWrite | Allows the app to read and write events in user calendars on behalf of the signed-in user. | 
| offline\$1access | Allows the app to refresh access tokens without requiring the user to sign in again. This reduces how often users need to re-authenticate. | 

**For service authentication (application permissions):**

Add the following as Application permissions in your Entra app registration.


**Teams action integration – application permissions**  

| Permission | Description | 
| --- | --- | 
| Chat.Read.All | Allows the app to read all chat messages in your organization without a signed-in user. | 
| Chat.Send | Allows the app to send chat messages without a signed-in user. | 
| Team.ReadBasic.All | Allows the app to read the names and descriptions of all teams without a signed-in user. | 
| Channel.ReadBasic.All | Allows the app to read all channel names and descriptions without a signed-in user. | 
| ChannelMessage.Read.All | Allows the app to read all channel messages without a signed-in user. | 
| ChannelMessage.Send | Allows the app to send messages to any channel without a signed-in user. | 
| ChannelMember.ReadWrite.All | Allows the app to add and remove members from all channels without a signed-in user. | 
| TeamMember.ReadWrite.All | Allows the app to add and remove members from all teams without a signed-in user. | 
| User.Read.All | Allows the app to read the full set of profile properties of all users without a signed-in user. | 
| OnlineMeetingTranscript.Read.All | Allows the app to read all transcripts of online meetings without a signed-in user. | 

**Important**  
With service authentication, all actions execute as the service account. Any user with access to this integration can perform actions across all teams and channels that the service account can access. Scope the application permissions appropriately for your organization's security requirements.

### Record your credentials
<a name="entra-record-credentials"></a>

Before leaving the Microsoft Entra admin center, confirm you have the following values. You need them for the Amazon Quick configuration.


**Required credentials from Microsoft Entra**  

| Value | Where to find it | 
| --- | --- | 
| Application (client) ID | App registration overview page | 
| Directory (tenant) ID | App registration overview page | 
| Client secret value | Certificates & secrets page | 

## Set up the integration in Amazon Quick
<a name="msteams-action-connector-setup"></a>

After you complete the Entra configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. Choose **Microsoft Teams** and choose the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** – Descriptive name for your Teams integration.
   + **Description** (Optional) – Purpose of the integration.

1. Choose your connection type and fill in the connection settings:

   1. For **User authentication (OAuth)**, configure the following fields:
      + **Base URL** – `https://graph.microsoft.com/v1.0`
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Auth URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
      + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

   1. For **Service authentication**, configure the following fields:
      + **Client ID** – Application (client) ID from your Entra app registration.
      + **Client Secret** – Client secret value from your Entra app registration.
      + **Token URL** – `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
      + **Scope** – `.default`

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

## Available actions
<a name="msteams-integration-actions"></a>

After you set up the integration, the following actions are available.


**Microsoft Teams available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Chats | List Chats | View your chat conversations. | 
| Chats | Create Chat | Start a new chat conversation. | 
| Chats | Send Chat Message | Send a message in a chat. | 
| Teams | List Teams | View teams you're a member of. | 
| Teams | List Team Members | View members of a team. | 
| Teams | Add Team Member | Add a member to a team. | 
| Channels | List Channels | View channels in a team. | 
| Channels | Create Channel | Create a new channel in a team. | 
| Channels | List Channel Messages | View messages in a channel. | 
| Channels | Send Channel Message | Post a message to a channel. | 
| Channels | List Channel Members | View members of a channel. | 
| Channels | Add Channel Member | Add a member to a channel. | 
| Users | List Users | View users in your organization. | 
| Meetings | List Online Meetings | View your scheduled online meetings. | 
| Meetings | Create Online Meeting | Schedule a new online meeting. | 
| Meetings | List Meeting Transcripts | View transcripts from meetings. | 
| Calendar | List Calendar Events | View events on your calendar. | 
| Calendar | Create Calendar Event | Create a new calendar event. | 

## Manage and troubleshoot
<a name="entra-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="entra-troubleshooting-auth"></a>
+ **Incorrect app registration** – Verify the app registration in Microsoft Entra includes the required API permissions and that admin consent has been granted.
+ **Expired client secret** – Check if the client secret has expired in **Certificates & secrets** and generate a new one if needed.
+ **Incorrect redirect URI** – Verify the redirect URI in Microsoft Entra matches `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`.

### Common error messages
<a name="entra-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`** – The authenticated user does not have the required permissions. Contact your administrator to verify and grant appropriate permissions.
+ **`AADSTS50020: User account from identity provider does not exist in tenant`** – The user account is not configured in the correct Microsoft Entra tenant. Verify the user account exists in the tenant that matches the Directory (tenant) ID in your app registration.

# New Relic integration
<a name="newrelic-integration"></a>

With the New Relic action connector, you can access the New Relic observability platform directly in Amazon Quick through natural language. You can investigate incidents, analyze application performance, query telemetry data, and generate reports without leaving Amazon Quick.

New Relic is available as a built-in connector in Amazon Quick. To set up this integration, complete the following two steps. First, prepare your New Relic account with the required access. Then, create the integration in Amazon Quick and authenticate with your New Relic credentials. This integration uses OAuth 2.0 user authentication. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Prerequisites
<a name="newrelic-integration-prerequisites"></a>

Before you set up the integration, make sure that you have the following resources and access.
+ An active New Relic account with the required permissions and access. For information about account requirements and access configuration, see [New Relic AI MCP](https://docs.newrelic.com/docs/agentic-ai/mcp/overview/) in the New Relic documentation.
+ For information about subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Verify your New Relic account
<a name="newrelic-account-setup"></a>

Before you configure Amazon Quick, verify that your New Relic account meets the following requirements.
+ Your New Relic account is active and you can sign in to [login.newrelic.com](https://login.newrelic.com).
+ The entities and data that you want to query are accessible to your account.

## Set up the integration in Amazon Quick
<a name="newrelic-integration-setup"></a>

After you verify your New Relic account access, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose the **Actions** tab.

1. Under **Set up a new app integration for Actions**, find **New Relic** and choose the Add (plus "\$1") button.

1. In the **Create integration** dialog, enter the following fields:
   + **Name** – A descriptive name for your New Relic integration.
   + **Description** (Optional) – Notes about how you plan to use this connection.
   + **Connection type** – Choose **Public network**.

1. Choose **Create and continue**.

1. On the integration detail page, choose **Sign in** and authenticate with your New Relic account credentials. This step authorizes Amazon Quick to access New Relic on behalf of the authenticated user.

1. (Optional) Choose the users to share the integration with.

1. Choose **Done**.

The integration appears in the **Existing actions** panel with a status of **Available**.

## Available actions
<a name="newrelic-integration-actions"></a>

After you set up the integration, you can use the following actions.


**New Relic available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Incident analysis | Generate Alert Insights Report | Generates an alert intelligence analysis report for a specific issue. Provides insights into root cause, impact, and recommended actions. | 
| Incident analysis | Generate User Impact Report | Analyzes affected entities and their relationships to quantify end-user impact through metrics like affected user count, degraded services, and severity indicators. | 
| Incident analysis | Search Incident | Retrieves alert incident events with flexible filtering by issue ID, entity GUID, or policy and condition pair. | 
| Incident analysis | List Recent Issues | Lists all recent issues (last 24 hours) for a specified account. | 
| Performance analysis | Analyze Transactions | Identifies slow and error-prone transactions, their traces, common transaction paths, and error distributions. | 
| Performance analysis | Analyze Golden Metrics | Analyzes key health indicators (throughput, response time, error rate, and saturation) across application and infrastructure entities. | 
| Performance analysis | Analyze Deployment Impact | Compares metrics before and after a deployment to identify regressions or improvements. | 
| Performance analysis | Analyze Kafka Metrics | Analyzes Kafka metrics including consumer lag, producer throughput, message latency, partition balance, and resource utilization. | 
| Performance analysis | Analyze Threads | Analyzes thread metric data including thread state, CPU usage, and memory consumption. Provides language-specific insights for applications. | 
| Performance analysis | List Garbage Collection Metrics | Retrieves garbage collection and memory metrics for a given entity. Use this action to identify whether GC issues are affecting application performance. | 
| Log analysis | Analyze Entity Logs | Analyzes application logs to identify error patterns, anomalous behavior, and recurring issues within a specified time window. | 
| Log analysis | List Recent Logs | Retrieves recent logs for a specified account and entity GUID. | 
| Error analysis | List Entity Error Groups | Retrieves error groups from the Errors Inbox within a time window. Groups errors by message and prioritizes by user impact. | 
| Queries | Natural Language to NRQL Query | Converts a natural language request into a New Relic Query Language (NRQL) query, runs it against New Relic, and returns the results. | 
| Queries | Execute NRQL Query | Runs an NRQL query directly against New Relic telemetry data. | 
| Entities | Get Entity | Retrieves entities by GUID or searches by name pattern. | 
| Entities | List Related Entities | Retrieves entities that are related to a given entity GUID. | 
| Entities | Search Entity with Tag | Searches for entities by using tag key and value pairs. | 
| Entities | List Entity Types | Lists the complete catalog of New Relic entity types with their domain, type, and metric definitions. | 
| Alerts | List Alert Policies | Lists alert policies for a specified account, with optional filtering by policy name. | 
| Alerts | List Alert Conditions | Retrieves alert condition details for a specific alert policy. | 
| Dashboards | List Dashboards | Lists all dashboards for a New Relic account. | 
| Dashboards | Get Dashboard | Retrieves detailed information for a specific dashboard by entity GUID. | 
| Change tracking | List Change Events | Retrieves a history of change events such as deployments, configuration changes, and other tracked activities for an entity. | 
| Monitoring | List Synthetic Monitors | Lists synthetic monitors that check service availability and performance from multiple geographic locations. | 
| Account | List Available New Relic Accounts | Lists all New Relic account IDs that are accessible to the authenticated user. | 
| Utilities | Convert Time Period to Epoch Ms | Converts a natural language time period to epoch milliseconds for use with time-based queries. | 

**Note**  
The actions that you can use depend on the permissions that are configured in your New Relic account and the entities that are accessible to the authenticated user.

## Manage and troubleshoot
<a name="newrelic-integration-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="newrelic-troubleshooting-auth"></a>
+ **Sign-in fails** – Verify that your New Relic account is active and that you can sign in to [login.newrelic.com](https://login.newrelic.com) directly. If your organization uses single sign-on (SSO), confirm that your identity provider is configured correctly.
+ **MCP server access denied** – Verify that your user has the required permissions to access the New Relic MCP server. For information about access requirements, see [New Relic AI MCP](https://docs.newrelic.com/docs/agentic-ai/mcp/overview/) in the New Relic documentation.

# Notion integration
<a name="notion-integration"></a>

With Notion integration in Amazon Quick, you can manage pages, databases, and collaborative workspaces through MCP server connectivity. This integration provides action capabilities for knowledge management and content organization operations.

## What you can do
<a name="notion-integration-capabilities"></a>

Notion integration provides action connector capabilities through MCP server connectivity:
+ Create and edit pages and documents
+ Manage databases and structured content
+ Organize content with tags and properties
+ Share pages and collaborate with team members
+ Search across workspaces and content
+ Manage workspace permissions and access

## Available tools
<a name="notion-integration-tools"></a>

The Notion MCP server typically provides these tools:
+ `create_page` - Create new pages
+ `update_page` - Update page content
+ `get_page` - Retrieve page information
+ `search_pages` - Search for pages
+ `create_database` - Create new databases
+ `query_database` - Query database entries
+ `create_database_entry` - Add database entries
+ `update_database_entry` - Update database entries

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official Notion documentation and MCP server repository.

## Setting up Notion integration
<a name="notion-integration-setup"></a>

Notion integration uses MCP server connectivity to provide action capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ Notion account with appropriate workspace permissions
+ Notion integration token for API access

## Compatibility
<a name="notion-integration-compatibility"></a>

Notion integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# OpenAPI Specification integration
<a name="openapi-integration"></a>

With OpenAPI Specification integration, you can create custom integrations based on OpenAPI schemas. This allows you to connect to any API that provides an OpenAPI specification. This integration supports action execution only and requires Amazon Quick Pro tier or higher.

## What you can do
<a name="openapi-integration-capabilities"></a>

OpenAPI Specification integration provides schema-based connectivity to help you work with custom APIs.

**Action connector**  
Perform actions based on OpenAPI specifications. Execute API calls, manage resources, and interact with custom services through dynamically generated actions based on the provided schema.

**Schema-based configuration**  
Import OpenAPI specifications to automatically generate available actions and actions. Support for JSON schema validation and parameter mapping.

## Before you begin
<a name="openapi-integration-prerequisites"></a>

Before you set up OpenAPI Specification integration, make sure you have the following:
+ OpenAPI specification (version 3.0.0 or higher) for your target API.
+ API authentication credentials (API key, OAuth, or other).
+ Amazon Quick Author or higher.
+ API documentation and endpoint access.

## Prepare OpenAPI specification and authentication
<a name="openapi-integration-preparation"></a>

Before setting up the integration in Amazon Quick, prepare your OpenAPI specification and authentication credentials. Your OpenAPI specification must meet specific requirements for successful integration.

### Basic requirements
<a name="openapi-integration-basic-requirements"></a>

Your OpenAPI specification must meet these basic requirements.
+ **OpenAPI version** - Version 3.0.0 or higher is required.
+ **File format** - JSON format only (application/json).
+ **File size limit** - Maximum 1MB for the entire OpenAPI specification.
+ **Operation limit** - Minimum 1 and maximum 100 API operations per connector.

### Required schema fields
<a name="openapi-integration-required-fields"></a>

Your OpenAPI specification must include these required sections.

**openapi**  
The OpenAPI version being used (must be "3.0.0" or higher).

**info**  
Service information including title, description, and version.

**servers**  
Base URL and server information for API connectivity.

**paths**  
API endpoint definitions with HTTP methods and operations.

### Supported authentication schemes
<a name="openapi-integration-authentication-schemes"></a>

Prepare authentication credentials based on the supported authentication methods in OpenAPI specifications.

**OAuth 2.0**  
Supports both Authorization Code Grant and Client Credentials Grant flows. Requires authorizationUrl, tokenUrl, and scopes definitions in the security scheme.

**API Key**  
API key authentication passed in query parameters or headers.

**No authentication**  
Default option when no security schemes are defined in the specification.

**Note**  
Unsupported authentication schemes in the OpenAPI specification will be ignored, and the connector will default to no authentication.

## Set up OpenAPI Specification integration
<a name="openapi-integration-setup"></a>

After preparing your OpenAPI specification and authentication credentials, follow these steps to create your OpenAPI Specification integration.

1. In the Amazon Quick console, choose **Integrations**.

1. Click **Add** (plus "\$1" button).

1. On the Add Schema page, select **Import Schema** and choose a schema to import.

1. Select **Next**.

1. Fill in the integration details including name and description.

1. Review the available actions generated from your OpenAPI specification.

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

### Expected results
<a name="openapi-integration-setup-results"></a>

After successful setup, your OpenAPI Specification integration appears in the integrations list with dynamically generated actions based on your schema. The integration is available for use in Amazon Quick workflows, automations, and AI agents, with tasks corresponding to the endpoints defined in your OpenAPI specification.

## Format and pattern requirements
<a name="openapi-integration-format-requirements"></a>

Your OpenAPI specification must follow these format requirements.
+ **Path patterns** - Must follow the pattern: `^/[^/]*(/[^/]*)*$` and begin with a forward slash (/).
+ **Operation IDs** - Must follow the pattern: `^[a-zA-Z0-9_ ]{1,256}$`.
+ **Descriptions** - Required for all operations and parameters, maximum 5000 characters.
+ **Content type** - Only application/json is supported for request and response bodies.

## Unsupported features
<a name="openapi-integration-unsupported-features"></a>

The following OpenAPI features are not supported and will cause validation errors.
+ **Array types** - Schemas with array types (for example, `{"type": "array", "items": {"string"}}`) are not supported.
+ **Composition keywords** - allOf, oneOf, anyOf, and not keywords are not supported.
+ **Circular references** - Circular or cyclic references (\$1ref inside of \$1ref) are not supported.
+ **Complex nested structures** - Avoid deeply nested object structures when possible.

## Schema best practices
<a name="openapi-integration-best-practices"></a>

Follow these best practices when creating your OpenAPI specification.

### Write effective descriptions
<a name="openapi-integration-description-guidelines"></a>

Use these guidelines to write clear and helpful descriptions.
+ **Operation descriptions** - Describe what the operation does, when to use it, and how it behaves.
+ **Parameter descriptions** - Concisely explain the parameter's purpose and impact on operation behavior.
+ **Self-contained content** - Ensure descriptions provide sufficient guidance without external references.
+ **Dependency clarity** - Make dependencies between operations explicit in descriptions.
+ **Operation references** - Use operationId when referring to other operations, not API paths.

### Parameter structure recommendations
<a name="openapi-integration-parameter-structure"></a>

Structure your parameters for optimal usability.
+ **Flatten complex objects** - Instead of nested objects, use separate parameters (for example, start\$1date, start\$1time, end\$1date, end\$1time).
+ **Use standard formats** - Use standard format values like "date-time" or "date" for ISO-8601 dates and times.
+ **Clear parameter names** - Use descriptive parameter names that clearly indicate their purpose.
+ **Required field marking** - Properly mark parameters as required or optional based on API behavior.

## Supported extensions
<a name="openapi-integration-extensions"></a>

We support custom OpenAPI extensions to enhance the user experience.

**x-amzn-form-display-name**  
Use at the parameter level to override the default field name displayed in confirmation forms. Currently supported for request body parameters only.  

```
"x-amzn-form-display-name": "User Name"
```

**x-amzn-operation-type**  
Define whether an operation should be treated as "read" or "write". By default, GET methods are "read" operations and all other HTTP methods are "write" operations.  

```
"x-amzn-operation-type": "read"
```

## Schema validation and error handling
<a name="openapi-integration-validation-process"></a>

When you upload an OpenAPI specification, we perform comprehensive validation.
+ **File size validation** - Ensures the specification doesn't exceed 1MB.
+ **Operation count validation** - Verifies between 1-100 operations are defined.
+ **Schema structure validation** - Checks for required fields and proper formatting.
+ **Security scheme validation** - Validates supported authentication methods.
+ **Content type validation** - Ensures only application/json is used.

Validation errors appear below the schema editor and must be resolved before the integration can be created. Common validation issues include:
+ Missing required fields (openapi, info, servers, paths).
+ Invalid path patterns or operation IDs.
+ Unsupported schema features (arrays, composition keywords).
+ Missing or overly long descriptions.
+ Circular references in schema definitions.

## Manage OpenAPI Specification integration
<a name="openapi-integration-management"></a>

After you create your OpenAPI Specification integration, you can manage it through several options.

### Share integration
<a name="openapi-integration-sharing"></a>

You can share OpenAPI Specification action connectors with other users in your organization.

1. From the OpenAPI integration details page, choose **Share**.

1. Configure sharing options:
   + **Share with specific users** - Enter user names or email addresses.
   + **Share with organization** - Make available to all users in your organization.

1. Set permission levels for shared access.

1. Choose **Share integration** to apply the sharing settings.

### Delete integration
<a name="openapi-integration-deletion"></a>

Follow these steps to permanently remove your OpenAPI integration.

1. From the OpenAPI integration details page, choose **Delete**.

1. Review the deletion impact, including any workflows or automations using this integration.

1. Type the integration name to confirm deletion.

1. Choose **Delete integration** to permanently remove it.

## Troubleshoot OpenAPI Specification integration
<a name="openapi-integration-troubleshooting"></a>

Use these troubleshooting tips to resolve common OpenAPI Specification integration issues.

Schema validation errors  
Ensure your OpenAPI specification follows the correct format and includes all required fields. Use an OpenAPI validator to check your schema before importing.

No tasks generated  
Verify that your OpenAPI specification includes path definitions with HTTP methods and operation IDs. Actions are generated based on the operations defined in your schema.

Authentication failures  
Check that the authentication scheme defined in your OpenAPI specification matches the actual API requirements and that credentials are properly configured.

Action execution failures  
Review the action parameters and ensure they match the parameter definitions in your OpenAPI specification, including required fields and data types.

# PagerDuty integration
<a name="pagerduty-integration"></a>

Connect Amazon Quick to your PagerDuty system to manage incidents, alerts, schedules, and on-call rotations. You can perform these actions without leaving your Amazon Quick environment. This integration requires Amazon Quick Pro tier or higher.

## What you can do
<a name="pagerduty-integration-capabilities"></a>

With PagerDuty integration, you can perform actions within your PagerDuty systems through the PagerDuty API.

**Action connector**  
Create, update, and manage incidents, alerts, schedules, and escalation policies through the PagerDuty API.

## Set up PagerDuty integration
<a name="pagerduty-integration-setup"></a>

Follow these steps to connect Amazon Quick to your PagerDuty system.

1. In the Amazon Quick console, choose **Integrations**.

1. Click the Add (plus "\$1") button.

1. Choose **PagerDuty** from the integration options.

1. Fill in the integration details:
   + **Name** - Enter a descriptive name for your PagerDuty integration.
   + **Description** (Optional) - Describe the purpose of this integration.

1. Choose your connection type:
   + **User authentication** - OAuth for individual user access to PagerDuty.
   + **Service authentication** - API key-based authentication for service-to-service access.

1. Fill in the connection settings based on your selected authentication method (either user or service).

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

### What happens next
<a name="pagerduty-integration-setup-results"></a>

After you complete the setup, your PagerDuty integration appears in the integrations list. You can use it in Amazon Quick workflows, automations, and AI agents.

## Manage PagerDuty integrations
<a name="pagerduty-integration-management"></a>

You can perform these management tasks for your PagerDuty integrations:
+ **Edit integration** - Update authentication settings or PagerDuty configuration.
+ **Share integration** - Make the integration available to other users in your organization.
+ **Delete integration** - Remove the integration and revoke authentication.

# PagerDuty Advance integration
<a name="pagerduty-advance-integration"></a>

Connect Amazon Quick to the PagerDuty Advance MCP and use AI to securely contact PagerDuty Advance. Teams can access incident context, history, and runbooks from the SRE agent, query the Insights agent for proactive ways to improve, or alter on-call coverage with Shift agent from their AI-enabled platform of choice.

## What you can do
<a name="pagerduty-advance-integration-capabilities"></a>

The PagerDuty Advance integration enables you to:
+ Access incident context, history, and runbooks for active incident response
+ Perform root cause analysis and technical troubleshooting
+ Query on-call schedules and manage shift coverage
+ Analyze historical trends and performance metrics (MTTR, MTTA)
+ Generate insights for service reliability and team performance
+ Collaborate with PagerDuty Advance agents from your AI-enabled platform of choice

## Available tools
<a name="pagerduty-advance-integration-tools"></a>

The MCP server for PagerDuty Advance typically provides these tools:
+ `analytics_agent_tool` - Runs an analytics agent for historical reporting and trend analysis, including performance metrics (MTTR, MTTA), team benchmarking, service reliability statistics, and executive KPI tracking.
+ `schedules_agent_tool` - Runs a schedules agent for on-call and scheduling information, including shift assignments, schedule configurations, escalation policies, user availability conflicts, and coverage management.
+ `sre_agent_tool` - Runs an SRE agent for incident response and technical troubleshooting, including active incident triage, root cause analysis, diagnostics, alert explanations, change event analysis, and runbook generation.

**Note**  
The specific tools and capabilities available through this MCP server may change over time. For the most current information about supported tools, features, and implementation details, check the official PagerDuty documentation and MCP server repository.

## Setting up PagerDuty Advance integration
<a name="pagerduty-advance-integration-setup"></a>

PagerDuty Advance integration uses MCP server connectivity to provide agent capabilities. For detailed setup instructions, see [Model Context Protocol (MCP) integration](mcp-integration.md).

You'll need:
+ PagerDuty account with appropriate permissions
+ PagerDuty API credentials (Client ID and Client Secret)
+ Amazon Quick with MCP integration enabled

## Compatibility
<a name="pagerduty-advance-integration-compatibility"></a>

PagerDuty Advance integration supports:
+ **Chat Agents:** Yes
+ **Flows:** Yes
+ **Knowledge Base:** No

# REST API Connection integration
<a name="rest-api-integration"></a>

With REST API Connection integration in Amazon Quick, you can perform actions with custom REST APIs and web services. This integration supports action execution only.

## What you can do
<a name="rest-api-integration-capabilities"></a>

With REST API Connection integration, you can perform actions with custom REST APIs and web services through the action connector.

**Action connector**  
Perform HTTP requests, retrieve data, and interact with APIs using flexible authentication options.

**Note**  
REST API Connection integration doesn't support data access or knowledge base creation. It's designed specifically for task execution and API interactions with custom web services.

## Before you begin
<a name="rest-api-integration-prerequisites"></a>

Before you set up REST API integration, make sure you have the following:
+ REST API endpoint with appropriate access permissions.
+ API authentication credentials (OAuth, API key, or other).
+ API documentation for the target web service.

## Prepare API endpoint and authentication
<a name="rest-api-integration-authentication"></a>

Before configuring the integration in Amazon Quick, prepare your REST API endpoint and authentication credentials. REST API Connection integration supports multiple authentication methods. Choose the method that matches your API requirements:

**User authentication (OAuth)**  
Gather the following information from your API provider:  
+ **Base URL** - REST API base URL.
+ **Client ID** - OAuth application client ID.
+ **Client Secret** - OAuth application client secret.
+ **Token URL** - OAuth token endpoint.
+ **Auth URL** - OAuth authorization endpoint.
+ **Redirect URL** - OAuth redirect URI.

**Service authentication (Service-to-service OAuth)**  
Gather the following information from your API provider:  
+ **Authentication type** - OAuth 2.0 client credentials grant flow for service-to-service authentication.
+ **Base URL** - REST API base URL.
+ **Client ID** - OAuth application client identifier for service authentication.
+ **Client secret** - OAuth application client secret for service authentication.
+ **Token URL** - OAuth token endpoint for obtaining access tokens.

### Custom headers and parameters
<a name="rest-api-custom-headers"></a>

You can use custom headers and parameters for flexible authentication and API interaction:
+ Custom authentication headers.
+ API version headers.
+ Content-Type specifications.
+ Custom query parameters.

## Set up REST API integration
<a name="rest-api-integration-setup"></a>

After you have prepared your API endpoint and authentication credentials, follow these steps to create your REST API integration:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **REST API Connection** from the integration options, and click the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** - Descriptive name for your REST API integration.
   + **Description** (Optional) - Purpose of the integration.

1. Choose your connection type:
   + **User authentication** - OAuth-based authentication for individual user access.
   + **Service authentication** - API key-based authentication for service access.

1. Fill in the connection settings based on your selected authentication method (either user or service).

1. Select **Next**.

1. Review the actions that are available.

1. Select **Create and continue**.

## Available task actions
<a name="rest-api-integration-actions"></a>

After you create your REST API integration, you can review the available actions for interacting with the REST API. Common REST API actions include:
+ HTTP GET requests for data retrieval.
+ HTTP POST requests for data creation.
+ HTTP PUT/PATCH requests for data updates.
+ HTTP DELETE requests for data removal.
+ Custom endpoint interactions.
+ JSON and XML data processing.
+ Query parameter and header management.

**Note**  
The specific actions available depend on the REST API endpoints and the authentication permissions configured for your integration.

## API configuration options
<a name="rest-api-integration-configuration"></a>

You can configure various aspects of your REST API integration to match your specific requirements.

### Endpoint configuration
<a name="rest-api-endpoint-configuration"></a>

Configure these endpoint settings:
+ Base URL and endpoint paths.
+ HTTP method specifications.
+ Request and response format handling.
+ Error handling and retry logic.

### Data handling
<a name="rest-api-data-handling"></a>

Configure how your integration processes different data formats:
+ JSON request and response processing.
+ XML data transformation.
+ Form data and multipart uploads.
+ Binary data handling.

## Manage REST API integrations
<a name="rest-api-integration-management"></a>

After you create your REST API integration, you can manage it using these options:
+ **Edit integration** - Update authentication settings, base URL, or API configuration.
+ **Share integration** - Make the integration available to other users in your organization.
+ **Monitor usage** - View integration activity and API call metrics.
+ **Review actions** - See the complete list of available REST API actions.
+ **Test endpoints** - Validate API connectivity and authentication.
+ **Delete integration** - Remove the integration and revoke associated authentication.

**Important**  
REST API integrations depend on the availability and configuration of the target web service. Changes to the API or authentication requirements may affect integration functionality.

# Salesforce integration
<a name="salesforce-integration"></a>

With Salesforce action connector in Amazon Quick, you can perform actions within Salesforce organizations, including managing records, querying data, and interacting with Salesforce APIs. This action connector supports task execution only and requires Amazon Quick Pro tier or higher.

## What you can do
<a name="salesforce-integration-capabilities"></a>

With Salesforce integration, you can perform actions within your Salesforce organizations through the action connector.

**Action connector**  
Create, update, and query Salesforce objects such as leads, accounts, contacts, and opportunities.

**Note**  
Salesforce integration doesn't support data access or knowledge base creation. It's designed specifically for task execution and API interactions with Salesforce objects.

## Before you begin
<a name="salesforce-integration-prerequisites"></a>

Before you set up Salesforce integration, make sure you have the following:
+ Salesforce organization with appropriate permissions.
+ Salesforce connected app or API access credentials.
+ Amazon Quick Author or higher.
+ Administrative access to configure OAuth applications (if using user authentication).

## Step 1: Set up Salesforce connected app
<a name="salesforce-connected-app-setup"></a>

**Note**  
Create a connected app in Salesforce. Do not create an external client app. External client apps are not compatible with this integration.

Create a connected app in Salesforce to enable OAuth authentication with Amazon Quick.

1. Sign in to your Salesforce account and navigate to the Setup page using the Setup icon in the top right.

1. In the Quick Find bar, enter **Apps**, then follow these steps:
   + Select **External Client Apps**
   + Select **Settings**
   + Under Settings, create a new connected app

1. Choose **New Connected App**.

1. Choose **Create a connected app**.

1. In the Basic Information section, enter the following required information:
   + **Connected App Name** - A descriptive name for your connected app.
   + **API Name** - A unique API name for your application.
   + **Contact Email** - Your contact email address.

1. In the OAuth Settings section, select the following checkboxes:
   + **Enable OAuth Settings**
   +  **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows** * (recommended)* 

      Enable this option to add an additional security layer to the Authorization Code flow.
   + **Require Secret for Web Server Flow**
   + **Require Secret for Refresh Token Flow**
   + **Enable Client Credentials Flow**
   + **Enable Authorization Code and Credential Flow**
   + **Enable Token Exchange Flow**
   + **Require Secret for Token Exchange Flow**

1. Add the following required OAuth scopes:
   + `api` - Access Salesforce APIs
   + `refresh_token` - Maintain access when user is offline
   + `offline_access` - Perform requests at any time
   + `full` - Full access to all data
   + `web` - Web-based access
   + `visualforce` - Access Visualforce pages
   + `custom_permissions` - Access custom permissions
   + `chatter_api` - Access Chatter API
   + `wave_api` - Access Analytics API
   + `eclair_api` - Access Einstein Analytics API
   + `pardot_api` - Access Pardot API
   + `id` - Access identity information
   + `email` - Access email address
   + `profile` - Access basic profile information
   + `address` - Access address information
   + `phone` - Access phone number
   + `open_id` - Access OpenID Connect

1. Enter the callback URL in the format: `<quicksuite-url>/sn/oauthcallback`

1. Choose **Save**.

## Step 2: Configure consumer details and execution user
<a name="salesforce-consumer-details"></a>

Configure the consumer details and set up an execution user for the client credentials flow.

1. From the Manage Connected Apps page, choose **Manage Consumer Details**. You might need to verify your identity.

1. Copy the **Consumer Key (Client ID)** and **Consumer Secret (Client Secret)**.

1. Choose **Apply**.

1. Choose **Initial Access Token**, then choose **OK**.

1. Configure the execution user:

   1. From the connected app detail page, choose **Edit** under the Action column.

   1. Under OAuth Policies > Refresh Token Policy, select **Immediately expire refresh token**.

   1. Under Client Credentials Flow, for Run As, choose the user to assign the client credentials flow.

   1. Choose **Save**.

## Step 3: Set up Salesforce action connector
<a name="salesforce-integration-setup"></a>

After preparing your Salesforce connected app credentials, create the Salesforce action connector in Amazon Quick.

Salesforce integration supports action execution only - data access and knowledge base creation are not available for Salesforce systems.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Salesforce** from the integration options, and click the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** - Descriptive name for your Salesforce action connector.
   + **Description** (Optional) - Purpose of the action connector.

1. Choose your connection type:
   + **User authentication** - OAuth-based authentication for individual user access.
   + **Service authentication** - Service-to-service authentication for application access.

1. Fill in the connection settings based on your selected authentication method (either user or service):

   1. For **User authentication (OAuth)**, configure the following fields:
     + **Base URL** - Salesforce instance URL (for example, https://your-domain.salesforce.com).
     + **Client ID** - Salesforce connected app consumer key.
     + **Client Secret** - Salesforce connected app consumer secret.
     + **Token URL** - Salesforce OAuth token endpoint.
     + **Auth URL** - Salesforce OAuth authorization endpoint.
     + **Redirect URL** - OAuth redirect URI configured in your connected app.

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

## Step 4: Associate action connector to automation groups
<a name="salesforce-automation-group-setup"></a>

To use Salesforce actions in automations, you must associate the action connector with your automation groups.

1. Navigate to your automation group settings.

1. Associate the Salesforce action connector with the automation group that will use these actions.

1. Create a new automation for the automation group to access Salesforce actions in your workflows.

## Available task actions
<a name="salesforce-integration-actions"></a>

After you create your Salesforce integration, you can review the available actions for interacting with Salesforce objects. Common Salesforce actions include:
+ Create, read, update, and delete (CRUD) operations on standard and custom objects.
+ Query Salesforce data using SOQL (Salesforce Object Query Language).
+ Manage leads, accounts, contacts, and opportunities.
+ Execute Apex methods and custom logic.
+ Manage cases, tasks, and activities.
+ Access reports and dashboards.

## Share integrations
<a name="salesforce-integration-sharing"></a>

You can share Salesforce action connectors with other users in your organization. Follow these steps:

1. After you create the integration, choose **Share integration**.

1. Select users or groups to share the integration with.

1. Set appropriate permissions for shared access.

1. Confirm sharing settings.

Shared users can use the Salesforce integration to perform actions within the connected Salesforce organization, subject to the permissions configured in the original authentication setup.

## Manage Salesforce action connectors
<a name="salesforce-integration-management"></a>

After you create your Salesforce action connector, you can manage it using these options:
+ **Edit action connector** - Update authentication settings or Salesforce instance configuration.
+ **Share action connector** - Make the action connector available to other users in your organization.
+ **Monitor usage** - View action connector activity and API usage metrics.
+ **Review actions** - See the complete list of available Salesforce actions.
+ **Delete action connector** - Remove the action connector and revoke associated authentication.

# SAP workload integrations
<a name="sap-integrations"></a>

With SAP workload integrations, you can perform actions within various SAP systems. Manage business data, inventory, materials, and business processes. These integrations support action execution only and require Amazon Quick Pro tier or higher.

## What you can do
<a name="sap-integrations-capabilities"></a>

SAP workload integrations provide enterprise-level connectivity to help you work with your SAP systems.

**Action connector**  
Perform actions within SAP systems. Create, update, and manage business data, inventory records, material information, and other enterprise operations through SAP APIs.

**Multiple SAP modules**  
Support for five different integration types: Bill of Materials, Business Partner, Material Stock, Physical Inventory Documents, and Product Master.

## Before you begin
<a name="sap-integrations-prerequisites"></a>

Before you set up SAP workload integrations, make sure you have the following:
+ SAP system with appropriate modules installed and configured.
+ SAP user account with necessary permissions and authorizations.
+ Amazon Quick Author or higher.
+ Network connectivity between Amazon Quick and your SAP system.

## Prepare SAP system configuration and authentication
<a name="sap-system-preparation"></a>

Before setting up the integration in Amazon Quick, prepare your SAP system configuration and user authentication. SAP workload integrations support multiple authentication methods and require proper system setup.

### Authentication methods
<a name="sap-authentication-methods"></a>

SAP workload integrations support two authentication methods:

**OAuth 2.0 (Recommended)**  
Secure authentication method for automated workflows. Requires OAuth configuration in your SAP system.  
**Required parameters:**  
+ **Client ID** - SAP OAuth Client ID
+ **Client Secret** - SAP OAuth Client Secret
+ **Token URL** - OAuth token endpoint (e.g., `https://hostname:port/sap/bc/sec/oauth2/token?sap-client=100`)
+ **Domain URL** - SAP system API endpoint (e.g., `https://hostname:port/sap/opu/odata/sap/API_BUSINESS_PARTNER`)

**Basic Authentication**  
Username and password authentication for direct SAP system access.  
**Required parameters:**  
+ **Username** - SAP system username
+ **Password** - SAP system password
+ **Domain URL** - SAP system API endpoint

### SAP system configuration requirements
<a name="sap-system-configuration"></a>

Before using SAP workload integrations, ensure your SAP system is properly configured:

#### OAuth 2.0 setup
<a name="sap-oauth-setup"></a>

For OAuth 2.0 authentication:
+ Configure the OAuth authorization server with appropriate scopes
+ Verify OAuth is enabled for the service using transaction code `/IWFND/MAINT_SERVICE`
+ Refer to SAP documentation for detailed OAuth 2.0 configuration: [OAuth 2.0 Configuration Guide](https://help.sap.com/docs/ABAP_PLATFORM_NEW/fd0fc52fd22b45f29d274a7f8236e768/cdb122d5b0784c77bf1bcce17f730e74.html)

#### SAP API activation
<a name="sap-api-activation"></a>

Ensure the required SAP API services are active:
+ Activate the specific API service for your chosen SAP connector
+ Verify API service status in your SAP system
+ Refer to SAP documentation for API activation: [SAP API Service Activation Guide](https://help.sap.com/doc/saphelp_nw75/7.5.5/en-US/1b/023c1cad774eeb8b85b25c86d94f87/frameset.htm)

### Available SAP workload integration types
<a name="sap-integration-types"></a>

Choose the SAP integration type that matches your business needs and ensure the corresponding SAP module is available in your system.

**SAP Bill of Materials**  
Manage bill of materials data, including component lists, quantities, and manufacturing specifications.  
**Required scope:** `ZAPI_BILL_OF_MATERIAL_SRV_0002`

**SAP Business Partner**  
Handle business partner information, including customer and vendor data, contact details, and relationship management.  
**Required scope:** `ZAPI_BUSINESS_PARTNER_0001`

**SAP Material Stock**  
Access and manage material stock levels, inventory movements, and warehouse information.  
**Required scope:** `ZAPI_MATERIAL_STOCK_SRV_0001`

**SAP Physical Inventory Documents**  
Create and manage physical inventory documents, stock counts, and inventory reconciliation processes.  
**Required scope:** `ZAPI_MATERIAL_STOCK_SRV_0001`

**SAP Product Master**  
Maintain product master data, including material specifications, classifications, and product hierarchies.  
**Required scope:** `ZAPI_PRODUCT_SRV_0001`

### SAP workload authentication setup
<a name="sap-authentication-setup"></a>

Prepare SAP user authentication credentials and ensure proper system access permissions.
+ **SAP system URL** - Obtain the base URL or server address for your SAP system.
+ **User credentials** - Create or identify a SAP user account with appropriate permissions.
+ **System permissions** - Ensure the user account has the necessary SAP authorizations and transaction codes for the specific SAP modules you plan to integrate.
+ **Network access** - Verify that your SAP system is accessible from external connections and that firewall rules allow the integration.

## Set up SAP integrations
<a name="sap-integrations-setup"></a>

After preparing your SAP system configuration and authentication credentials, the setup process is similar for all SAP integration types. Choose between OAuth 2.0 or Basic Authentication based on your security requirements.

1. In the Amazon Quick console, choose **Integrations**.

1. Select one of the available SAP connectors:
   + **SAP Bill of Materials**
   + **SAP Business Partner**
   + **SAP Material Stock**
   + **SAP Physical Inventory Documents**
   + **SAP Product Master**

1. Click **Add** (plus "\$1" button).

1. Fill in the name and description for your SAP integration.

1. Choose the connection type for your integration.

1. Configure authentication using one of the supported methods:

   1. <a name="sap-oauth-configuration"></a>**OAuth 2.0 configuration**

      For OAuth 2.0 authentication, provide:
      + **Client ID** - Your SAP OAuth Client ID
      + **Client Secret** - Your SAP OAuth Client Secret
      + **Token URL** - OAuth token endpoint URL
      + **Domain URL** - SAP system API endpoint URL

   1. <a name="sap-basic-auth-configuration"></a>**Basic Authentication configuration**

      For Basic Authentication, provide:
      + **Username** - Your SAP system username
      + **Password** - Your SAP system password
      + **Domain URL** - SAP system API endpoint URL

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

### Expected results
<a name="sap-integrations-setup-results"></a>

After successful setup, your SAP workload integration appears in the integrations list and is available for use in Amazon Quick workflows, automations, and AI agents. You can perform SAP-specific actions directly from Amazon Quick using the configured authentication credentials.

## Available operations by connector type
<a name="sap-available-operations"></a>

Each SAP workload connector provides specific operations tailored to its business domain. Review the available operations for your chosen connector type.

### SAP Bill of Materials operations
<a name="sap-bom-operations"></a>

Available operations for managing bill of materials data:
+ **Get Material BOM Item** - Retrieves bill of material details for specified materials

  **Operation ID:** `getMaterialBOMItem`

  **Endpoint:** `GET /MaterialBOMItem`

### SAP Business Partner operations
<a name="sap-bp-operations"></a>

Available operations for managing business partner data:
+ **Get Business Partner** - Retrieves business partner general data

  **Operation ID:** `getBusinessPartner`
+ **Get Business Partner Addresses** - Retrieves business partner address data

  **Operation ID:** `getBusinessPartnerAddress`
+ **Get Business Partner Roles** - Retrieves business partner role data

  **Operation ID:** `getBusinessPartnerRole`
+ **Get Business Partner by ID** - Retrieves business partner data by business partner number

  **Operation ID:** `getBusinessPartnerByID`

  **Required parameter:** `BusinessPartner` (string, max 10 characters)
+ **Get Business Partner Role by ID** - Retrieves business partner role data using key fields

  **Operation ID:** `getBusinessPartnerRoleByID`

  **Required parameters:** `BusinessPartner` (string, max 10 characters), `BusinessPartnerRole` (string, max 6 characters)

### SAP Material Stock operations
<a name="sap-ms-operations"></a>

Available operations for managing material stock data:
+ **Get Material Stock In Account** - Retrieves material stock information posted in the account model

  **Operation ID:** `getMaterialStockInAccount`

### SAP Physical Inventory Documents operations
<a name="sap-pi-operations"></a>

Available operations for managing physical inventory documents:
+ **Get PhysInventory Doc Item** - Reads information on physical inventory items

  **Operation ID:** `getPhysInventoryDocItem`

### SAP Product Master operations
<a name="sap-pm-operations"></a>

Available operations for managing product master data:
+ **Get Product Master Item** - Returns product master records

  **Operation ID:** `getProductMaster`
+ **Get Plant Data By Material** - Returns plant data of product master record

  **Operation ID:** `getPlantDataByMaterial`

  **Required parameter:** `Product` (string, max 40 characters)
+ **Get Supply Planning Data By Material** - Returns supply planning data by product number and plant

  **Operation ID:** `getSupplyPlanningDataByMaterial`

  **Required parameters:** `Product` (string, max 40 characters), `Plant` (string, max 4 characters)

## Query parameters
<a name="sap-odata-parameters"></a>

SAP connectors support standard query parameters to filter, sort, and format API responses. Use these parameters to optimize data retrieval and processing.


**Supported Query Parameters**  

| \$1 | Parameter | Description | Type | 
| --- | --- | --- | --- | 
| 1 | \$1top | Limits the number of returned items | integer | 
| 2 | \$1skip | Skips the specified number of items | integer | 
| 3 | \$1filter | Filters results based on specified criteria | string | 
| 4 | \$1orderby | Orders results by specified fields | array | 
| 5 | \$1select | Selects specific properties to return | array | 
| 6 | \$1expand | Expands related entities | array | 
| 7 | \$1inlinecount | Includes count of items in response | string | 

## Manage SAP workload integrations
<a name="sap-integrations-management"></a>

After you create your SAP workload integration, you can manage it through several options.

### Edit integration settings
<a name="sap-integrations-editing"></a>

Follow these steps to modify your SAP workload integration settings.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose your SAP workload integration type from the integration grid.

1. Select your integration from the list and choose **Edit**.

1. Modify integration settings:
   + Update authentication credentials (username and password).
   + Change SAP system URL or connection settings.
   + Modify integration name or description.

1. Choose **Save changes** to apply your modifications.

### Share integration
<a name="sap-integrations-sharing"></a>

You can share SAP workload action connectors with other users in your organization.

1. From the SAP integration details page, choose **Share**.

1. Configure sharing options:
   + **Share with specific users** - Enter user names or email addresses.
   + **Share with organization** - Make available to all users in your organization.

1. Set permission levels for shared access.

1. Choose **Share integration** to apply the sharing settings.

### Delete integration
<a name="sap-integrations-deletion"></a>

Follow these steps to permanently remove your SAP integration.

1. From the SAP workload integration details page, choose **Delete**.

1. Review the deletion impact, including any workflows or automations using this integration.

1. Type the integration name to confirm deletion.

1. Choose **Delete integration** to permanently remove it.

## Troubleshoot SAP workload integrations
<a name="sap-integrations-troubleshooting"></a>

Use these troubleshooting tips to resolve common SAP workload integration issues.

### Authentication issues
<a name="sap-authentication-issues"></a>

OAuth 2.0 authentication failures  
**Symptoms:** Token generation fails, invalid client credentials, or OAuth scope errors.  
**Resolution:**  
+ Verify OAuth client ID and client secret are correct
+ Check that OAuth is properly configured in SAP using transaction `/IWFND/MAINT_SERVICE`
+ Ensure the required scopes are properly configured for your SAP workload connector type
+ Verify the token URL format matches your SAP system configuration

Basic authentication failures  
**Symptoms:** Login failures, invalid credentials, or access denied errors.  
**Resolution:**  
+ Verify SAP username and password are correct
+ Check that the user account has necessary SAP authorizations
+ Ensure the user account is not locked or expired
+ Verify the domain URL is accessible and correctly formatted

### SAP system configuration issues
<a name="sap-system-configuration-issues"></a>

API service not activated  
**Symptoms:** Service unavailable errors, API endpoint not found, or HTTP 404 responses.  
**Resolution:**  
+ Verify the required SAP API service is activated in your system
+ Check API service status using SAP transaction codes
+ Ensure the API service corresponds to your chosen SAP connector type
+ Contact your SAP administrator to activate missing API services

Connection timeouts  
**Symptoms:** Request timeouts, network connectivity errors, or slow response times.  
**Resolution:**  
+ Check that your SAP system URL is correct and accessible
+ Verify network connectivity allows connections to SAP system
+ Ensure firewall rules permit the integration traffic
+ Check SAP system performance and availability

### Permission and authorization errors
<a name="sap-permission-errors"></a>

Insufficient SAP authorizations  
**Symptoms:** Access denied errors, missing authorization messages, or restricted operation failures.  
**Resolution:**  
+ Ensure the authenticated user has required SAP authorizations for the specific module
+ Verify the user has access to necessary transaction codes
+ Check that the user account has appropriate role assignments
+ Contact your SAP administrator to grant missing permissions

Scope permission errors  
**Symptoms:** OAuth scope errors, insufficient permissions for API operations, or restricted access messages.  
**Resolution:**  
+ Verify the OAuth configuration includes the required scope for your connector type
+ Check that the scope permissions are properly granted in SAP system
+ Ensure the OAuth client has been granted the necessary API access rights

### Data format and parameter errors
<a name="sap-data-format-errors"></a>

Invalid parameter formats  
**Symptoms:** Data validation errors, invalid field length messages, or parameter format exceptions.  
**Resolution:**  
+ Review action parameters and ensure they match expected SAP data formats
+ Check field lengths match SAP system requirements (e.g., BusinessPartner max 10 characters)
+ Verify data types are correct for the specific SAP module
+ Ensure all required fields are provided for the operation

Query parameter errors  
**Symptoms:** Query syntax errors, unsupported parameter messages, or malformed request errors.  
**Resolution:**  
+ Verify parameters use correct syntax (e.g., `$filter`, `$top`, `$skip`)
+ Check that the parameter values are properly formatted
+ Ensure the SAP API supports the specific parameters being used
+ Refer to SAP API documentation for supported query options

### SAP system availability issues
<a name="sap-system-availability"></a>

SAP system unavailability  
**Symptoms:** Connection refused errors, system not responding, or service unavailable messages.  
**Resolution:**  
+ Check SAP system status and availability with your SAP administrator
+ Verify if there are scheduled maintenance windows affecting the system
+ Check for any SAP system alerts or known issues
+ Retry the operation after confirming system availability

# ServiceNow integration
<a name="servicenow-integration"></a>

Use the ServiceNow integration to perform actions within your ServiceNow instances, including managing incidents, problems, change requests, knowledge base articles, and attachments. This integration uses the ServiceNow REST API. For more information, see [REST API](https://docs.servicenow.com/bundle/xanadu-api-reference/page/build/applications/concept/api-rest.html) in the ServiceNow documentation.

Setting up this integration involves two steps. First, you configure an OAuth application in your ServiceNow instance. Then, you create the integration in Amazon Quick and connect it to your ServiceNow app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Before you begin
<a name="servicenow-integration-prerequisites"></a>

Before you set up the integration, verify that you have the following.
+ A ServiceNow instance. This integration is validated against the Xanadu release.
+ A ServiceNow user account with permissions to create OAuth applications (`admin` role required).
+ For service authentication (client credentials), your instance must be running the Washington DC release or later.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure ServiceNow OAuth
<a name="servicenow-oauth-setup"></a>

Before you configure Amazon Quick, create an OAuth application endpoint in your ServiceNow instance. Complete all of the following steps in ServiceNow before moving to the Amazon Quick console.

For more information, see [Create an endpoint for clients to access the instance](https://www.servicenow.com/docs/bundle/xanadu-platform-security/page/administer/security/task/t_CreateEndpointforExternalClients.html) in the ServiceNow documentation.

### Register the OAuth application
<a name="servicenow-oauth-app-registration"></a>

To register the OAuth application, complete the following steps.

1. In your ServiceNow instance, navigate to **All** > **System OAuth** > **Application Registry** and choose **New**.

1. Choose **Create an OAuth API endpoint for external clients**.

1. Complete the form:
   + **Name** – A descriptive name for the OAuth application.
   + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

     Replace *\$1region\$1* with your AWS Region (for example, `us-east-1`).

1. Choose **Submit**.

1. Reopen the application registry entry and choose the lock icon next to **Client Secret** to reveal the value.

1. Copy the **Client ID** and **Client Secret** values. You need these when you configure the integration in Amazon Quick.

### Additional steps for service authentication (client credentials)
<a name="servicenow-oauth-client-credentials"></a>

If you plan to use service authentication, complete these additional steps after registering the OAuth application. The client credentials grant type was introduced in the ServiceNow Washington DC release. For more information, see [Up Your OAuth2.0 Game: Inbound Client Credentials with Washington DC](https://www.servicenow.com/community/developer-blog/up-your-oauth2-0-game-inbound-client-credentials-with-washington/ba-p/2816891) in the ServiceNow Community.

1. Enable the client credentials grant type. Navigate to `sys_properties.list` using the filter navigator and create a new system property with the following values:
   + **Name** – `glide.oauth.inbound.client.credential.grant_type.enabled`
   + **Type** – `true | false`
   + **Value** – `true`

1. Verify that the following plugins are installed (navigate to **Admin** > **Application Manager**):
   + OAuth 2.0 (`com.snc.platform.security.oauth`)
   + REST API Provider (`com.glide.rest`)
   + Authentication scope (`com.glide.auth.scope`)
   + REST API Auth Scope Plugin (`com.glide.rest.auth.scope`)

1. Return to your OAuth application in **System OAuth** > **Application Registry**. Add the **OAuth Application User** field to the form if it isn't visible (use **Configure** > **Form Builder** to add it).

1. Set the **OAuth Application User** to an appropriately permissioned user, such as a user with the System Administrator role.

**Important**  
With service authentication, all actions execute as the configured OAuth application user. Any Amazon Quick user with access to this integration can perform actions using that account's permissions. Configure the account permissions to match your organization's security requirements.

## Set up the integration in Amazon Quick
<a name="servicenow-action-integration-setup"></a>

After you complete the ServiceNow OAuth configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **ServiceNow** and choose the Add (plus "\$1") button.

1. Enter the integration details:
   + **Name** – Descriptive name for your ServiceNow integration.
   + **Description** (Optional) – Purpose of the integration.

1. Choose your connection type and fill in the connection settings:

   1. For **User authentication (OAuth)**, configure the following fields:
      + **Base URL** – `https://{your-instance}.service-now.com`
      + **Client ID** – Client ID from your ServiceNow OAuth application.
      + **Client Secret** – Client secret from your ServiceNow OAuth application.
      + **Token URL** – `https://{your-instance}.service-now.com/oauth_token.do`
      + **Auth URL** – `https://{your-instance}.service-now.com/oauth_auth.do`
      + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

   1. For **Service authentication (client credentials)**, configure the following fields:
      + **Authentication type** – Service-to-service OAuth
      + **Base URL** – `https://{your-instance}.service-now.com`
      + **Client ID** – Client ID from your ServiceNow OAuth application.
      + **Client Secret** – Client secret from your ServiceNow OAuth application.
      + **Token URL** – `https://{your-instance}.service-now.com/oauth_token.do`

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

For user authentication, navigate to **Integrations** > **Actions** > your ServiceNow integration name, and choose **Sign in** to complete the OAuth authorization flow.

## Available actions
<a name="servicenow-integration-actions"></a>

After you set up the integration, the following actions are available.


**ServiceNow available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Incidents | List Incidents | Retrieve existing incidents. | 
| Incidents | Create Incident | Create an incident record to document a deviation from an expected standard of operation. | 
| Incidents | View Incident | Retrieve the details of a specific incident. | 
| Incidents | Update Incident | Update an incident record. | 
| Incidents | Delete Incident | Delete an incident. | 
| Problems | List Problems | Retrieve existing problems. | 
| Problems | Create Problem | Create a new problem record. | 
| Problems | View Problem | Retrieve the details of a specific problem record. | 
| Problems | Update Problem | Update a problem record. | 
| Problems | Delete Problem | Delete a problem. | 
| Change requests | List Change Requests | Retrieve all change requests. | 
| Change requests | Create Change Request | Create a change request to implement a controlled process for modifying approved and supported configuration items (CIs). | 
| Change requests | View Change Request | Retrieve detailed information about a specific change request. | 
| Change requests | Update Change Request | Modify a change request. | 
| Change requests | Delete Change Request | Delete a change request. | 
| Knowledge base articles | Create Knowledge Base Article | Create a knowledge base article. Requires the Knowledge API (sn\$1km\$1api) plugin. | 
| Knowledge base articles | Update Knowledge Base Article | Modify a knowledge base article. | 
| Knowledge base articles | Delete Knowledge Base Article | Delete a knowledge base article. | 
| Attachments | Retrieve Attachments Metadata | Retrieve metadata for attachment files. | 
| Attachments | Retrieve Attachment Metadata | Retrieve metadata for a specific attachment file. | 
| Attachments | Retrieve Attachment Content | Retrieve the binary file attachment content. | 
| Attachments | Upload Binary Attachment | Upload a binary file as an attachment to a specified record. | 
| Attachments | Upload Multipart Form Attachment | Upload a multipart file attachment. | 
| Attachments | Delete Attachment | Delete an attachment. | 
| Users | List Users | List all user records. | 
| System | List Choices | Retrieve choice list values from the sys\$1choice table. | 

**Note**  
The specific actions available depend on the permissions configured in your ServiceNow instance and the authentication method used.

## Limitations
<a name="servicenow-integration-limitations"></a>

This integration interacts with ServiceNow through the REST API, which does not enforce UI policies, UI actions, or client scripts. These rules only apply in the ServiceNow browser interface. Server-side business rules, ACLs, and data policies are enforced. For more information, see [REST API](https://docs.servicenow.com/bundle/xanadu-api-reference/page/integrate/inbound-rest/concept/c_RESTAPI.html) in the ServiceNow documentation.

## Manage and troubleshoot
<a name="servicenow-integration-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="servicenow-troubleshooting-auth"></a>
+ **OAuth authorization fails** – Verify that the Client ID and Client Secret match the values in your ServiceNow Application Registry. Confirm the Redirect URL in ServiceNow matches the URL in your Amazon Quick configuration exactly.
+ **Service authentication fails** – Verify that the `glide.oauth.inbound.client.credential.grant_type.enabled` system property is set to `true`. Confirm the **OAuth Application User** field is populated on the application registry record.

### Common error messages
<a name="servicenow-troubleshooting-errors"></a>
+ **Actions return permission errors** – Verify that the ServiceNow user or OAuth application user has the required roles to access the target tables (for example, `itil` role for incident management).
+ **Connection timeout or unreachable instance** – Verify the Base URL uses the correct ServiceNow instance name. Confirm the ServiceNow instance is accessible and not in maintenance mode.

# Slack integration
<a name="slack-integration"></a>

With Slack integration in Amazon Quick, you can perform actions within Slack workspaces, including sending messages, managing channels, and interacting with Slack APIs. This integration supports action execution only and requires Amazon Quick Pro tier or higher.

## What you can do
<a name="slack-integration-capabilities"></a>

With Slack integration, you can perform actions through the action connector.

**Action connector**  
Send messages, manage channels, and access Slack APIs through authenticated connections.

## Before you begin
<a name="slack-integration-prerequisites"></a>

Before you set up Slack integration, make sure you have the following:
+ Slack workspace with appropriate permissions.
+ Slack app or bot token with required scopes.
+ Amazon Quick Author or higher.
+ Administrative access to configure OAuth applications (if using user authentication).

## Set up Slack OAuth app
<a name="slack-integration-oauth-setup"></a>

Before you configure the integration, you need to create a Slack app with OAuth capabilities. Follow these steps:

1. Go to the Slack API website and create a new Slack app.

1. Configure OAuth scopes based on the actions you want to perform.

1. Set up redirect URLs to match your Amazon Quick integration configuration.

1. Note the client ID and client secret for use in Amazon Quick integration setup.

## Set up Slack integration
<a name="slack-integration-setup"></a>

Use the unified Integrations tab in the Amazon Quick console to set up Slack integration for task execution. Follow these steps:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Slack** from the integration options, click the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** - Descriptive name for your Slack integration.
   + **Description** (Optional) - Purpose of the integration.

1. Choose your connection type (user authentication for Slack).

1. Fill in the connection settings for user authentication:

   1. Configure the following OAuth fields:
     + **Base URL** - Slack API base URL (typically https://slack.com/api).
     + **Client ID** - Slack app client ID.
     + **Client Secret** - Slack app client secret.
     + **Token URL** - Slack OAuth token endpoint.
     + **Auth URL** - Slack OAuth authorization endpoint.
     + **Redirect URL** - OAuth redirect URI configured in your Slack app.

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

## Available task actions
<a name="slack-integration-actions"></a>

After you create your Slack integration, you can review the available actions for interacting with Slack workspaces. Common Slack actions include:
+ Send messages to channels or direct messages.
+ Create and manage channels.
+ Retrieve channel information and member lists.
+ Upload and share files.
+ Manage user presence and status.
+ Access workspace and team information.

**Note**  
The specific actions available depend on the OAuth scopes configured in your Slack app and the permissions granted during authentication.

## Share integrations
<a name="slack-integration-sharing"></a>

You can share Slack action connectors with other users in your organization. Follow these steps:

1. After you create the integration, choose **Share integration**.

1. Select users or groups to share the integration with.

1. Set appropriate permissions for shared access.

1. Confirm sharing settings.

Shared users can use the Slack integration to perform actions within the connected Slack workspace, subject to the permissions configured in the original OAuth setup.

## Manage Slack integrations
<a name="slack-integration-management"></a>

After you create your Slack integration, you can manage it through the Integrations console using these options:
+ **Edit integration** - Update authentication settings or OAuth configuration.
+ **Share integration** - Make the integration available to other users in your organization.
+ **Monitor usage** - View integration activity and API usage metrics.
+ **Review actions** - See the complete list of available Slack actions.
+ **Delete integration** - Remove the integration and revoke associated OAuth tokens.

**Important**  
Deleting a Slack integration will revoke the OAuth tokens and prevent any shared users from accessing the Slack workspace through Amazon Quick.

# Smartsheet integration
<a name="smartsheet-integration"></a>

Use the Smartsheet action connector to manage sheets, rows, reports, and search across your Smartsheet workspaces directly in Amazon Quick through natural language. This integration uses the Smartsheet API. For more information, see [Smartsheet API introduction](https://developers.smartsheet.com/api/smartsheet/introduction) in the Smartsheet documentation.

Setting up this integration involves two steps. First, you configure credentials in Smartsheet for your chosen authentication method. Then, you create the integration in Amazon Quick and connect it to your Smartsheet account. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](quick-action-auth.md).

## Prerequisites
<a name="smartsheet-integration-prerequisites"></a>

Before you set up the integration, make sure that you meet the following requirements:
+ A Smartsheet account with a Business or Enterprise plan. Free accounts cannot generate API access tokens or register OAuth apps. For more information, see [Smartsheet pricing](https://www.smartsheet.com/pricing) on the Smartsheet website.
+ Access to [Smartsheet Developer Tools](https://developers.smartsheet.com/) activated for your account. To register, go to the [Developer Tools Registration](https://developers.smartsheet.com/register) page.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).

## Configure Smartsheet Developer Tools
<a name="smartsheet-developer-setup"></a>

Before you configure Amazon Quick, set up credentials in Smartsheet. The steps you complete depend on which authentication method you plan to use. Amazon Quick supports two authentication methods for Smartsheet. For more information about these methods, see [Authentication methods](quick-action-auth.md).
+ **User authentication (OAuth)** – Each user signs in with their own Smartsheet account. Actions run with that user's permissions. This method uses [Custom user-based authentication](quick-action-auth.md#quick-custom-user-auth). Complete the [Register for Developer Tools and create a developer profile](#smartsheet-register-developer-tools) and [Register the OAuth application](#smartsheet-register-oauth-app) sections below.
+ **Service authentication (API key)** – All actions run using a single API token. This method uses [API key authentication](quick-action-auth.md#quick-actions-api-key-auth). Complete the [Generate an API access token (service authentication only)](#smartsheet-api-token-setup) section below.

For more information about Smartsheet OAuth, see [OAuth](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth) in the Smartsheet API documentation.

### Register for Developer Tools and create a developer profile
<a name="smartsheet-register-developer-tools"></a>

1. Go to the [Developer Tools Registration](https://developers.smartsheet.com/register) page and register the Smartsheet account you want to use with your apps. For more information, see [Register for Developer Tools](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#register-for-developer-tools) in the Smartsheet API documentation.

1. After Smartsheet activates Developer Tools, sign in to the Smartsheet application and choose your **Account** icon in the lower-left corner, then choose **Developer Tools**.

1. Choose **Create Developer Profile** and enter a profile name. For more information, see [Create your developer profile](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#create-your-developer-profile) in the Smartsheet API documentation.

**Tip**  
Smartsheet recommends using a dedicated service account for OAuth apps rather than a personal account.

### Register the OAuth application
<a name="smartsheet-register-oauth-app"></a>

1. In Smartsheet Developer Tools, choose **Create New App**.

1. Complete the form:
   + **App name** – A name to identify your app to users.
   + **App description** – A brief description of the integration.
   + **App URL** – The URL that launches your app, or a landing page.
   + **App contact/support** – Support contact information.
   + **App redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

     Replace *\$1region\$1* with your AWS Region (for example, `us-east-1`).

1. Choose **Save**. Smartsheet generates the **App client ID** and **App secret**.

1. Copy the **Client ID** and **Client Secret** values. You need these when you configure the integration in Amazon Quick.

For more information, see [Register an app](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#register-an-app) in the Smartsheet API documentation.

### Generate an API access token (service authentication only)
<a name="smartsheet-api-token-setup"></a>

If you plan to use service authentication instead of OAuth, generate an API access token. You must have a Business or Enterprise plan to generate tokens. For more information, see [Generate an API access token](https://help.smartsheet.com/articles/2482389-generate-API-key) in the Smartsheet Help Center.

1. In the Smartsheet application, choose your **Account** (profile image) at the bottom of the left navigation bar, then choose **Personal Settings**.

1. Choose the **API Access** tab and choose **Generate new access token**.

1. Name the token and choose **OK**. Copy the token value immediately — this is the only time it's visible.

**Important**  
Store your access token securely. Anyone with the token can access all Smartsheet data that the token owner has access to. Do not commit tokens to version control systems. For best practices on storing tokens, see [Authentication](https://developers.smartsheet.com/api/smartsheet/guides/basics/authentication) in the Smartsheet API documentation.

## OAuth access scopes
<a name="smartsheet-oauth-scopes"></a>

When you configure user authentication (OAuth), the integration requests the following access scopes from Smartsheet. These scopes determine what the integration can do on behalf of the authenticated user. If you use service authentication (API key) instead, the integration uses the full permissions of the token owner and scopes do not apply. For more information, see [Access scopes](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#access-scopes) in the Smartsheet API documentation.


**Smartsheet OAuth access scopes**  

| Scope | Description | 
| --- | --- | 
| READ\$1SHEETS | Read all sheet data, including attachments, discussions, and cell data. | 
| WRITE\$1SHEETS | Insert and modify sheet data, including attachments, discussions, and cell data. | 

**Note**  
Access scopes don't override existing sharing permissions. For example, having the `WRITE_SHEETS` scope doesn't allow the integration to update a sheet on which the user has only viewer-level access. For more information, see [Resource access levels](https://developers.smartsheet.com/api/smartsheet/guides/basics/resource-access-levels) in the Smartsheet API documentation.

## Set up the integration in Amazon Quick
<a name="smartsheet-action-integration-setup"></a>

After you complete the Smartsheet Developer Tools configuration, create the integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Smartsheet** and choose the Add (plus "\$1") button.

1. Enter the integration details:
   + **Name** – Descriptive name for your Smartsheet integration.
   + **Description** (Optional) – Purpose of the integration.

1. Choose your connection type and fill in the connection settings. For more information about these authentication methods, see [Authentication methods](quick-action-auth.md).

   1. For **User authentication (OAuth)**, use the Client ID and Client Secret from your Smartsheet Developer Tools app registration. Configure the following fields:
      + **Base URL** – `https://api.smartsheet.com/2.0`
      + **Client ID** – App client ID from your Smartsheet Developer Tools app registration.
      + **Client Secret** – App secret from your Smartsheet Developer Tools app registration.
      + **Token URL** – `https://api.smartsheet.com/2.0/token`
      + **Auth URL** – `https://app.smartsheet.com/b/authorize`
      + **Redirect URL** – `https://{region}.quicksight.aws.amazon.com/sn/oauthcallback`

   1. For **Service authentication (API key)**, use the API access token from your Smartsheet Personal Settings. Configure the following fields:
      + **API Key** – Smartsheet API access token generated from your Personal Settings.
      + **Base URL** – `https://api.smartsheet.com/2.0`
      + **Email** – Email address associated with the Smartsheet account that generated the token.

1. Choose **Create and continue**.

1. Choose users to share the integration with.

1. Choose **Next**.

For user authentication, go to **Integrations** > **Actions** > your Smartsheet integration name, and choose **Sign in** to complete the OAuth authorization flow. In the Smartsheet consent window, choose **Allow** to grant access.

**Important**  
With service authentication, all actions run using the API token owner's permissions. Any Amazon Quick user with access to this integration can perform actions on all Smartsheet resources that the token owner can access. Scope the token permissions appropriately for your organization's security requirements.

**Note**  
If you use Smartsheet Gov, Smartsheet Regions Europe, or Smartsheet Regions Australia, use the corresponding base URL for your environment:  


**Smartsheet regional base URLs**  

| Environment | Base URL | 
| --- | --- | 
| Smartsheet | https://api.smartsheet.com/2.0 | 
| Smartsheet Gov | https://api.smartsheetgov.com/2.0 | 
| Smartsheet Regions Europe | https://api.smartsheet.eu/2.0 | 
| Smartsheet Regions Australia | https://api.smartsheet.au/2.0 | 
For more information, see [Base URL](https://developers.smartsheet.com/api/smartsheet/guides/basics/base-url) in the Smartsheet API documentation.

## Available actions
<a name="smartsheet-integration-actions"></a>

After you set up the integration, the following actions are available.


**Smartsheet available actions**  

| Category | Action | Description | 
| --- | --- | --- | 
| Search | List Search | Searches all sheets that the user can access for specified text. | 
| Sheets | List Sheets | Lists all sheets that are accessible to the authenticated user. | 
| Sheets | Get Sheet | Gets a sheet and its data based on the sheet ID. | 
| Reports | List Reports | Lists all reports that are accessible to the user. | 
| Reports | View Report | Gets report details based on the report ID. | 

## Manage and troubleshoot
<a name="smartsheet-integration-troubleshooting"></a>

To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).

### Authentication issues
<a name="smartsheet-troubleshooting-auth"></a>
+ **OAuth authorization fails** – Verify that the Client ID and Client Secret match the values in your Smartsheet Developer Tools app registration. Confirm the redirect URL in Smartsheet matches the URL in your Amazon Quick configuration exactly. For a list of OAuth error types, see [OAuth error types](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#oauth-error-types) in the Smartsheet API documentation.
+ **Developer Tools not available** – Verify that Developer Tools is activated for your Smartsheet account. Free accounts do not support Developer Tools. If your request was denied, contact your Smartsheet Customer Success Manager.
+ **API key authentication fails** – Verify that the access token has not been revoked. You can manage tokens from **Personal Settings** > **API Access** in the Smartsheet application. For more information, see [Generate an API access token](https://help.smartsheet.com/articles/2482389-generate-API-key) in the Smartsheet Help Center.
+ **Access token expired** – OAuth access tokens expire after approximately 7 days. Amazon Quick handles token refresh automatically. If you encounter persistent token errors, sign out and sign in again from the integration settings. For more information, see [Make API calls](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#make-api-calls) in the Smartsheet API documentation.

### Common error messages
<a name="smartsheet-troubleshooting-errors"></a>
+ **Actions return permission errors** – Verify that the authenticated user has the required sharing permissions on the target sheets. OAuth scopes don't override sharing-level access controls. For more information, see [Resource access levels](https://developers.smartsheet.com/api/smartsheet/guides/basics/resource-access-levels) in the Smartsheet API documentation.
+ **Sheet not found** – Verify the sheet ID is correct and that the authenticated user has at least viewer access to the sheet.
+ **API rate limit errors** – The Smartsheet API enforces rate limits. For more information, see [Limitations](https://developers.smartsheet.com/api/smartsheet/guides/basics/limitations) in the Smartsheet API documentation.

# Web Crawler integration
<a name="web-crawler-integration"></a>

With Web Crawler integration in Amazon Quick, you can create knowledge bases from website content by crawling and indexing web pages. This integration supports data ingestion capabilities with different authentication options.

## Web Crawler capabilities
<a name="web-crawler-integration-capabilities"></a>

Web Crawler users can ask questions about content stored on websites and web pages. For example, users can search documentation sites, knowledge bases, or specific information across multiple web pages.

The integration helps users access and understand web content regardless of location or type. It provides contextual details such as publication dates, modification history, and page ownership for more efficient information discovery.

**Note**  
Web Crawler integration supports data ingestion only. It doesn't provide action capabilities for managing websites or web services.

## Prerequisites
<a name="web-crawler-integration-prerequisites"></a>

Before you set up Web Crawler integration, make sure you have the following:
+ Website URLs to crawl and index.
+ An Amazon Quick Enterprise subscription.
+ A website that is not behind a firewall and does not require special browser plugins to connect.

## Prepare website access and authentication
<a name="web-crawler-integration-authentication"></a>

Before setting up the integration in Amazon Quick, prepare your website access credentials. Web Crawler integration supports different authentication methods:

**No authentication**  
Use for crawling websites that don't require authentication.

**Basic authentication**   
Standard HTTP Basic Authentication for secured websites. When you visit a protected site, your browser displays a dialog box that asks for your credentials.  
**Required credentials:**  
+ **Login page URL** - The URL of the login page
+ **Username** - Basic auth username
+ **Password** - Basic auth password

**Form authentication**   
For websites that use HTML form-based login pages. You specify XPath expressions to identify the form fields on the login page.  
XPath (XML Path Language) is a query language for navigating elements in an HTML or XML document. To find an XPath for a web page element, right-click the element in your browser and choose **Inspect**. In the developer tools, right-click the highlighted HTML code, choose **Copy**, and then choose **Copy XPath**.  
**Required information:**  
+ **Login page URL** - URL of the login form (for example, `https://example.com/login`)
+ **Username** - Login username
+ **Password** - Login password
+ **Username field XPath** - XPath to username input field (for example, `//input[@id='username']`)
+ **Username button XPath** (Optional) - XPath to username button field (for example, `//input[@id='username_button']`)
+ **Password field XPath** - XPath to password input field (for example, `//input[@id='password']`)
+ **Password button XPath** - XPath to password button (for example, `//button[@type='password']`)

**SAML authentication**  
For websites that use SAML-based single sign-on (SSO) authentication.  
SAML (Security Assertion Markup Language) authentication is a federated identity standard that enables SSO. Users authenticate through a centralized identity provider (such as Microsoft Azure AD or Okta) instead of entering credentials directly into each application. The identity provider passes a secure token back to the application to grant access.  
**Required information:**  
+ **Login page URL** - URL of the SAML login page
+ **Username** - SAML username
+ **Password** - SAML password
+ **Username field XPath** - XPath to username input field (for example, `//input[@id='username']`)
+ **Username button XPath** (Optional) - XPath to username button field (for example, `//input[@id='username_button']`)
+ **Password field XPath** - XPath to password input field (for example, `//input[@id='password']`)
+ **Password button XPath** - XPath to password button (for example, `//button[@type='password']`)

### XPath configuration examples
<a name="web-crawler-xpath-examples"></a>

Use these XPath examples to configure form and SAML authentication:

```
Username field examples:
//input[@id='username']
//input[@name='user']
//input[@class='username-field']

Password field examples:
//input[@id='password']
//input[@name='pass']
//input[@type='password']

Submit button examples:
//button[@type='submit']
//input[@type='submit']
//button[contains(text(), 'Login')]
```

## Set up Web Crawler integration
<a name="web-crawler-integration-setup"></a>

After preparing your website access requirements, create the Web Crawler integration in Amazon Quick.

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Web Crawler** from the integration options, and click the **Add** button (plus "\$1" button).

1. Choose **Access data from Web Crawler**. Web Crawler integration supports data access only - action execution is not available for web crawling.

1. Configure integration details and authentication method, then create knowledge bases as needed.

   1. Choose the authentication type for your web crawler integration.

   1. Enter the required details based on your chosen authentication method.

   1. (Optional) Choose a VPC connection to crawl sites hosted in your private network. The VPC connection must be configured in admin settings before you can choose it here. For more information, see [Setting up a VPC to use with Amazon Quick](vpc-setup-for-quicksight.md).
**Note**  
You can't change the VPC connection after the integration is created. To use a different VPC connection, create a new integration.

   1. Choose **Create and continue**.

   1. Enter the name and description for your knowledge base.

   1. Add the content URLs that you want to crawl.

   1. Choose **Create**.

After you choose **Create**, the data sync starts automatically.

## Configure crawling
<a name="web-crawler-integration-configuration"></a>

You can configure which websites and pages to crawl and how to filter the content.

### Configure URLs and content sources
<a name="web-crawler-url-configuration"></a>

Configure which websites and pages to crawl:

#### Direct URLs
<a name="web-crawler-direct-urls"></a>

Specify individual URLs to crawl:

```
https://example.com/docs
https://example.com/blog
https://example.com/support
```

**Limit:** Maximum 10 URLs per dataset

### Content filters and crawl settings
<a name="web-crawler-content-filters"></a>

#### Crawl scope settings
<a name="web-crawler-crawl-scope-settings"></a>

 To view these settings, you must first set up a knowledge base and then examine the advanced settings option. 

**Crawl depth**  
+ Range: 0-10 (default: 1)
+ 0 = crawl only specified URLs
+ 1 = include linked pages one level deep
+ Higher values follow links deeper into the site

**Maximum links per page**  
+ Default: 1000
+ Maximum: 1,000
+ Controls how many links to follow from each page

**Wait time**  
+ Default: 1
+ The time (in seconds) that the web crawler waits for each page after the page reaches a ready state. Increase this value for pages with dynamic JavaScript content that loads after the main template.

## Manage knowledge bases
<a name="web-crawler-integration-knowledge-base"></a>

After setting up your Web Crawler integration, you can create and manage knowledge bases from your crawled website content.

### Edit existing knowledge bases
<a name="web-crawler-edit-knowledge-base"></a>

You can modify your existing Web Crawler knowledge bases:

1. In the Amazon Quick console, choose **Knowledge bases**.

1. Choose your Web Crawler knowledge base from the list.

1. Choose the three-dot icon under **Actions**, then choose **Edit knowledge base**.

1. Update your configuration settings as needed and choose **Save**.

### Attachments and file crawling
<a name="web-crawler-attachments"></a>

Control whether the system processes files and attachments linked from web pages:
+ **Enable file attachment crawling** – Choose this option to crawl and index files and attachments found on web pages, such as PDFs, documents, and media files.

### Crawling behavior and sync configuration
<a name="web-crawler-crawling-behavior"></a>

Your Web Crawler integration follows these crawling practices:
+ **Incremental sync model:** First sync performs full crawl. Subsequent syncs capture changes only.
+ **Automatic retry:** Built-in retry logic for failed requests.
+ **Duplicate handling:** Automatic detection and deduplication of URLs.
+ **Crawler identification:** Identifies itself with user-agent string "aws-quick-on-behalf-of-<UUID>" in request headers.

#### Sitemap discovery
<a name="web-crawler-sitemap-discovery"></a>

Web Crawler automatically checks for sitemaps by appending common sitemap paths to your seed URLs. You don't need to provide sitemap URLs separately. The following paths are checked:

```
sitemap.xml
sitemap_index.xml
sitemap/sitemap.xml
sitemap/sitemap_index.xml
sitemaps/sitemap.xml
sitemap/index.xml
```

For example, if your seed URL is `https://example.com/docs`, the crawler checks for `https://example.com/docs/sitemap.xml`, `https://example.com/docs/sitemap_index.xml`, and so on.

**Note**  
Web Crawler does not follow recursive sitemap index references. Only the URLs listed directly in a discovered sitemap are used. Sitemap directives in robots.txt are not used for sitemap discovery.

#### Robots.txt compliance
<a name="web-crawler-robots-compliance"></a>

Web Crawler respects the robots.txt protocol and honors user-agent and allow/disallow directives. This enables you to control how the crawler accesses your site.

##### How robots.txt checking works
<a name="web-crawler-robots-behavior"></a>
+ **Host-level checking:** Web Crawler reads robots.txt files at the host level (for example, example.com/robots.txt)
+ **Multiple host support:** For domains with multiple hosts, Web Crawler honors robots rules for each host separately
+ **Fallback behavior:** If Web Crawler can't fetch robots.txt due to blocking, parsing errors, or timeouts, it behaves as if robots.txt doesn't exist. In this case, the crawler proceeds to crawl the site.

##### Supported robots.txt fields
<a name="web-crawler-robots-fields"></a>

Web Crawler recognizes these robots.txt fields (field names are case-insensitive, values are case-sensitive):

`user-agent`  
Identifies which crawler the rules apply to.

`allow`  
A URL path that may be crawled.

`disallow`  
A URL path that may not be crawled.

`crawl-delay`  
The time (in seconds) to wait between requests to your website.

#### Meta tag support
<a name="web-crawler-meta-tags"></a>

Web Crawler supports page-level robots meta tags that you can use to control how your data is used. You can specify page-level settings by including a meta tag on HTML pages or in an HTTP header.

##### Supported meta tags
<a name="web-crawler-supported-meta-tags"></a>

`noindex`  
Do not index the page. If you don't specify this rule, the page may be indexed and eligible to appear in experiences.

`nofollow`  
Do not follow the links on this page. If you don't specify this rule, Web Crawler may use the links on the page to discover those linked pages.

You can combine multiple values using a comma (for example, "noindex, nofollow").

**Note**  
To detect meta tags, Web Crawler must access your page. Don't block your page with robots.txt, because this prevents the page from being recrawled.

## Troubleshooting
<a name="web-crawler-integration-troubleshooting"></a>

Use this section to resolve common issues with Web Crawler integration.

### Authentication failures
<a name="web-crawler-authentication-failures"></a>

**Symptoms:**
+ "Unable to authenticate" error messages
+ 401/403 HTTP responses
+ Login page redirect loops
+ Session timeout errors

**Resolution steps:**

1. Verify the site is reachable from the AWS Region where the Amazon Quick instance is set up.

1. Verify that your credentials are correct and haven't expired.

1. Check authentication endpoint availability and accessibility.

1. Validate XPath configurations by testing them in browser developer tools.

1. Review browser network logs to understand the authentication flow.

1. Ensure the login page URL is correct and accessible.

1. Test authentication manually using the same credentials.

### Access and connectivity issues
<a name="web-crawler-access-issues"></a>

**Symptoms:**
+ Connection timeouts and network errors
+ Network unreachable errors
+ DNS resolution failures

**Resolution steps:**

1. Verify network connectivity to target websites.

1. Validate site accessibility:
   + Check DNS resolution for target domains.
   + Verify SSL/TLS configuration and certificates.
   + Test access from different networks if possible.

### DNS resolution
<a name="web-crawler-dns-resolution"></a>

The Web Crawler uses DNS to resolve website hostnames (for example, `www.example.com`) to IP addresses. By default, it uses public DNS resolution.

When crawling sites inside a VPC, you may need to configure a private DNS server so the crawler can resolve hostnames for internal sites. Choose one of the following options based on your VPC configuration:

1. **Use the VPC-provided DNS server** — If your VPC has both **DNS hostnames** and **DNS resolution** enabled, you can use the default VPC DNS resolver (typically 10.0.0.2, or more generally the VPC CIDR base\$12). For more information, see [VPC](vpc-amazon-virtual-private-cloud.md).

1. **Use a custom DNS server** — If your VPC uses a custom DNS resolver, provide the IP address of your organization's internal DNS server. Work with your network administrator to obtain this address.

If you don't configure a DNS server, the crawler resolves only publicly registered hostnames.

### JavaScript-dependent navigation
<a name="web-crawler-javascript-navigation"></a>

**Symptoms:**
+ Only the seed URL is indexed, no additional pages discovered
+ Crawl completes successfully but returns only one document

**Resolution steps:**

1. Web Crawler executes JavaScript and renders page content, but does not simulate user interactions such as clicks, scrolls, or hover actions. If your site loads navigation links through user interaction (for example, click handlers, infinite scroll, or dynamic menus), the crawler cannot discover those links.

1. Inspect your page in browser developer tools to check if navigation links use standard `<a href="...">` elements. If links are wired through JavaScript event handlers instead, the crawler will not follow them.

1. If your site provides a sitemap, Web Crawler automatically checks for common sitemap paths on your seed URLs. Ensure your sitemap is available at a standard location (for example, `/sitemap.xml`) so the crawler can discover additional URLs without relying on in-page link extraction.

1. Alternatively, provide all target page URLs directly as seed URLs.

1. If content can be exported as HTML, PDF, or text files, consider using the Amazon S3 connector as your data source instead.

### Crawl and content issues
<a name="web-crawler-crawl-issues"></a>

**Symptoms:**
+ Missing or incomplete content
+ Incomplete crawls or early termination
+ Rate limiting errors (429 responses)
+ Content not being indexed properly

**Resolution steps:**

1. Review robots.txt restrictions:
   + Check robots.txt file for crawl restrictions.
   + Verify that the crawler is allowed to access target paths.
   + Ensure robots.txt compliance isn't blocking content.

1. Check rate limiting and throttling:
   + Monitor response headers for rate limit information.
   + Implement appropriate crawl delays.

1. Verify URL patterns and filters:
   + Test regex patterns for accuracy.
   + Check URL formatting and structure.
   + Validate include/exclude pattern logic.

1. Review content restrictions:
   + Check for noindex meta tags on pages.
   + Verify content type support.
   + Ensure content size is within limits.

1. Update the wait time so that the content loads on the page before the crawler starts crawling.

### Known limitations
<a name="web-crawler-integration-limitations"></a>

Web Crawler integration has the following limitations:
+ **URL limits:** Maximum of 10 seed URLs per dataset. You can't provide sitemap URLs in the seed URL field.
+ **Crawl depth:** Maximum crawl depth of 10 levels
+ **Security requirements:** HTTPS required for web proxy configurations

The following limitations apply when using the Web Crawler with a VPC connection:
+ **No HTTP/3 (QUIC) support:** HTTP/3 is not supported. Most sites will fall back to HTTP/2 automatically, but sites configured for HTTP/3 only will not be accessible.
+ **DNS over TCP required:** DNS resolution must use TCP. Verify that your DNS server supports DNS over TCP before configuring VPC crawling.
+ **Publicly trusted SSL certificates required:** Internal sites must use a certificate from a well-known certificate authority (for example, Let's Encrypt or DigiCert). Sites using self-signed or private CA certificates will fail to connect.
+ **IPv4 only:** Only IPv4 addresses are supported. Sites accessible exclusively over IPv6 cannot be crawled.

# Zendesk Suite integration
<a name="zendesk-integration"></a>

With Zendesk Suite integration in Amazon Quick, you can perform actions within Zendesk instances, including managing tickets, users, and customer support workflows. This integration supports action execution only and requires Amazon Quick Pro tier or higher.

## What you can do
<a name="zendesk-integration-capabilities"></a>

With Zendesk Suite integration, you can perform actions within your Zendesk instances through the action connector.

**Action connector**  
Create, update, and manage tickets, users, and customer support processes through the Zendesk API.

## Set up Zendesk integration
<a name="zendesk-integration-setup"></a>

Follow these steps to create your Zendesk integration:

1. In the Amazon Quick console, choose **Integrations**.

1. Choose **Zendesk Suite** from the integration options, click the Add (plus "\$1") button.

1. Fill in the integration details:
   + **Name** - Descriptive name for your Zendesk integration.
   + **Description** (Optional) - Purpose of the integration.

1. Choose your connection type:
   + **User authentication** - OAuth-based authentication for individual user access.
   + **Service authentication** - API key-based authentication for service access.

1. Fill in the connection settings based on your selected authentication method (either user or service):

   1. For **User authentication (OAuth)**, configure the following fields:
      + **Base URL** - Zendesk instance URL.
      + **Client ID** - Zendesk OAuth app client ID.
      + **Client Secret** - Zendesk OAuth app client secret.
      + **Token URL** - Zendesk OAuth token endpoint.
      + **Auth URL** - Zendesk OAuth authorization endpoint.
      + **Redirect URL** - OAuth redirect URI.

      Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`.

   1. For **Service authentication (API Key)**, configure the following fields:
      + **API Key** - Zendesk API token.
      + **Base URL** - Zendesk instance URL.
      + **Email** - Associated Zendesk user email.

1. Select **Create and continue**.

1. Choose users to share the integration with.

1. Click **Next**.

## Manage Zendesk integrations
<a name="zendesk-integration-management"></a>

After you create your Zendesk integration, you can manage it using these options:
+ **Edit integration** - Update authentication settings or Zendesk configuration.
+ **Share integration** - Make the integration available to other users.
+ **Delete integration** - Remove the integration and revoke authentication.

# Support escalation path
<a name="sharepoint-support-escalation"></a>

If you cannot resolve an issue for an integration using the troubleshooting steps, follow this escalation path:

1. Gather diagnostic information:
   + Integration configuration details
   + Error messages and timestamps
   + Steps to reproduce the issue
   + Environment details if applicable (Online vs. Server, version)

1. Check Amazon Quick service health and known issues in the console.

1. Contact AWS Support through the Amazon Quick console or AWS Support Center.

1. For complex authentication or permission issues, be prepared to involve your administrator.

# Bring Your Own Amazon Q Business Index (BYOI)
<a name="quick-byoa"></a>

Amazon Quick enables you to use your existing Amazon Q Business indexes as data sources. You can leverage your enterprise data without having to recreate indexes. This capability, known as Bring Your Own Index (BYOI), lets you connect your Amazon Q Business indexes to Amazon Quick and use them alongside other data sources for comprehensive analytics and intelligent responses.

BYOI supports two implementation methods:

**IDC Implementation**  
Uses IAM Identity Center for authentication. Requires both Amazon Q Business and Amazon Quick to authenticate through IAM Identity Center in the same AWS account and region.

**Non-IDC Implementation**  
Supports multiple authentication methods including native identities, AWS Managed Microsoft AD, and IAM federation. All Amazon Quick users automatically receive access to connected Amazon Q Business indexes.

**Topics**
+ [Overview of Amazon Q Business indexes in Amazon Quick](qbiz-indexes-overview.md)
+ [Prerequisites](qbiz-indexes-prerequisites.md)
+ [Supported authentication methods](qbiz-indexes-supported-authentication.md)
+ [Setting up permissions](qbiz-indexes-permissions.md)
+ [Creating knowledge bases from Amazon Q Business indexes](qbiz-indexes-creating-datasets.md)
+ [Sharing Amazon Q Business index knowledge bases](qbiz-indexes-sharing.md)
+ [Using Amazon Q Business index knowledge bases](qbiz-indexes-using.md)
+ [Limitations](qbiz-indexes-limitations.md)
+ [Billing](qbiz-indexes-billing.md)
+ [Feature comparison](qbiz-indexes-feature-comparison.md)
+ [Troubleshooting](qbiz-indexes-troubleshooting.md)
+ [Security best practices](qbiz-indexes-security.md)
+ [User types and capabilities](qbiz-indexes-user-types.md)
+ [Common use cases](qbiz-indexes-use-cases.md)
+ [Interacting with your Amazon Q Business indexes](qbiz-indexes-chat-interaction.md)

# Overview of Amazon Q Business indexes in Amazon Quick
<a name="qbiz-indexes-overview"></a>

Amazon Q Business indexes contain indexed enterprise data that you can now use directly in Amazon Quick. When you connect an Amazon Q Business index to Amazon Quick, it becomes available as a knowledge base. You can use it in spaces, agents, and automations, just like any other knowledge base in Amazon Quick.

Key benefits of using Amazon Q Business indexes in Amazon Quick include:

**Leverage existing data investments**  
Use your existing Amazon Q Business indexes and indexed data directly in Amazon Quick. You don't need to recreate indexes or upload the same data again.

**Unified analytics experience**  
Query across multiple data sources including Amazon Q Business indexes, uploaded documents, and structured data. Use Amazon Quick's unified analytical environment for all your data.

**Consistent security and permissions**  
Amazon Q Business index knowledge bases in Amazon Quick maintain the same security and access controls as in Amazon Q Business. Users only see content they have permission to access.

**Enhanced collaboration**  
Share Amazon Q Business index knowledge bases with other users in Amazon Quick, add them to spaces, and use them with agents and automations to create comprehensive business solutions.

# Prerequisites
<a name="qbiz-indexes-prerequisites"></a>

Before you can use Amazon Q Business indexes in Amazon Quick, ensure that you meet the following prerequisites:

## Common Prerequisites
<a name="qbiz-indexes-prerequisites-common"></a>
+ You have an existing Amazon Q Business index with indexed data.
+ Both the Amazon Q Business index and the Amazon Quick instance are in the same AWS account and region.
+ You have administrator permissions in Amazon Quick.

## IDC Implementation Prerequisites
<a name="qbiz-indexes-prerequisites-idc"></a>
+ AWS Identity Center is enabled and configured.
+ Both Amazon Q Business and Amazon Quick authenticate through IAM Identity Center.
+ The IAM Identity Center region and Amazon Q Business index region are the same.
+ You have access to both the Amazon Q Business index and AWS Identity Center administration.

# Supported authentication methods
<a name="qbiz-indexes-supported-authentication"></a>

The authentication methods supported depend on your implementation type:

## IDC Implementation
<a name="qbiz-indexes-auth-idc"></a>
+ Amazon Quick: AWS Identity Center authentication only
+ Amazon Q Business: `AWS_IAM_IDC`

## Non-IDC Implementation
<a name="qbiz-indexes-auth-qbiz"></a>
+ Amazon Quick:
  + Native identities (username/password)
  + AWS Managed Microsoft AD
  + IAM federation
+ Amazon Q Business: `AWS_QUICKSIGHT_IDP`

# Setting up permissions
<a name="qbiz-indexes-permissions"></a>

To use Amazon Q Business indexes in Amazon Quick, you need to set up the appropriate permissions based on your implementation method:

## Initial Setup
<a name="initial-setup"></a>

1. Sign in to the Amazon Quick console as an administrator.

1. Navigate to the **Admin** section.

1. Select **AWS Resources**.

1. Choose **Amazon Q Business** from the list of available data sources.

1. Choose **Select Applications**.

## Application Setup
<a name="application-setup"></a>

You can either connect to an existing Amazon Q Business application or create a new one:

1. Choose one of the following options:
   + **Connect to existing Amazon Q Business application** - Select an existing application from your account.
   + **Create new Amazon Q Business application** - Create a new application. The new application will use the same authentication used by your Amazon Quick instance setup.

1. For new applications, the system automatically configures authentication based on your Amazon Quick instance setup.

1. Wait for application creation to complete.

1. You will be redirected to the Amazon Q Business application to configure indexes and data sources.

## Access Management by Implementation
<a name="access-management"></a>

**IDC Implementation**  
+ Access is managed through AWS Identity Center.
+ Access to the Amazon Q Business application is managed through the Amazon Q Business console.

**Non-IDC Implementation**  
+ All Amazon Quick users automatically gain access to connected Amazon Q Business indexes.
+ No additional access management required in Amazon Q Business.

Once permissions are set up, you can use your Amazon Q Business index as a knowledge base in Amazon Quick, and Admin users can create knowledge bases from Amazon Q Business indexes.

# Creating knowledge bases from Amazon Q Business indexes
<a name="qbiz-indexes-creating-datasets"></a>

After setting up permissions, Admin or Admin Pro users can create knowledge bases from Amazon Q Business indexes:

1. Sign in to the Amazon Quick console as an Admin or Admin pro user.

1. Navigate to **Knowledge bases**.

1. Choose **Create knowledge base**.

1. Select **Amazon Q Business** as the data source.

1. Choose the Amazon Q Business index you want to use from the list of available indexes.

1. Provide a name and description for the knowledge base.

1. Choose **Create** to create the knowledge base.

**Note**  
If multiple Admin users create knowledge bases from the same Amazon Q Business index, these knowledge bases will functionally be identical.

# Sharing Amazon Q Business index knowledge bases
<a name="qbiz-indexes-sharing"></a>

Users who have access to an Amazon Q Business index in Amazon Q Business will automatically have the corresponding knowledge base in Amazon Quick shared with them when it is created. The knowledge base can be shared with other users after creation, but only the user who created the knowledge base can share it with other users.

In an IDC implementation, any changes to the permissions in Amazon Q Business application after the creation of knowledge base will not take effect in Amazon Quick.

If you are an admin and want to share the knowledge base with other users in Amazon Quick:

1. Navigate to **Knowledge bases**.

1. Select the Amazon Q Business index knowledge base you want to share.

1. Choose **Share**.

1. Select the users or groups you want to share the knowledge base with.

1. Choose **Share** to confirm.

# Using Amazon Q Business index knowledge bases
<a name="qbiz-indexes-using"></a>

Once created, Amazon Q Business index knowledge bases can be used in Amazon Quick just like any other knowledge base:

## Using in spaces
<a name="qbiz-indexes-in-spaces"></a>

Admins can add Amazon Q Business index knowledge bases to spaces:

1. Navigate to the space where you want to add the knowledge base.

1. Choose **Add resources**.

1. Select **Knowledge bases**.

1. Choose the Amazon Q Business index knowledge base from the list.

1. Choose **Add** to confirm.

## Using in output cards
<a name="qbiz-indexes-in-spaces-output"></a>

Admins can use Amazon Q Business index knowledge bases via Spaces in output cards.

## Using with agents
<a name="qbiz-indexes-in-agents"></a>

Admins can add Amazon Q Business index knowledge bases to custom agents:

1. Navigate to **Agents**.

1. Select an existing agent or create a new one.

1. In the agent configuration, choose **Add knowledge bases**.

1. Select the Amazon Q Business index knowledge base from the list.

1. Choose **Add** to confirm.

## Using with automations
<a name="qbiz-indexes-in-automations"></a>

Admins can add Amazon Q Business index knowledge bases to automations:

1. Navigate to **Automations**.

1. Select an existing automation or create a new one.

1. In the automation configuration, add a step that uses knowledge bases.

1. Select the Amazon Q Business index knowledge base from the list.

1. Configure the step and save the automation.

## Querying knowledge bases
<a name="qbiz-indexes-querying"></a>

Readers can query Amazon Q Business index knowledge bases through the Amazon Quick web application. However, a user will only be able to get a response from the Amazon Q Business index if they also have access to the Amazon Q Business application. To query the knowledge base:

1. Navigate to the Amazon Quick web application.

1. Select a space that contains the Amazon Q Business index knowledge base or use the default agent.

1. Enter your query in the chat interface.

1. View the response, which includes citations and clickable links to the source documents from the Amazon Q Business index.

# Limitations
<a name="qbiz-indexes-limitations"></a>

**Note**  
In an IDC implementation, when a Amazon Q Business knowledge base is first created in Amazon Quick, access to the knowledge base is automatically granted to users with access to the selected Amazon Q Business index. For additional users to have access to a knowledge base, the admin must configure user access in both the Amazon Q Business console and Amazon Quick knowledge base permissions pages.

When using Amazon Q Business indexes in Amazon Quick, be aware of the following limitations:

## General Limitations
<a name="general-limitations"></a>
+ Amazon Q Business index knowledge bases cannot be changed like other knowledge bases in Amazon Quick.
+ Amazon Q Business index knowledge bases only support the docs types supported by Amazon Q Business.
+ QApps, Actions, and Amazon Q Business chat guardrails are not included in the BYOI capability.
+ Amazon Q Business indexes must be in the same AWS account and region as Amazon Quick.

## IDC Implementation Limitations
<a name="idc-implementation-limitations"></a>
+ Both Amazon Quick and Amazon Q Business must use the same instance of IAM Identity Center.

## Index Quotas
<a name="index-quotas"></a>
+ You can connect up to two Amazon Q Business indexes per Region to Amazon Quick in the current release.
+ This quota cannot be increased.
+ Once indexes are selected and saved in a Amazon Quick instance, they cannot be directly unselected.

# Billing
<a name="qbiz-indexes-billing"></a>

When using Amazon Q Business indexes in Amazon Quick, billing works as follows:

## IDC Implementation Billing
<a name="idc-implementation-billing"></a>
+ You are billed for index and subscription costs in Amazon Q Business (recommended at least 1 user).
+ You are billed for subscription costs in Amazon Quick based on your Amazon Quick user subscriptions.
+ There are no additional charges for connecting Amazon Q Business indexes to Amazon Quick.

## Non-IDC Implementation Billing
<a name="qbiz-implementation-billing"></a>
+ No explicit Amazon Q Business subscription charges apply in this implementation model.
+ You are billed for subscription costs in Amazon Quick based on your Amazon Quick user subscriptions.

For more information about Amazon Quick pricing, see [Amazon Quick pricing](https://aws.amazon.com/quicksight/pricing/).

# Feature comparison
<a name="qbiz-indexes-feature-comparison"></a>

The following table compares key features between IDC and Amazon Q Business implementations:


| Feature | IDC Implementation | Non-IDC Implementation | 
| --- | --- | --- | 
|  User management  |  AWS Identity Center  |  Amazon Quick  | 
|  Amazon Quick authentication methods  |  Identity Center Only  |  Native identities (username/password), AWS Managed Microsoft AD, IAM federation  | 
|  Amazon Q Business authentication methods  |  `AWS_IAM_IDC`  |  `AWS_QUICKSIGHT_IDP`  | 
|  Share permissions  |  Amazon Q Business Console and Knowledge base permissions page  |  Amazon Quick Knowledge Base Permission page (Automatic)  | 
|  Index compatibility  |  All indexes  |  All indexes  | 

# Troubleshooting
<a name="qbiz-indexes-troubleshooting"></a>

## Amazon Q Business not seen in Integrations page
<a name="qbiz-not-seen-in-integrations"></a>

**Symptoms**
+ Amazon Q Business option missing from Integrations page
+ Cannot create new Amazon Q Business integration

**Resolution**
+ Only Admin users have access to create a Amazon Q Business/BYOI knowledge base
+ Verify user has Admin persona permissions

## Failed to fetch Amazon Q Business applications
<a name="failed-to-fetch-qbiz-applications"></a>

**Resolution**
+ Confirm Amazon Q Business is enabled in the Admin console
+ Try logging out and back in to refresh the session, then retry the operation

## Amazon Q Business application not seen in the list of applications displayed during knowledge base creation
<a name="qbiz-application-not-seen-in-list"></a>

**Symptoms**
+ Amazon Q Business applications list is empty on Create Knowledge Base page
+ Amazon Q Business applications list is populated but missing expected applications

**Resolution**
+ Check if missing Amazon Q Business applications were granted permissions in the AWS resources page of the Admin console

## Failed to create dataset. Chat instance is not ready. Please try again later
<a name="failed-to-create-dataset-chat-instance-not-ready"></a>

**Symptoms**
+ Knowledge base creation fails with error "Chat instance is not ready. Please try again later"
+ Unable to complete knowledge base creation process

**Resolution**
+ If this is the first time creating a knowledge base in Amazon Quick, wait 5 minutes and retry the operation

# Security best practices
<a name="qbiz-indexes-security"></a>
+ Regularly review access permissions
+ Monitor user activities
+ Implement least-privilege access
+ Maintain authentication method security

# User types and capabilities
<a name="qbiz-indexes-user-types"></a>

Different user types have different capabilities when working with Amazon Q Business indexes in Amazon Quick:

Amazon Q Business Administrator  
Manages Amazon Q Business indexes in the Amazon Q Business console.

Amazon Quick Administrator  
Enables permissions for Amazon Quick to access Amazon Q Business indexes in the same AWS account and region.

Amazon Quick Admin  
Creates knowledge bases from Amazon Q Business indexes, shares them with other users, and adds them to spaces.

Amazon Quick Admin  
Creates agents and automations that leverage Amazon Q Business index knowledge bases.

Amazon Quick Reader  
Uses agents and automations that leverage Amazon Q Business index knowledge bases, and queries these knowledge bases through the Amazon Quick web application.

# Common use cases
<a name="qbiz-indexes-use-cases"></a>

Here are some common use cases for using Amazon Q Business indexes in Amazon Quick:

**Finding relevant information**  
Query about specific topics across your enterprise data, such as HR policies, support documentation, or compliance guidelines.  
Example: "What is the maternity leave policy for my company in Washington state?" where national guidelines are in an Amazon Q Business index and state-specific information is in Amazon Quick.

**Business analytics and insights**  
Extract key findings from status updates across multiple groups or analyze the health of your product portfolio.  
Example: "Analyze the health of my product portfolio" where product sales data is in an Amazon Q Business index, and product engineering and support data is in Amazon Quick.

**Content creation and summarization**  
Create summaries or reports based on documents from multiple sources.  
Example: "Summarize last week's Service WBR and Sales update into a one-pager reflecting key initiatives" where the Service WBR is indexed in an Amazon Q Business index and the latest sales update is uploaded to Amazon Quick.

# Interacting with your Amazon Q Business indexes
<a name="qbiz-indexes-chat-interaction"></a>

Once you've connected your Amazon Q Business index to Amazon Quick, you can interact with it through chat using agents. 

1. From the left navigation menu in the console, select **Agents**.

1. From the **Actions** column for the agent you want to share, select the menu icon, and then select **Chat**.

1. You can then narrow down the resource to just the Knowledge Base created from the Amazon Q Business index by selecting the All Resources option and clicking on your Amazon Q Business index from the Knowledge Bases sub-tab.

When you ask questions, the agent analyzes data from your Amazon Q Business index alongside other data sources to provide comprehensive responses.

You can ask complex questions in plain language about your enterprise data and get detailed responses that draw from your Amazon Q Business index's indexed content. The chat interface allows you to:
+ Query your enterprise data using natural language
+ Get contextual responses that combine data from your Amazon Q Business index with other Amazon Quick data sources
+ View source citations with clickable references to see where information originated
+ Continue conversations and build on previous queries

For detailed information about using the chat interface and working with agents, see [Use a chat agent](use-agents.md).