1️⃣: AWS COMPREHEND - PII DETECTOR (FRONT-END) ==================================

📋 ELEMENT DESCRIPTION
--------------------------------
AWS COMPREHEND - PII DETECTOR (FRONT-END) provides LOCATE & REDACT PII ENTITIES (FRONT-END) action to detect and redact Personally Identifiable Information (PII) in text. The front-end element is suitable for applications when reactivity is desired, such as mobile applications.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 1) can be automatically performed by using this deployment template:
https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleComprehendSyncOnly&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSComprehendSyncOnly.yaml

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

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

1) Create your AWS COMPREHEND ACCESS KEY & SECRET ACCESS KEY, then add to the credentials the AWS COMPREHEND READ-ACCESS policy: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

2) Register on plugins.wiseable.io. Create a new Credential which associates your BUBBLE APP URL, AWS ACCESS KEY & SECRET ACCESS KEY.
The registration service will generate your PUBLIC ACCESS KEY. This key serves as a secure proxy for your real API key. It allows your application to communicate with the service without exposing your real API key. Since this PUBLIC ACCESS KEY is explicitly tied to your registered BUBBLE APP URL, it can only be used from that domain, ensuring that even if the key is publicly visible, it remains safe and cannot be misused by unauthorized sources.

3) Enter in the PLUGIN SETTINGS your PUBLIC ACCESS KEY (used for front-end element only) and AWS SERVICE ENDPOINT REGION (if not provided, default endpoint is "us-east-1").

4) Add the AWS COMPREHEND - PII DETECTOR (FRONT-END) element to the page on which the PII detection feature must be integrated. Select the RESULT DATA TYPE as Returned type, must always be set to "RESULT (COMPREHEND - PII DETECTOR)".

5) Integrate the logic into your application using the following AWS COMPREHEND - PII DETECTOR (FRONT-END) element's states and actions:

FIELDS:
- RESULT DATA TYPE: Returned type, must always be set to "RESULT (COMPREHEND - PII DETECTOR)".  

EVENTS:
- SUCCESS: Event triggered upon success
- ERROR: Event triggered upon error

EXPOSED STATES:
Use any element able to show/process the data of interest (such as a Group with a Text field) stored within the result of the following states of the AWS COMPREHEND - PII DETECTOR (FRONT-END) element:
- RESULTS: Populated upon SUCCESS event. Returns the redacted text and a list of detected PII entities along with type, confidence score, offset positions for each.
- ERROR MESSAGE: Populated upon ERROR event.
- IS PROCESSING: Set to true when processing is in progress, false otherwise.

ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
- LOCATE & REDACT PII ENTITIES (FRONT-END): Detect and redact PII entities in text. Populate RESULTS state upon completion.

Inputs Fields:
 - TEXT TO ANALYZE: A UTF-8 text string. Each string should contain at least 20 characters and must contain fewer that 5,000 bytes of UTF-8 encoded characters.
 - MASK: Character mask in redacted text.

2️⃣: LOCATE & REDACT PII ENTITIES (BACK-END)
==================================

📋 ACTION DESCRIPTION
--------------------------------
LOCATE & REDACT PII ENTITIES (BACK-END) returns the redacted text and a list of detected PII entities along with type, confidence score, offset positions for each.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 1) can be automatically performed by using this deployment template:
https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleComprehendSyncOnly&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSComprehendSyncOnly.yaml

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

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

1) Create your AWS COMPREHEND ACCESS KEY & SECRET ACCESS KEY, then add to the credentials the AWS COMPREHEND READ-ACCESS policy: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

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

3) Set up the "LOCATE & REDACT PII ENTITIES (BACK-END)" action in the workflow.
  Inputs Fields:
    - RESULT DATA TYPE: Returned type, must always be set to "RESULT (COMPREHEND - PII DETECTOR)".
    - TEXT TO ANALYZE: A UTF-8 text string in English language. Each string should contain at least 20 characters and must contain fewer that 5,000 bytes of UTF-8 encoded characters.
    - MASK: Character mask in redacted text.
  Output Fields:
    - RESULTS: Returns the redacted text and a list of detected PII entities along with type, confidence score, offset positions for each.

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

ℹ️ ADDITIONAL INFORMATION
======================
> PII universal entity types details: https://docs.aws.amazon.com/comprehend/latest/dg/how-pii.html#how-pii-types
> Country-specific PII entity types: https://docs.aws.amazon.com/comprehend/latest/dg/how-pii.html#how-pii-types-country

> AWS COMPREHEND service limits: https://docs.aws.amazon.com/comprehend/latest/dg/guidelines-and-limits.html#limits-all
> 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 Logs tab, "Server logs" section of your App Editor.
Make sure that "Plugin server side output" and "Plugin client side output" is selected in "Show Advanced".

For front-end actions, you can also open your browser's developer console (F12 or Ctrl+Shift+I in most browsers) to view detailed error messages and logs.

Always check the ERROR MESSAGE state of the element and implement error handling using the ERROR event to provide a better user experience.

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

⚡ PERFORMANCE CONSIDERATIONS
===========================

GENERAL
-------------
For back-end actions, the maximum retrievable result set is capped at 30 seconds duration time - this does not apply to front-end actions.

⏱️ BACK-END ACTION START DELAY
-----------------------------------------------
Each time a server-side action is called, Bubble initializes a small virtual machine to execute the action. If the same action is called shortly after, the caching mechanism kicks in, resulting in faster execution on subsequent calls.

A useful workaround is to fire a dummy execution at page load, which pre-warms the Bubble engine for the next few minutes, reducing the impact of cold starts for your users.

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