# Creating purpose-built *Amazon Q Apps* **Important** As of July 1, 2024, Amazon Q Apps are available only to [Amazon Q Business Pro users](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers). Amazon Q Business Lite users will no longer be able to create, run, or view Q Apps. To access, Q Apps, Lite users must upgrade to Amazon Q Business Pro. As of August 30, 2024, all Amazon Q Apps created by Lite users who did not upgrade their account to Amazon Q Business Pro have been deleted. You and your web experience users can create lightweight, purpose-built *Amazon Q Apps* within your broader Amazon Q Business application environment. Using your enterprise data, users can create a generative AI-powered app that streamlines their tasks. These Q Apps can be easily created by anyone at the click of a button, transforming their conversations with an Amazon Q Business assistant into reusable and shareable Amazon Q Apps. Teams across your organization can create Amazon Q Apps tailored to their specific workflows and business needs. When your Amazon Q Business assistant generates useful content, users can transform those conversations into reusable apps that automate repetitive tasks and ensure consistency. The following examples show how different teams might use Amazon Q Apps: **Example Marketing content generator** A marketing team member creates a Amazon Q App that generates social media posts following company branding guidelines. The app includes: + Input card: Product name and key features + Text output card: Generates professional post with company tone + Text output card: Creates social-media-friendly version Result: Team members can quickly generate consistent branded content for any product launch. **Example Employee onboarding assistant** An HR team creates a Amazon Q App to streamline new employee setup: + Input card: Employee name, department, start date + Plugin card: Creates Jira ticket for IT equipment setup + Text output card: Generates personalized welcome email + File upload card: Processes signed documents Amazon Q Apps is enabled by default when you create a new Amazon Q Business application environment using [IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html) or [IAM Federation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html) in the Amazon Q Business console. Amazon Q Apps can be accessed through the web experience. You can also create and manage Q Apps programmatically. For an more information, see [Amazon Q Apps](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Operations_QApps.html) in the *Amazon Q Business API Reference*. **Topics** + [Prerequisites for Amazon Q Apps](purpose-built-qapps-prerequisites.md) + [Managing Amazon Q Apps](purpose-built-qapps-manage.md) + [Using the web experience to create and run Amazon Q Apps](purpose-built-qapps-web-experience.md) + [Sharing Amazon Q Apps](qapps-private-sharing.md) + [Custom labels for Amazon Q Apps](qapps-custom-labels.md) + [Understanding and managing Verified Amazon Q Apps](verfied-apps-management.md) + [Data collection in Amazon Q Apps](q-apps-forms.md) + [Using plugins in Amazon Q Apps](qapps-plugins.md) # Prerequisites for Amazon Q Apps Before using Amazon Q Apps, make sure that you do the following: + **Set up your identity provider** – For web experience users to create and run their own Amazon Q Apps within a broader Amazon Q Business application environment, they must be recognized by either IAM Identity Center or AWS Identity and Access Management (IAM). These users can continue to authenticate either directly through IAM Identity Center, or through an existing enterprise identity provider connected to IAM Identity Center or IAM (like Okta, Microsoft Entra ID, and Ping Identity, among others). When users attempt to use an Amazon Q Business web experience, Amazon Q Apps authorizes their actions based on the user and group information it gathers from IAM Identity Center or IAM. To set up IAM Identity Center, see [Enable single sign-on access to your AWS applications (Application admin role)](https://docs.aws.amazon.com/singlesignon/latest/userguide/use-case-app-admin.html) in the *IAM Identity Center User Guide* . You need to complete this step before creating an Amazon Q Business application environment and using Amazon Q Apps. For a list of supported enterprise identity providers and how to connect them to your IAM Identity Center instance, see [Manage an external identity provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) in the *IAM Identity Center User Guide*. To set up AWS Identity and Access Management, see [Get started with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started.html) in the *AWS Identity and Access Management User Guide*. You need to complete setting up and connecting an identity provider to an IAM instance before creating an Amazon Q Business application environment and using Amazon Q Apps. For a list of supported enterprise identity providers and how to connect them to your IAM instance, see [Identity providers and federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html) in the *AWS Identity and Access Management User Guide*. For an example of how to set up an Amazon Q Business application environment with IAM federation using Okta as an example, see [Configuring an Amazon Q Business application using IAM Federation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html). **Important** As of July 1, 2024, Amazon Q Apps are available only to [Amazon Q Business Pro users](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers). Amazon Q Business Lite users will no longer be able to create, run, or view Q Apps. To access, Q Apps, Lite users must upgrade to Amazon Q Business Pro. As of August 30, 2024, all Amazon Q Apps created by Lite users who did not upgrade their account to Amazon Q Business Pro have been deleted. + **Finish the Amazon Q Business setup** – Complete [setting up Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/setting-up.html) and create an Amazon Q Business application environment integrated with either [IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html) or [AWS Identity and Access Management](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html). Configuring the application environment is necessary so that you can allow users to manage their own Amazon Q Apps. Also, include a retriever and, optionally, a data source connector. + **Create an IAM role** – Configure an AWS Identity and Access Management (IAM) access role (permissions policy) for the deployed web experience for your broader application environment, including permissions for Amazon Q Apps. The admin can use the Amazon Q Business console to create the required IAM role for users as part of the configuration steps. To view and modify the required IAM access role with set permissions and [optional permissions for web experience users to view and specify approved data sources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-experience-iam-role.html#deploy-data-source-iam-permissions ) with Amazon Q Apps, see the [IAM role for web experience users](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-experience-iam-role.html). **Note** If you are using permissions for Amazon Q Apps created prior to July 10, 2024, you must update your role with the new [Amazon Q Apps](deploy-q-apps-iam-permissions.md) permissions for your users to have access to use the [permissions to view and specify approved data sources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-q-apps-iam-permissions.html#deploy-data-source-iam-permissions) and other future features in Q Apps. + **Quotas** *(formerly known as limits)* — There are set maximum quotas for Amazon Q Apps. For information about these quotas, see [Quotas](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html#limits). # Managing Amazon Q Apps You can enable or disable the ability for web experience users to create and run their own Amazon Q Apps. To do this, use the feature settings for your broader application environment, as part of the [admin controls and guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html) in the Amazon Q Business console. You can also manage Amazon Q Apps through the console. You can view the list of all published Q Apps created within your broader application environment. To do this, select your application environment's *name* and then go to **Amazon Q Apps** in the navigation menu. From this list, you can remove one or more published apps from your library of Amazon Q Apps. # Using the web experience to create and run Amazon Q Apps After you enable Amazon Q Apps in the console, web experience users can then start creating, running, and publishing their own purpose-built Q Apps. Within the Amazon Q Business web experience, users can create an Amazon Q App from an existing conversation or prompt. Users can simply generate Q Apps in a single step from their conversation with Amazon Q Business or by describing their requirements using natural language prompts. To use the Amazon Q Business web experience, users must be granted access using IAM Identity Center. You share the endpoint URL of your web experience page with your users, who go to the URL and are authenticated to access the web experience. This endpoint URL is in the **web experience settings** of your application environment in the Amazon Q Business console. To create and run Amazon Q Apps, users go to the web experience endpoint URL and then select **Apps** from the navigation menu. For users to create an Q App from a conversation, once in a conversation, they can choose the **Create Amazon Q App** button to transform it into an app for use. Within **Apps**, users can try the example prompts by selecting the **Amazon Q Apps Creator** in the web experience. Users can create, edit, run, publish, and delete their apps. Users can also directly create an app by describing their requirements using natural language prompts in the **Amazon Q Apps Creator**. An Amazon Q App is made up of a collection of cards. A card is a UI element in the web experience that users can combine with other cards to create an app. Cards take a users' inputs, support file uploads, connect to other cards, generate text outputs, and allow actions through new and legacy [Amazon Q Business built-in plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/built-in-plugin.html) and [Amazon Q Business custom plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-plugin.html) (if activated), from within Q Apps. Users can select their Amazon Q App to add, edit, or delete a card. **Note** For tips on using effective prompting with Amazon Q Apps, see this [Community Article](https://repost.aws/articles/ARQ4zf4VpwQ1OOFjmhOQLWVg) on AWS re:Post. Text output and plugin cards contain *prompt* instructions that determine how Amazon Q Business is queried to generate a response. When your users use the **Amazon Q Apps Creator**, relevant cards are auto-generated with pre-filled prompts. Your users can further refine these prompts using simple, natural language. When writing or editing a prompt for a card, users can reference other cards using an *@ mention* to select a card from the list of cards in the app. Users can also instruct the cards to reference your enterprise data in Amazon Q Business or, they can specify a data source from a list of your available *data sources* ([requires additional IAM permissions from the admin](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-experience-iam-role.html#deploy-data-source-iam-permissions)). This allows users to focus the Q App's output on a particular subset of your data, rather than querying across the entire index. For example, an app that is built to summarize weekly sales updates by geography can have the output cards with results from the data source tied to a specific geography, rather than your company's entire data repository or the LLM's foundational knowledge. Users can then share the Amazon Q Apps that they have created with other web experience users. To do this, they open their Amazon Q App and then choose **Publish** to share it with other users through your company's Amazon Q Apps library. When you publish an app, you can also assign helpful labels to it to make them easier to group my subject matter or purpose. To have your published Q Apps become *Verified*, you'll need to work with your Amazon Q Business administrators. Admins can review your published apps and update the status to *Verified* if they determine the app meets your organization's criteria. When users access the Q Apps Library, they will see a distinct blue checkmark icon on any apps that have been marked as **Verified** by administrators. Verified apps are automatically surfaced to the top of the app list within each category, making them easily discoverable. . For more information, see [Understanding and managing Verified Amazon Q Apps](verfied-apps-management.md) Published Amazon Q Apps are made available in the your Amazon Q Apps library. The creator of an app can edit their own Amazon Q App and publish changes. This updates the app in the library. Other users can copy and customize a published Amazon Q App and create a new version. However, other users cannot edit the original app, only the creator can. Users can also show their support for a useful Amazon Q App by selecting the like button for the app in the library. **Note** If you update an Amazon Q App with a verified label, it will lose its verified status until the admin re-applies the label. Maintaining an app's *Verified * state requires ongoing collaboration with your administrators. # Sharing Amazon Q Apps Amazon Q Apps allows you to privately share your Q Apps with specific users within your Q Business application environment. This private sharing capability enables app creators to restrict app access to select users, providing more granular control over app visibility and usage within organizations. ## Benefits + **Controlled Access**: Share your Q Apps with only the intended users, maintaining privacy and security. + **Run-Only Mode**: Shared users can view and run the Q App but cannot make structural changes. To make structural changes, they will first need to duplicate it, which creates their separate, editable copy of the Q App. ## Key Concepts + Owner: The owner is the user who creates and has full editing rights over the Q App. As the owner, you can: + Privately share the Q App with other users by full email address. + Revoke access for shared users. + Edit the category for the shared Q App, which affects where it appears in the shared app user's library. + App User: A shared app user is a user within your organization's Q Business environment that the owner has shared the Q App with by email. As a shared user, you can: + View and run the shared Q App. + Duplicate the Q App to create an editable version. + Cannot directly edit the original shared Q App. Shared users do not receive a notification when a Q App is shared with them. You need to send them the link from the share modal. ## Prerequisites for Private Sharing Before your web experience users can use sharing you will need to update the web experience IAM role to enable private sharing in the web experience. We recommend updating the `DescribeQAppPermissions` `UpdateQAppPermissions` statement of the IAM policy attached to this role to include the action as follows: ``` { "Sid": "QAppsAppOwnerPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:UpdateQApp", "qapps:DeleteQApp", "qapps:ImportDocument", "qapps:ImportDocumentToQApp", "qapps:CreateLibraryItem", "qapps:UpdateLibraryItem", "qapps:StartQAppSession", "qapps:DescribeQAppPermissions", "qapps:UpdateQAppPermissions" ], "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:UserIsAppOwner": "true" } } } { "Sid": "QAppsPublishedAppPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:AssociateQAppWithUser", "qapps:GetLibraryItem", "qapps:CreateLibraryItemReview", "qapps:AssociateLibraryItemReview", "qapps:DisassociateLibraryItemReview", "qapps:StartQAppSession", "qapps:DescribeQAppPermissions" ], "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:AppIsPublished": "true" } } } ``` ### Sharing Amazon Q Apps ------ #### [ Web Experience ] **To privately share your Q App** 1. Open the Q App you want to share. 1. Choose on the "Share" button in the top right corner. 1. In the share modal, enter the email addresses of the users you want to share with, or you can toggle ‘Share with all’ to give access to everyone in your Q Apps organization. 1. Edit the category(s) for the shared Q App, which affects where it appears in the shared user's library. 1. (Optional) Choose the copy icon to obtain the link; this can then be sent to shared users via your preferred method (e.g., email or Slack). 1. Choose "Share" to complete the sharing process. The shared users will now be able to access and run your Q App from the library or via the shareable link you provide them. ------ #### [ AWS CLI ] To privately share your Q App with AWS CLI, use the `DescribeQAppPermissions` command. ``` aws qapps describe-q-app-permissions \ --instance-id instanceId \ --app-id appId ``` ------ ## Managing Shared Users As the owner, you can manage who has access to your shared Q App by revisiting the share modal: ------ #### [ Web Experience ] 1. To revoke access, choose the "Remove" button next to the user's email address. 1. To grant access to new users, enter their email addresses. 1. Choose "Share" to apply the changes. ------ #### [ AWS CLI ] To manage share user access with AWS CLI, use `UpdateQAppPermissions`. ``` aws qapps update-q-app-permissions \ --instance-id instanceId \ --app-id appId \ --grant-permissions listOfPermissions to be granted \ --revoke-permissions listOfPermissions to be revoked \ ``` ------ # Custom labels for Amazon Q Apps To organize and classify apps based on your unique business needs, Administrators can customize the labels available for published Q Apps. You can add up to 10 labels, and remove or update existing labels. Labels help web experience users find Q Apps in the library. For example, you might add custom HR organization-specific labels like *Employee onboarding* and *Benefits inquiries*. When members of your HR team create and use Q Apps, they can use these labels to classify them and help other users find the apps they need. **Topics** + [Prerequisites for customizing labels](#qapps-labels-prerequisites) + [Considerations for customizing labels](#qapps-labels-considersations) + [Customizing labels](#qapps-adding-custom-labels) ## Prerequisites for customizing labels Before your web experience users can use custom labels, the web experience IAM role for your application environment must have permission to perform the `qapps:ListCategories` action. We recommend updating the `QAppsResourceAgnosticPermissions` statement of the IAM policy attached to this role to include the action as follows: ``` { "Sid": "QAppsResourceAgnosticPermissions", "Effect": "Allow", "Action": [ "qapps:CreateQApp", "qapps:PredictQApp", "qapps:PredictProblemStatementFromConversation", "qapps:PredictQAppFromProblemStatement", "qapps:ListQApps", "qapps:ListLibraryItems", "qapps:CreateSubscriptionToken" "qapps:ListCategories" ], "Resource": "arn:aws:qbusiness:us-west-2:account-number:application/application-id" } ``` ## Considerations for customizing labels When you add labels, note the following: + The maximum number of labels for an application environment is 10. This includes predefined labels. + You can't add duplicate labels. + Labels can't include special characters. ## Customizing labels To customize labels available in an application environment for Q Apps, you can use the Amazon Q Business console or the following API operations. + [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_ListCategories.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_ListCategories.html) + [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchUpdateCategory.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchUpdateCategory.html) + [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchCreateCategory.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchCreateCategory.html) + [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchDeleteCategory.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_BatchDeleteCategory.html) After you save your changes, the label updates appear in the web experience immediately. If users don't see the changes, make sure you have configure permissions for the web experience IAM role for your application environment correctly. For more information, see [Prerequisites for customizing labels](#qapps-labels-prerequisites). The following shows how to customize Q Apps with the Amazon Q Business console or the AWS Command Line Interface. ### Console To customize labels for Q Apps, navigate to the **Q Apps** page for your application environment, choose the **Settings** tab, and add, update, or remove labels. **To customize labels** 1. Sign in to the AWS Management Console and open the Amazon Q Business console. 1. In **Applications**, choose the name of your application environment from the list of applications. 1. From the left navigation menu, choose **Enhancements**, and then choose **Amazon Q Apps**. 1. Choose the **Settings** tab, and add, update, or remove labels. 1. Choose **Save**. After you save your changes, the label updates appear in the web experience immediately. ### AWS CLI To customize labels with the AWS CLI, use the `list-categories`, `batch-update-category`, `batch-create-category` or `batch-delete-category`commands. + To view all custom labels for your application environment, use the `list-categories` command. ``` aws qapps list-categories --instance-id instanceId --region region ``` + If you have reached the 10 label limit, you can use the `batch-update-category` command to update an existing category name. ``` aws qapps batch-update-category \ --instance-id instanceId \ --categories '[{"id":"existingCategoryId","title":"updatedCategoryName"}]' \ --region region ``` + If you have less than 10 labels, you can use the `batch-create-category` command to add new labels. ``` aws qapps batch-create-category \ --instance-id instanceId \ --categories '[{"id":"uniqueId","title":"newCategoryName"}]' \ --region region ``` + To delete categories, use the `batch-delete-category` command. For `categories`, specify the list of IDs of the categories to be deleted. ``` aws qapps batch-delete-category \ --instance-id instanceId \ --categories '["categoryId1", "categoryId2"]' \ --region region ``` # Understanding and managing Verified Amazon Q Apps The Verified Q Apps feature empowers administrators to endorse published Amazon Q Apps. The goal is to enhance governance and provide a clear signal to end-users about which Q Apps are recommended for use within their organization. By labeling apps as *Verified*, admins can help improve trust and adoption of the most valuable, high-quality Q Apps created by employees. Admins can easily endorse published Q Apps by updating their status from *Default* to *Verified* directly within the Amazon Q Business console. The idea is that admins would work closely with their business stakeholders to determine the criteria for verifying apps, based on their organization's specific needs and policies. This admin-led labeling capability is a reactive approach to endorsing published apps, without gating the publishing process for app creators. When users access the Amazon Q Apps Library, they will see a distinct blue checkmark icon on any apps that have been marked as *Verified* by administrators. Additionally verified apps are automatically surfaced to the top of the app list within each category, making them easily discoverable. Users can also filter the library to view only Verified apps. **Note** If a Amazon Q App is unpublished and then re-published, or if changes are made to a *Verified* app, the verified label will be removed until the administrator re-applies it. **Topics** + [Considerations for verifying Amazon Q Apps](#verified-apps-considersations) + [Verifying Amazon Q Apps](#verified-apps-update) + [Restoring Amazon Q Apps to the default state](#default-apps-update) ## Considerations for verifying Amazon Q Apps To start using the Verified Apps feature in Amazon Q Apps, consider the following: + **Determine Verification Criteria:** Work with business stakeholders to establish the criteria for verifying Q Apps. This could include factors like content quality, alignment with organizational policies, and user feedback. + **Review Published Apps:** Review the list of published apps against your criteria. This can be accessed from the Amazon Q Business console or API. ## Verifying Amazon Q Apps To update an app state to verified you can use the console; or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateLibraryItem.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateLibraryItem.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI. ------ #### [ Console ] **To verify Amazon Q Apps** 1. Sign in to the AWS Management Console and open the Amazon Q Business console. 1. In **Applications**, select the name of your application environment from the list of applications. 1. From the left navigation menu, choose **Enhancements**, and then choose **Amazon Q Apps**. 1. In the **Amazon Q Apps in library** section, choose the Q Apps that you want to verify, and then choose **Update state**. 1. From the **Update state** drop down, choose **Verified**. ------ #### [ AWS CLI ] **To verify Amazon Q Apps** ``` // to add the verified label aws qapps update-library-item-metadata \ --instance-id instanceId \ --library-item-id libraryItemId \ --is-verified \ ``` ------ ## Restoring Amazon Q Apps to the default state All Amazon Q Apps are always in a *Default* state when they are first published or updated. To remove an Amazon Q App verified state and change it back to default you can use the console; or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateLibraryItem.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateLibraryItem.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI. ------ #### [ Console ] **To restore Amazon Q Apps state to default** 1. Sign in to the AWS Management Console and open the Amazon Q Business console. 1. In **Applications**, select the name of your application environment from the list of applications. 1. From the left navigation menu, choose **Enhancements**, and then choose **Amazon Q Apps**. 1. In the **Amazon Q Apps in library** section, choose the Q Apps that you want to verify, and then choose **Update state**. 1. From the **Update state** drop down, choose **Default**. ------ #### [ AWS CLI ] **To restore Amazon Q Apps state to default** ``` // to add the verified label aws qapps update-library-item-metadata \ --instance-id instanceId \ --library-item-id libraryItemId \ --no-is-verified \ ``` ------ # Data collection in Amazon Q Apps **Note** The Amazon Q Apps data collection feature is in preview and is subject to change. A data collection app is an Amazon Q App with one or more form cards that collect multiple pieces of information from app users. For example, you might use a data collection app to conduct team surveys, organize project retrospectives, collect ideas for next year's goals, or collect questions for a town hall. These apps can leverage generative AI to analyze the collected data, identify common themes, summarize ideas, and provide actionable insights. When creating a data collection app, you add one or more data collection form cards. You can also add output cards that use generative AI to analyze or summarize participants' data. For each form card, you add one or more text input fields. For example, a user can submit an idea and the reason to prioritize. Forms can be configured to allow multiple submissions by the same user. For example, users can submit multiple ideas for next year's goals. After you share your app, you and other users can open it and start collecting data. When anyone opens the app and starts a data collection, they become a data collection owner. An owner can own only one active data collection per app. More than one user can start a data collection for the same app. The data collection owner shares the data collection with participants, controls access to the forms and data collection results, and controls when to start and stop accepting submissions. As the owner of a data collection, choose when reveal or hide the data from the form. For example, your app might collect ideas from the team for next year. Based on the collected data, you can choose to hold off on revealing the responses and any generative AI analysis or summaries. **Topics** + [Permissions requirements](#qapps-forms-permissions) + [Data collection concepts](qapps-forms-data-collection-concepts.md) + [Creating a new Q App with a data collection form](qapps-forms-creating-app.md) + [Starting a new data collection](qapps-forms-starting-new-data-collection.md) ## Permissions requirements For users to create and use data collection apps, the web experience IAM role for your Amazon Q Business environment must have the following permissions for session resources: + qapps:GetQAppSessionMetadata + qapps:UpdateQAppSessionMetadata + qapps:ListQAppSessionData + qapps:ExportQAppSessionData For more information, including a policy example, see [IAM permissions for using Amazon Q Apps](deploy-q-apps-iam-permissions.md). # Data collection concepts This topic outlines specific concepts and features of Data collection forms in Amazon Q Apps. These concepts are key to understanding how to collect data from users with Amazon Q Apps. **Topics** + [Data collection](#qapps-forms-data-collection) + [Data collection form](#qapps-forms-data-collection-form) + [Creator](#qapps-forms-creator) + [Data collection owner](#qapps-forms-owner) + [User](#qapps-forms-user) + [Shareable link](#qapps-forms-shareable-link) + [Access control and security](#qapps-forms-access-control-and-security) ## Data collection A *data collection* is a pool of data that contains all participant responses submitted through the data collection form, as well as the configuration settings for how participants can access and submit data. Key aspects of data collections include the following: + Instantiation – After you publish your data collection app to the library, other users can open it and create a data collection. When a user creates a data collection, they become the data collection owner. Each owner has a unique shareable link they use control over which users participate. There can be multiple data collections for a single app. + Data isolation – Each data collection maintains its own separate pool of data. This ensures that each owner's data collection stays completely separate from any other owners' using the app. + Access control – The data collection owner creates and shares unique access links with participants. + Flexibility – Multiple owners can create data collections from the same data collection app. For example, you might have a Project Retrospective data collection app. Different owners can create new data collections for different projects from this same app. + Owner control – The owner manages access and data collection configuration. ## Data collection form A *data collection form* is a unique Amazon Q Apps card type that allows you to collect multiple pieces of information from participating users. You can add up to 20 data collection form cards per app. ## Creator A *creator* is the user who designs and builds the Q App with the data collection form. Creators have the ability to do the following: + Add data collection form cards. + Define the form's fields. + Set up and make changes to the overall structure of the Q App. + Initiate data collections (i.e., operate as the 'owner' of the data collection app) of the Q App tow collect data from different groups of users. + Can share, re-share, and unshare the Q App to and from the library. + Creators can be owners of a data collection associated with their own app. ## Data collection owner An owner is a user who opens a data collection app and configures a new data collection with a shareable link. Owners control the data collection, including access and submission settings. They can own only one active data collection per app. Key aspects of the Owner role include: + Data collection management – Owners control the data collection, including when to start and stop accepting responses. + Access control – Owners manage who can by access the data collection by sharing the link located in the data collection settings. + Advanced settings – Owners can use the data collection's advanced settings to allow users to submit data or see all collected data. This is important when the data collection is being used for sensitive information (e.g., personal identifying information (PII)). For more information, see [Access control and security](#qapps-forms-access-control-and-security). + Limited app editing capabilities – They can't make structural changes to the core data collection app (i.e., add, edit, and remove cards). ## User A user accesses a shared data collection app via the unique data collection link provided by the owner to submit data. Key aspects of the user role include – + Response submission – users can fill out and submit data using a form within the data collection. + Limited access – users cannot modify the form structure or manage data collection data collection settings. + Viewing data – Depending on controlled data collection settings, users may or may not be able to view other users' submissions. + Multiple submissions – users may be able to submit multiple inputs, based on the form's configuration. ## Shareable link A shareable link is a unique URL that provides access to a specific data collection app. Owners share this link with intended participants over a channel of their preference, such as email or slack. Key features of shareable links include: + Access control – Links are private and can only be accessed by users within the organization's Q Instance. + Data collection-specific – Each link corresponds to a particular data collection of the Q App. + Security – Links may have additional security measures, such as expiration dates or user authentication requirements. ## Access control and security The Data collection owner controls who can submit data and who can view the collected data. **Topics** + [Data access](#qapps-forms-data-access) + [Data visibility](#qapps-forms-data-visibility) + [Multiple submissions](#qapps-forms-multiple-submissions) + [Limitations](#qapps-forms-limitations) + [Security](#qapps-forms-security) ### Data access By default, the shareable data collection link allows anyone within your organization to submit data. As the owner, you can choose to: + Leave the data collection open for unlimited submissions. + Disable submissions at any time. ### Data visibility The visibility of submitted data is also controlled by the owner. By default, all users can view the collected data. You can choose to hide results and only reveal them when you're ready to review the data. This flexibility allows you to control the data collection form process – whether you want it to be an open, transparent exercise or a more controlled, private exercise. The owner maintains full control over the data collection settings and data access. Users can only submit data through the shared data collection link and view data based on the owner's permissions. ### Multiple submissions By default, data collection forms limit users to one response. When you add a data collection form, you can clear the **Limit users to one response** check box to allow for multiple submissions from each user within a data collection. If a user submits a form multiple times in the same data collection, all of their submissions are be saved. If you use a single submission form, only the recent submission is saved. ### Limitations The following are limitations for data collection apps 1. Isolated data usage – The collected data is confined to the Q App where they're created. You cannot combine them with other data sources or use different card output types within the same app. 1. Optional form fields – By default, form fields aren't required. Users can submit forms without completing all fields, potentially resulting in incomplete data. 1. Number of data collection cards:Creators can add up to 20 data collection form cards to a single Q App. ### Security All data collected through Amazon Q Apps data collection form are stored securely within your organization's Q Instance and are not accessible to anyone outside your organization. # Creating a new Q App with a data collection form To create a new data collection app, you create a new app, add a data collection form with one or more fields, and publish the app. 1. Go to your Amazon Q Business web experience URL. 1. In the navigation pane, choose **Apps**. 1. Choose one of four methods to start creating your Q App data collection form: + In **Recently used** choose the pencil icon. + Choose a tile that contains a **Data collection** pill + Describe your Q App data collection form use case in the text entry box and choose **Generate**. + Choose **Create blank app** + Choose **Explore the Q Apps library** to start with any existing apps your team may have already created and shared. 1. Choose **\$1 Add card** and choose **Data collection form**. 1. Choose the pencil icon on the data collection form. 1. For **Title**, give the form a name. 1. Under **Fields**, add one or more fields with field labels. + Choose **\$1 Add a field** to add more fields. + Choose the trash can icon to delete a field. 1. Choose **Save** to save the form. 1. Add any necessary output cards to analyze the collected data. Use `@cardname` to reference the data from the form card in the prompt. 1. When you are finished, the top right, choose **Share**. 1. Configure how you want to share the app and optionally edit its categories. 1. Choose **Share**. When complete, you can find the new app in your library. # Starting a new data collection You can start a new data collection with the web experience or with the Q Apps APIs. ## Web experience To start a new data collection, you open an app with a data collection form, configure data collection settings, and then copy and share the link to start collecting responses. 1. Go to your Amazon Q Business web experience URL. 1. In the navigation pane, choose **Apps**. 1. Locate and open an existing Q App that has a data collection form. 1. Choose **Start data collection** at the top right. 1. Enter a name for the data collection. For example, John Doe's All-Hands Meeting. You use this name when you reference the data from the form in other cards. For example, outputting an AI-generated summary of responses to an output card in the app. 1. In **Advanced settings**, configure the participant experience with the **Allow users to submit data** and **Allow users to see all collected data** check boxes. 1. Choose **Create**. 1. Choose the options to enable/disable form submissions and whether users can see others' data. 1. Choose the **Copy** icon to obtain the shareable link. 1. Choose **Save**. 1. Share the link directly with your users. As users respond to questions, you can do the following from your app: + To see user data, on the form collection card, choose **All data**. + To delete collected data, choose **Data collection settings** and choose **Delete collected data**. + To stop or restart collecting data, toggle the **Allow users to submit data** check box. ## Q Apps APIs Owners can start and manage data collections with the following APIs: + `StartQAppSession` - Start a new data collection. + `UpdateQAppSessionMetadata` - Update metadata for the data collection. For example, give the collection a name. + `UpdateQAppSession` - Optionally provide answers to your own data collection questions. + `ListQppSessionData` - List all submitted values for form cards. + `ExportQAppSessionData` - Export data in CSV format + `StopQAppSession` - Terminate the session For participants, use the following APIs: + `StartQAppSession` - Associate the user with the data collection. + `GetQAppSession` - Get the latest state of the data collection. Use this API before and after submitting data into form cards. + `ListQAppSessionData` - Get all submitted values for form cards. + `UpdateQappSession` - Submit data into form cards. # Using plugins in Amazon Q Apps If [plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html) are configured for your Amazon Q Business application environment you can add these to a Amazon Q Apps you're creating. Once you add a plugin to your Q Apps, your app users will be able to perform plugin actions from within your Q Apps. All plugins (new and legacy built-in plugins, and custom plugins) configured in the Amazon Q Business console will be available for Q App creators to use. **Important** You can add only one action per plugin card. The following section outlines how to add plugins to your Q Apps using both the AWS Management Console and the AWS CLI. **Topics** + [Prerequisites for adding plugins](#qapps-plugins-prerequisites) + [Adding plugins in Amazon Q Apps](#qapps-plugins-add) + [Using plugins in Amazon Q Apps](#qapps-plugins-use) ## Prerequisites for adding plugins Before your web experience users can create and use plugins, the web experience IAM role for your application environment must have the correct permissions to perform the necessary actions. We recommend updating your web experience IAM policy following the steps outlined in [Prerequisites for configuring Amazon Q Business built-in plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/basic-plugins-prereqs.html). ## Adding plugins in Amazon Q Apps To add a plugin to your Q App you can use either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_CreateQApp.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_CreateQApp.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI. **Note** You can also add a plugin to your Q App through your Amazon Q Business web experience URL. ------ #### [ Console ] **To add a plugin card to an Q App** 1. Sign in to the AWS Management Console and open the Amazon Q Business console. 1. In **Applications**, select the name of your application environment from the list of applications. 1. From the left navigation menu, choose **Enhancements**, and then choose **Amazon Q Apps**. 1. In the **Amazon Q Apps in library** section, choose the Q Apps that you want to add a plugin card to, and then select the web experience URL for that Q Apps. 1. From the Q Apps **App library** navigate to your app and select **Open**. 1. On the Q App page that opens, select **Add card**, and then select **Actions**. 1. From the **Actions** menu that opens up on the right, do the following: + For **Title** – Add a title for the card. + For **Plugin** – Select the plugin you want to add. Then, choose the actions you want your plugin to be able to perform. **Note** You can only add one action per plugin card. + For **Prompt** – In the prompt section, you get a dropdown of actions for the plugin you select. Once you select an action in the dropdown, your prompt will be populated with a recommended template that you can use for configuration. We recommend that Q App creators follow the generated prompt when writing their own prompts to achieve better results. 1. Select **Save**. ------ #### [ AWS CLI ] **To add a plugin to an Q App** ``` // Create an app with a single plugin card aws qapps create-q-app \ --title appTitle \ --instance-id qBusinessApplicationId \ --description pluginDescription \ --app-definition '{"cards":[{"qPlugin":{"type":"q-plugin","title":"Action Card","id":"cardUUID","pluginId":"QBusinessPluginId","actionIdentifier":"pa:jira:999.0_0:/rest/api/2/issue:POST","prompt":"Create a task in my project"}}]}' ``` ------ ## Using plugins in Amazon Q Apps To use a plugin within a Q App you can use either the Amazon Q Business web experience URL or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_StartQAppSession.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_StartQAppSession.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI. ------ #### [ Web experience ] **To use a plugin in an Q App** 1. From your **Q App** with plugins, select **Run**. A window will open up asking you to log in to your third party plugin account. 1. After you login, Q Apps displays a dialog box asking you to grant your Q App permission to access your third party plugin account. From the box, select **Allow**. **Note** If there are multiple plugins configured for a Q App, the authentication flow for the second app occurs after the first one. 1. After a successful connection, your plugin card will display a form where you can fill in the details for the action you are taking. 1. After filling in the details needed, select **Create**. Your plugin card displays a success message when your action completes successfully. ------ #### [ AWS CLI ] **To use a plugin in an Q App** ``` // start execution of an app aws qapps start-q-app-session \ --app-id fill in from create or get q app response \ --app-version fill in from create or get q app response \ --instance-id qBusinessApplicationId \ // If you have input cards that should be passed to the plugin: aws qapps start-q-app-session \ --app-id fill in from create or get q app response \ --app-version fill in from create or get q app response \ --initial-values '{"cardId":"fill in from create q app input or get q app response","value":"fill in"}' \ --instance-id qBusinessApplicationId \ // To get the status of an app, and results (if any): aws qapps get-q-app-session \ --session-id fill in from StartQAppSession response \ --instance-id qBusinessApplicationId \ //To provide follow up messages to an app that is waiting for additional input: aws qapps update-q-app-session \ --session-id fill in from StartQAppSession response \ -- values '{"cardId":"fill in","value":"fill in"}' --instance-id qBusinessApplicationId \ ``` ------