START & GET ANALYZE LENDING (ASYNC) ========================================

ACTION DESCRIPTION
--------------------------------
 ANALYZE LENDING in a JPEG, PNG, PDF file stored in AWS S3 to return structured and normalized lending data from a loan package.
 Asynchronous request mode, useful for large files and time-insensitive application.

STEP-BY-STEP SETUP
--------------------------------
If you do not have AWS S3 configured yet, the configuration steps can be automatically performed by using this deployment template:
https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleS3&param_BucketName=BucketNameOfYourChoice&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSS3Plugin.yaml

 You will find the required parameters values used to configure your AWS S3 plugin, for which "AWS S3 DROPZONE & SQS UTILITIES" is suggested, in the "OUTPUT" tab of the created stack.

The steps from 0) to 3) b) of START & GET ANALYZE LENDING (ASYNC) can be automatically performed by using this deployment template:
 https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleTextract&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSTextractAsync.yaml

 0) Sign-up for AWS TEXTRACT : https://console.aws.amazon.com/textract/home?p=txt&cp=bn&ad=c

 1) Configure AWS TEXTRACT FOR ASYNCHRONOUS OPERATION by following ALL the instructions : https://docs.aws.amazon.com/textract/latest/dg/api-async-roles.html

   Write down your:
     - KEY & KEY SECRET
     - AWS SERVICE ENDPOINT REGION
     - NOTIFICATION ROLE ARN
     - SNS TOPIC ARN
     - QUEUE URL

 2) In the Plugin Settings, enter the following :
     - AWS TEXTRACT API KEY & SECRET
     - AWS SERVICE ENDPOINT REGION (if not provided, default endpoint is "us-east-1").

 3) Set-up in your workflow an action returning the BUCKET and KEY of your file to analyze.
   a) If you do not already have such action, install the plugin "AWS S3 & SQS UTILITIES"
   b) Create a AWS S3 BUCKET that will be used to store the file to analyze: https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html
   c) Set up the "PUT FILE TO S3" action in the workflow.
     Inputs Fields:
       - FILE URL TO STORE : The file URL from the Bubble.io uploader, or a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext). The file must be accessible through the HTTPS protocol.
       - AWS S3 BUCKET NAME : AWS S3 Bucket Name to which the file will be saved.
       - AWS S3 FILE NAME : Path & Name of the file to put to AWS S3. The format must be [path/]filename.ext.
           Example 1: path1/path2/filename.ext.
           Example 2: filename.ext if the file is at the root of the bucket.

 4) Set up the "START ANALYZE LENDING JOB" action in the workflow.
   Inputs Fields:
   - AWS S3 BUCKET NAME : AWS S3 bucket name from which the input file will be read.
   - AWS S3 FILE NAME : Path & Name of the JPEG, PNG, PDF file to get from AWS S3. The format must be [path/]filename.ext.
       Example 1 : path1/path2/filename.ext.
       Example 2 : filename.ext if the file is at the root of the bucket.
   - NOTIFICATION ROLE ARN : The ARN of an IAM role giving AWS TEXTRACT publishing permissions to the Amazon SNS topic.
   - SNS TOPIC ARN : The AWS SNS topic ARN to which AWS TEXTRACT posts the completion status.
   Output Fields:
     - JOB ID : ID of the Job, to be reused in the "GET JOB STATUS FROM SQS" and "GET ANALYZE LENDING RESULTS".

 5) Install the plugin "AWS S3 & SQS UTILITIES"
   Set up the action "GET JOB STATUS FROM SQS" in a recurring workflow ('Do every x seconds') AWS TEXTRACT job status messages with the JOBID.
   Configure this recurring workflow to execute the next step once the job status is SUCCEEDED, using 'Only When' Event Condition, to retrieve the results.
     Inputs Fields :
       - QUEUE URL : URL of AWS SQS you set up at step 1, used to poll for AWS TEXTRACT job status messages.
       - JOBID : ID of the job to poll, returned by "START ANALYZE LENDING JOB" action.
     Output Fields:
       - JOB STATUS : Valid values are SUCCEEDED, POLLING, IN_PROGRESS, PARTIAL_SUCCESS and FAILED or ERROR, with error or failure messages being appended to the status.

 6) Set up the action "GET ANALYZE LENDING RESULTS" in the workflow.
   Inputs Fields :
     - JOB ID : ID of the job to poll, returned by "START ANALYZE LENDING JOB" action.
     - MAX RESULTS : Maximum results per paginated calls from AWS. The largest value you can specify is 1000, any greater value wil return 1000 results. The default value is 1000. This plugin auto-paginates AWS response based on this parameter.
     - OUTPUT TYPE : Returned type, must always be set to "RESPONSE (TEXTRACT)".
   Output Fields :
     - RESPONSE : Returns a list of RESULTS containing the structured lending data from the mortgage package and WARNINGS, containing errors if any during processing.

IMPLEMENTATION EXAMPLE
======================
Feel free to browse the app editor in the Service URL for an implementation example.

ADDITIONAL INFORMATION
======================
> Supported Files Type: https://docs.aws.amazon.com/textract/latest/dg/lending-response-objects.html#lending-document-types

> AWS TEXTRACT service limits : https://docs.aws.amazon.com/textract/latest/dg/limits.html
> AWS services availability per region : https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/
> AWS Service endpoints list : https://docs.aws.amazon.com/general/latest/gr/rande.html

TROUBLESHOOTING
================

Any plugin related error will be posted to the the Logs tab, "Server logs" section of your App Editor.
Make sure  "Plugin server side output" and "Plugin server side output" is selected in "Show Advanced".

> Server Logs Details: https://manual.bubble.io/core-resources/bubbles-interface/logs-tab#server-logs

PERFORMANCE CONSIDERATIONS
===========================

GENERAL
-------------
 The largest retrievable result-set from AWS TEXTRACT depends on the capacity units your app can use on Bubble.io (see Capacity Boost or Professional Plan, the highest limit being capped by Bubble.io's Workflow Action maximum execution time to perform the response parsing operation.

QUESTIONS ?
===========
Contact us at [email protected] for any additional feature you would require or support question.