Amazon Textract Enhancer

- When a Textract job is submitted in asynchronous mode, using a request token, an unique job-id is created. For any subsequent submissions with same document, it prevents Textract from running the same job over again. Since in this solution, two different types of jobs are submitted, one for `DocumentAnalysis` and one for `TextDetection`, a DynamoDB table is used with `JobId` as HASH key and `JobType` as RANGE key, to track the status of the job. - In order to facilitate table scan with the document location, the table also use a global secondary index, with `DocumentBucket` as HASH key and `DocumentPath` as RANGE key. This information is used by the retrieval functions later when an API request is sent to obtain the tables, forms and lines of texts. - Upon completion of a job, post processing Lambda functions update the corresponding records in this DynamoDB table with location of the extracted files, as stored in S3 bucket, and other metadata such as completion time, number of pages, lines, tables and form fields.

- Lambda functions used in this solution prototype uses a common execution role that allows it to assume the role, to which required policies are attached.

- When submitting asynchronous jobs to Textract, an SNS topic needs to be specified, which textract uses to post the job completion messages. The messages posted to this topic would contain the same unique job-id that was generated and returned during submission API call. Subsequent retrieval calls will then use this job-id to obtain the results for the corresponding Textract jobs. - Since `DocumentAnalaysis` and `TextDetection` are separate job types, that requires post processing by different Lambda functions, two different SNS topics are used, in order to have a clear separation of channels. - The topic named `DocumentAnalysisJobStatusTopic` adds lambda protocol subscriptions for `TextractPostProcessTableFunction` and `TextractPostProcessFormFunction`. - The topic named `TextDetectionJobStatusTopic` adds lambda protocol subscription for `TextractPostProcessTextFunction`.

- In order to be able to publish job completion messages to specified SNS topic, Textract also needs to assume a role that has policies attahced, allowing publish access to the respective topics. This service role needs to be created and the ARN passed to textract with the asynchronous job submission.

- A Lambda function, named `TextractAsyncJobSubmitFunction` is used to invoke both `DocumentAnalysis` and `TextDetection` API calls to Textract. Several environment variables are passed to this function: - `document_analysis_token_prefix`: an unique string used to identify the document analysis jobs. This is used alongwith the bucket and document name to indicate to Textract the uniqueness of submissions. Based on this, Textract either runs a fresh job or responds with a job-id generated during a prior submission of same document. - `text_detection_token_prefix`: an unique string used to identify the text detection jobs. This is used alongwith the bucket and document name to indicate to Textract the uniqueness of submissions. Based on this, Textract either runs a fresh job or responds with a job-id generated during a prior submission of same document. - `document_analysis_topic_arn`: Specifies the SNS topic to which job completion messages for document analysis jobs will be posted. - `text_detection_topic_arn`: Specifies the SNS topic to which job completion messages for text detection jobs will be posted. - `role_name`: Textract service role to which policies allowing message publication to the two previously mentioned topics are added. - `retry_interval`: Value in seconds specifying how long the function should wait if a submission fails. When lot of submission requests arrive within a short time, either through exposed Rest API, or due to bulk upload of documents to S3 bucket, Textract API throughput exceeds. By waiting for a certain interval before retrying another attempted submission ensures that all documents gets their turn to be processed. - `max_retry_attempt`: Sometimes, due to large volume of requests, some might keep failing consistently. By specifying a maximum number of attempts, the solution allows us to gracefully exit out of the processing pipeleine. This feature, alongwith tracking metadata in DynamoDB table can then be used to manually submit the request later, using the Rest API interface. - The job submission function executes the following actions, when invoked: - Attach S3 access policy to the execution role it is using for itself (allowing invocation using documents either using own S3 buckets, or hosted on an external S3 bucket) - Submit document analysis job using `start_document_analysis` method - Submit text detection job using `start_document_text_detection` method - Create or update DynamoDB records for both job types

- There are 3 separate Lambda functions, all triggered when job completion messages are posted by Textract to the respective SNS topics. - A Lambda function, named `TextractPostProcessTableFunction` is triggered when a `DocumentAnalysis` job completion message is posted to `DocumentAnalysisJobStatusTopic`. Once invoked, this function executes following actions: - Obtain unique Job-Id and Document location from the posted message - Retrieve result of the analysis using `get_document_analysis` API - Parses the JSON dictionary from Textract response to extract all Table and Cell Blocks as a list of key value maps - Convert each map of Table and Cell blocks to generate an XML structure, using HTML tags to indicate tables, rows and columns - Save the extracted tables as one HTML file each under a upload folder marked by the job-id, created underneath the document location folder in the same S3 bucket - Update the DynamoDB record for the correpsonding JobId and JobType with completion information, result metadata (number of tables and pages), and the location on S3 bucket where the resulting files are uploaded. - A Lambda function, named `TextractPostProcessFormFunction` is triggered when a `DocumentAnalysis` job completion message is posted to `DocumentAnalysisJobStatusTopic`. Once invoked, this function executes following actions: - Obtain unique Job-Id and Document location from the posted message - Retrieve result of the analysis using `get_document_analysis` API - Groups all blocks present in the Textract response by block types, and selects all Keys and Values having child relationships - Gather all identified key-value pairs in a JSON dictionary - Save the JSON dictionary with key-value mappings as a file under a upload folder marked by the job-id, created underneath the document location folder in the same S3 bucket - Update the DynamoDB record for the correpsonding JobId and JobType with completion information, result metadata (number of form fields ), and the location on S3 bucket where the resulting file is uploaded. - A Lambda function, named `TextractPostProcessTextFunction` is triggered when a `TextDetection` job completion message is posted to `TextDetectionJobStatusTopic`. Once invoked, this function executes following actions: - Obtain unique Job-Id and Document location from the posted message - Retrieve result of the analysis using `get_document_text_detection` API - Groups all blocks present in the Textract response by block types, and captures all texts by selecting all Line type blocks that are present as children of Page type blocks - Gather all identified lines of texts as a JSON dictionary with Line number being the key and Line text the value - These dictionary elements are nested within outer dictionary with Page number as keys - Save the extracted lines as JSON file under a upload folder marked by the job-id, created underneath the document location folder in the same S3 bucket - Update the DynamoDB record for the correpsonding JobId and JobType with completion information, result metadata (number of pages and lines), and the location on S3 bucket where the resulting files are uploaded.

- An S3 bucket is used as a staging area where the documents that needs to be analysed are uploaded. The same bucket is also used to store the analysis results. - This bucket is configured with triggers such that whenever a document image (PDF or JPEG) is uploaded, the lambda function for job submission gets triggered, and submits the uploaded document to Textract for processing. - Bucket policy attached to this bucket is used to extend read/write access to this bucket for the Lambda execution role. The advantage of doing so instead of adding policy statements with S3 access during the execution role declaration is that, it serves to show how such access can be extended and revoked at run-time. In fact, when the job submission function is triggered by invoking the API method with external bucket name, the submission function first creates a policy to grant the Lambda execution role with required read/write access to the specified bucket.

- After the post processing is completed the results are stored in JSON and HTML files (as appropriate) under the folders marked by unique Job-Ids for the corresponding documents. - The solution includes two Lambda functions - `TextractDocumentAnalysisResultRetrievalFunction` and `TextractTextDetectionResultRetrievalFunction`, that when invoked with document name and bucket location, scans the DynamoDB table to get the document metadata, and returns the same, alongwith actual content of the resulting files, fetched from the S3 bucket location. - The retrieval functions provides a way for on-demand querying of the Textract results, without actually sending a request to Textract everytime the document results are needed.

- Retrieval functions can be used programmatically to acces the Textract results anytime, but that works only when the user is an authenticated IAM user of the same AWS account. Rest APIs, created using Amazon API Gateway expands this capability to outside the account boundary. - The Rest API exposes an endpoint method to trigger a Textract job submission, and two endpoints to extract the results of document analysis and text detection. - `submittextanalysisjob` method can be invoked with two parameters - Bucket and Document, which in turn invokes `TextractAsyncJobSubmitFunction` Lambda function and submits the specified document for document analysis and text detection processing. - `retrievedocumentanalysisresult` method can be invoked with parameters - Bucket, Document, and optionally ResultType, which in turn invokes `TextractDocumentAnalysisResultRetrievalFunction` Lambda function to return tables, forms or both. - `retrievetextdetectionresult` method can be invoked with parameters - Bucket, Document, which in turn invokes `TextractTextDetectionResultRetrievalFunction` Lambda function to return lines of texts grouped by pages.