Automate and implement version control for Amazon Kendra FAQs

Amazon Kendra is an intelligent search service powered by machine learning (ML). Amazon Kendra reimagines enterprise search for your websites and apps so your employees and customers can easily find the content they’re looking for, even when it’s scattered across multiple locations and content repositories across your organization.

Amazon Kendra’s FAQs allow users to upload frequently asked questions with their respective answers. This helps to consistently answer common queries among end users. As of this writing, when you want to update FAQs, you must delete the FAQ and recreate it. In this post, we present a simpler, faster approach to updating your Amazon Kendra FAQs (enabled). Our method eliminates the manual steps of creating and deleting FAQs as you update their content.

Solution overview

We use a fully deployable AWS CloudFormation template to create an Amazon Simple Storage Service (Amazon S3) bucket that becomes the source for storing your Amazon Kendra FAQs. Each index-based FAQ is stored in a folder with a prefix associated with the Amazon Kendra index.

This solution uses an AWS Lambda function that is triggered by an Amazon S3 event notification. When you upload an FAQ to an S3 folder mapped to a specific Amazon Kendra index, it creates a new version of the FAQ for your index. Old versions of the FAQ are only deleted after a new indexed version of the FAQ has been created, achieving near-zero downtime for index searches.

The following figure shows how our method creates and deletes a new version of the Amazon Kendra FAQ.

The steps of the work process are as follows:

1. A user uploads an Amazon Kendra FAQ document to an S3 bucket mapped to an Amazon Kendra index.
2. Amazon S3: PutObject event triggers a Lambda function that reads the event details.
3. The Lambda function creates a new FAQ version for each uploaded document target index and deletes old FAQ versions.
4. The Lambda function then publishes a message to the Amazon Simple Notification Service (Amazon SNS), which sends an email to the user notifying them that the FAQ was successfully updated.

Prerequisites:

Before you start exploring, you need an AWS account (you can sign up for one if you don’t have one). You should also create files that contain sample FAQs.

• main.csv – The following code is the FAQ CSV template:

  How many free clinics are in Spokane WA?, 13, https://www.freeclinics.com/
  How many free clinics are there in Mountain View Missouri?, 7, https://www.freeclinics.com/

• demo.json: – The following code is the FAQ JSON template:

  {
    "SchemaVersion": 1,
    "FaqDocuments": [
      {
        "Question": "How many free clinics are in Spokane WA?",
        "Answer": "13"
      },
      {
        "Question": "How many free clinics are there in Mountain View Missouri?",
        "Answer": "7",
        "Attributes": {
          "_source_uri": "https://www.freeclinics.com",
          "_category": "Charitable Clinics"
        }
      }
    ]
  }

• header_demo.csv: – The following code is an FAQ CSV template with the title:

  _question,_answer,_last_updated_at
  How many free clinics are in Spokane WA?, 13, 2012-03-25T12:30:10+01:00
  How many free clinics are there in Mountain View Missouri?, 7, 2012-03-25T12:30:10+01:00

Install the solution

The CloudFormation templates that create the resources used by this solution can be found in the GitHub repository. Follow the repository instructions to deploy the solution. AWS CloudFormation creates the following resources in your account:

• An S3 bucket that will be the source of the Amazon Kendra FAQ.
• Amazon Kendra index.
• AWS Identity and Access Management (IAM) role Amazon Kendra FAQ to read (GetObject) from bucket S3.
• A Lambda function configured to run on an Amazon S3 event. The feature is created outside of Amazon VPC.

Note that it may take approximately 30 minutes to create the resource.

After running the installation, you will receive an email. Choose Confirm subscription.

You have been redirected to a page confirming your subscription.

Verify that the Amazon Kendra index is listed in the Amazon Kendra dashboard. In this post, we called the Amazon Kendra index sample-kendra-index.

Upload a sample FAQ document to Amazon S3

In the previous step, you successfully deployed the CloudFormation stack. We use the stack output in the following steps:

1. On Results On the CloudFormation stack tab, specify its values S3Bucket (kendra-faq-<random-stack-id>) and: KendraIndex.
   
2. On the Amazon S3 dashboard, navigate to the S3 bucket created from the CloudFormation stack.
3. Choose Create a folder and create a folder called faq-<index-id>. For index-id:use the value you specified for the CloudFormation parameter KendraIndex. After creating the folder, this becomes its prefix sample-kendra-index FAQ:
   
4. Upload demo.json FAQ document in that folder.
   

Verify that the FAQ index has been created

To confirm that the index FAQ has been created, complete the following steps:

1. In the Amazon Kendra dashboard, navigate to the index sample_kendra_indexwhich was created as part of the deployment.
2. Navigate to FAQs page for this index to check if the FAQ is listed.

An index has a naming convention <file-name>-faq-<Date-Time>.

Once the FAQ has been successfully created, you will receive another email to let you know. You can upload new versions of the FAQ after receiving this email.

Note that the automation detects the file format to use when generating the FAQ by reading the uploaded file extension and, as an exception, the prefix. header_ for a CSV document with a header. The target Amazon Kendra index is identified by the name of the S3 bucket folder with the index ID as a suffix; for example faq-1f01abb8-341c-4921-ad16-139ee517a845.

Upload additional FAQ documents

Amazon Kendra FAQ supports three types of file formats: CSV, CSV_WITH_HEADERand: JSON. Make sure that when uploading a CSV file with a header, the filename must have a prefix header_ (this is only when you use the CSV file format with header in its content). Follow these steps to upload your FAQ documents:

1. Upload header_demo.csv file in the same folder.
   
2. Verify that the FAQ is created in the Amazon Kendra dashboard.
   

FAQ creation is case sensitive to the file format of the FAQ document you upload. For example, if you are uploading demo.json and: demo.JSON, both are treated as unique objects in Amazon S3. Therefore, this operation creates two FAQs such as demo-json-faq-22-09-2022-20-09-11 and: demo-JSON-faq-22-09-2022-20-09-11.

1. Upload demo.JSON.
   
2. Check that FAQ demo.JSON created in the Amazon Kendra console.
   

Create a new FAQ version of the index

The solution is now self-contained and can run independently when you upload a new version of an FAQ document to Amazon S3.

To test this, upload your newly updated version demo.json FAQ document faq-<index-id> folder. When you navigate to the index for FAQ, it will be named FAQ <file-name>-faq-<Date-Time>.

This solution creates a new FAQ version for the new version of the FAQ document uploaded to Amazon S3. When an FAQ is active, it deletes the old version of the FAQ for the same document.

Create an FAQ with a description

This solution also supports creating a FAQ with a description when files are named in a special way; <document_name>-desc-<your faq description>.fileformat[json|csv]. For example, demo-desc-hello world.json. Download this FAQ document faq-<index-id> folder.

After loading the document, the FAQ will be created and will have the description as specified in the file name.

You should use only -desc- when you need to add a description to the FAQ. If you are uploading a file with the same document_name prefix, it will delete the one created from the old FAQ document_name.fileformat FAQ document and create a new FAQ with a description.

Clear

For cleaning, perform the following actions:

1. Empty the S3 bucket created by the CloudFormation stack to store the FAQ documents. See Emptying the Bucket for instructions.
2. Delete the CloudFormation package. For instructions, see Deleting a Stack in the AWS CloudFormation Console.

Conclusion

In this post, we’ve introduced an automated way to manage your Amazon Kendra FAQs. After applying this solution, you should be able to create and delete FAQs by uploading them to an S3 bucket. This way, you save time by avoiding repetitive manual changes and inconsistent troubleshooting caused by unexpected operational incidents. You can also feel free to check out Amazon Kendra’s FAQs at your organization.

Do you have feedback on this post? Submit your comments in the comments section. You can also post questions in the AWS re:Post forum.

---

about the writer

Debit is a DevOps consultant who specializes in helping customers deliver secure and reliable solutions using AWS services. He focuses on infrastructure development and building serverless solutions using AWS and DevOps. Apart from work, Debojit likes to watch movies and spend time with his family.

Glenn Is a cloud architect at AWS. He uses technology to help clients achieve their desired outcomes on their cloud adoption journey. His current focus is DevOps and open source software development.

Shalabh is a senior consultant based in London. Its main goal is to help companies provide secure, reliable and fast solutions using AWS services. He is very excited about customer innovation with AWS and DevOps. Outside of work, Shalabh is a cricket fan and a passionate singer.