START & GET FACE DETECTION (ASYNC) ================================

ACTION DESCRIPTION
--------------------------------
 Detect faces along with emotions and landmarks within a MPEG-4 or MOV video, encoded using the H. 264 codec and stored in AWS S3.

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 FACE DETECTION (ASYNC) can be automatically performed by using this deployment template:
 https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleRekognition&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSRekognitionAsync.yaml

 You will find the required parameters values used across the plugin in the "OUTPUT" tab of the created stack.

Otherwise, follow these manual steps:

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

 1) Configure AMAZON REKOGNITION VIDEO by following ALL the instructions : https://docs.aws.amazon.com/rekognition/latest/dg/api-video-roles.html

   Write down your:
     - KEY & KEY SECRET
     - AWS SERVICE ENDPOINT REGION
     - NOTIFICATION ROLE ARN
     - SNS TOPIC ARN
     - SQS QUEUE URL  /!\ Make sure that SQS QUEUE encryption is disabled.

 2) In the Plugin Settings, enter the following :
     - AWS REKOGNITION 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 : Bucket Name to which the file will be saved.
      - AWS S3 FILE NAME : Path & File Name to save to. 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 FACE DETECTION 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 : AWS S3 file name for the input file. Enter here the video file from the Bubble.io uploader, or a Protocol-relative URLs (//server/video.mov), or a HTTPS video URL (https://server/video.mov). The video must be encoded using the H. 264 codec. The supported file formats are MPEG-4 and MOV.
       Example 1 : path1/path2/filename.ext.
       Example 2 : filename.ext if the file is at the root of the bucket.
   - NOTIFICATION ROLE ARN : ARN of an IAM role giving AWS REKOGNITION publishing permissions to the AWS SNS topic.
   - SNS TOPIC ARN : AWS SNS topic ARN to which AWS REKOGNITION posts the completion status.
   Output Fields:
     - JOBID : ID of the Job, to be reused in the "GET JOB STATUS FROM SQS" and "GET FACE DETECTION 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'), to poll the job completion status on a regular basis.
   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 REKOGNITION job status messages.
       - JOBID : ID of the job to poll, returned by "START FACE DETECTION 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 FACE DETECTION RESULTS" in the workflow.
   Inputs Fields :
     - JOB ID : ID of the job to poll, returned by "START FACE DETECTION JOB" action.
     - MAX RESULTS : Maximum results per paginated calls from AWS. The largest value you can specify is 1000, any greater value will 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 "RESULT (REKOGNITION)".
   Output Fields :
     - RESULTS: Returns the faces in the video. For each face, the operation returns face details. These details include a bounding box of the face, a confidence value (that the bounding box contains a face), and a fixed set of attributes such as facial landmarks (for example, coordinates of eye and mouth), presence of beard, sunglasses, emotions, and the timestamp.


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

ADDITIONAL INFORMATION
======================

> AWS REKOGNITION service limits : https://docs.aws.amazon.com/rekognition/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 that "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 usable file size 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.