1️⃣: GOOGLE DOCUMENT AI - FORM OCR (FRONT-END DESKTOP & NATIVE MOBILE) =========================================================

📋 ELEMENT DESCRIPTION
--------------------------------
 GOOGLE DOCUMENT AI - FORM OCR (FRONT-END DESKTOP & NATIVE MOBILE) provides client-side processing for form extraction, offering improved responsiveness and user experience. The element supports a wide range of image formats and automatically handles format conversion and compression when needed.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 2) can be automatically performed by logging in into your Google Cloud Console, opening the Cloud Shell (top right corner of your page) and copy pasting this command and press enter:

 wget -q https://storage.googleapis.com/bubblegcpdemo/demo-assets/wiseable-gcp-documentai-sync-only.py && python3 wiseable-gcp-documentai-sync-only.py

 0) Set-up a project from Google Cloud Console : https://cloud.google.com/document-ai/docs/setup
 - Create or select a project
 - Enable the DOCUMENT AI API for that project
 - Create a service account
 - Download a private key as JSON.

 1) Open the private key JSON file with a text editor, copy/paste the following parameters from your file to the Plugin settings:
 - CLIENT_EMAIL
 - PROJECT_ID
 - PRIVATE_KEY, including the -----BEGIN PRIVATE KEY-----\\n prefix and \\n-----END PRIVATE KEY-----\\n suffix.

 2) Register on plugins.wiseable.io. Create a new Credential which associates your BUBBLE APP URL, GCP PROJECT_ID, CLIENT_EMAIL & PRIVATE_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 RONT-END & NATIVE MOBILE element only).

 4) Add the GOOGLE DOCUMENT AI - FORM OCR (FRONT-END DESKTOP & NATIVE MOBILE) element to the page on which the form extraction feature must be integrated. Select the RESULT DATA TYPE as Returned type, must always be set to "RESULT (DOCUMENT AI - FORM OCR)".

 5) Integrate the logic into your application using the following GOOGLE DOCUMENT AI - FORM OCR (FRONT-END DESKTOP & NATIVE MOBILE) element's states and actions:

FIELDS:
- RESULT DATA TYPE: Returned type, must always be set to "RESULT (DOCUMENT AI - FORM OCR)".

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 GOOGLE DOCUMENT AI - FORM OCR (FRONT-END DESKTOP & NATIVE MOBILE) element:
- RESULTS: Populated upon SUCCESS event. Returns a list of pages along with a list of fields' names and values along with the detected languages.
- ERROR MESSAGE: Populated upon ERROR event. Contains any error message that occurred during processing.
- IS PROCESSING: Set to true when processing is in progress, false otherwise.

ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
- ANALYZE FORM (FRONT-END DESKTOP & NATIVE MOBILE): Extract form fields from a file. Populates RESULTS state upon completion.

Inputs Fields:
 - FILE: File from the Bubble.io picture uploader, a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext) or a Google Storage URL (gs://bucket/file.ext). The RONT-END & NATIVE MOBILE element supports a wide range of image formats.
 - PROCESSOR ID: The ID of your processor. You will find this ID in your Google Cloud Console > Document AI > Processors > ID
 - PROCESSOR REGION: Your processor's region, for example: us - United States eu - European Union. You will find this location in your Google Cloud Console > Document AI > Processors > Region

2️⃣: ANALYZE FORM (BACK-END)
=======================

📋 ACTION DESCRIPTION
--------------------------------
 ANALYZE FORM (BACK-END) from a file returns a list of fields' names and values along with the detected languages.
 Google Document AI technology enables data entry tasks automation involving hand-filled surveys, applications and forms.
 It also includes OCR (Optical Character Recognition) technology to recognize machine printed text, and OMR (Optical Mark Recognition) for check boxes and multiple choice bubbles.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 2) can be automatically performed by logging in into your Google Cloud Console, opening the Cloud Shell (top right corner of your page) and copy pasting this command and press enter:

 wget -q https://storage.googleapis.com/bubblegcpdemo/demo-assets/wiseable-gcp-documentai-sync-only.py && python3 wiseable-gcp-documentai-sync-only.py

 0) Set-up a project from Google Cloud Console : https://cloud.google.com/document-ai/docs/setup
 - Create or select a project
 - Enable the DOCUMENT AI API for that project
 - Create a service account
 - Download a private key as JSON.

 1) Open the private key JSON file with a text editor, copy/paste the following parameters from your file to the Plugin settings:
 - CLIENT_EMAIL
 - PROJECT_ID
 - PRIVATE_KEY, including the -----BEGIN PRIVATE KEY-----\\n prefix and \\n-----END PRIVATE KEY-----\\n suffix.

 2) In your Google Cloud Console > IAM > PERMISSION > Add the DOCUMENT AI VIEWER permissions to the service account created at the step 0.

 3) In your Google Cloud Console > Document AI, create a FORM PARSER PROCESSOR. This PROCESSOR ID and REGION will be used in the following step: https://cloud.google.com/document-ai/docs/create-processor

 4) Set up the action "ANALYZE FORM (BACK-END)" in the workflow.
   Inputs Fields:
     - FILE: PDF, TIFF, JPG, PNG, BMP, WEBP or GIF file from the Bubble.io picture uploader, a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext). Maximum file size of 20 MB and of 10 pages.
     - PROCESSOR ID: The ID of your processor. You will find this ID in your Google Cloud Console > Document AI > Processors > ID
     - REGION: Your processor's region, for example: us - United States eu - European Union. You will find this location in your Google Cloud Console > Document AI > Processors > Region
     - RESULT DATA TYPE: Returned type, must always be set to "RESULT (DOCUMENT AI - FORM OCR)".
   Output Fields:
     - RESULTS: Returns a list of pages along with a list of fields' names and values along with the detected languages.

⚠️ Note: For back-end actions, the maximum retrievable result set is capped at 30 seconds duration time.


3️⃣: START & GET ANALYZE FORM OPERATION (ASYNC)
=====================================

📋 ACTION DESCRIPTION
--------------------------------
 START & GET ANALYZE FORM OPERATION (ASYNC) from a file returns a list of fields' names and values along with the detected languages.
 Google Document AI technology enables data entry tasks automation involving hand-filled surveys, applications and forms.
 It also includes OCR (Optical Character Recognition) technology to recognize machine printed text, and OMR (Optical Mark Recognition) for check boxes and multiple choice bubbles.  
 Asynchronous request mode, useful for large files and time-insensitive application.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ If you intend to store your files in Google Cloud Storage, please refer to the instructions of "GOOGLE STORAGE DROPZONE & UTILITIES" plugin (https://bubble.io/plugin/google-storage-dropzone--utilities-1616855011494x235332313714262000) first to setup your bucket. Then follow the instructions below.

The steps from 0) to 1) can be automatically performed by logging in into your Google Cloud Console, opening the Cloud Shell (top right corner of your page) and copy pasting this command and press enter:

 wget -q https://storage.googleapis.com/bubblegcpdemo/demo-assets/wiseable-gcp-documentai.py && python3 wiseable-gcp-documentai.py

Otherwise, follow these manual steps:

 0) Set-up a project from Google Cloud Console : https://cloud.google.com/document-ai/docs/setup
 - Create or select a project
 - Enable the DOCUMENT AI API for that project
 - Create a service account
 - Download a private key as JSON.

 1) Open the private key JSON file with a text editor, copy/paste the following parameters from your file to the Plugin settings:
 - CLIENT_EMAIL
 - PROJECT_ID
 - PRIVATE_KEY, including the -----BEGIN PRIVATE KEY-----\\n prefix and \\n-----END PRIVATE KEY-----\\n suffix.

 2) In your Google Cloud Console > Document AI, create a FORM PARSER PROCESSOR. This PROCESSOR ID and REGION will be used in the following step: https://cloud.google.com/document-ai/docs/create-processor

 3) Set up the action "START ANALYZE FORM OPERATION" in the workflow.
   Inputs Fields:
     - INPUT FILES: PDF, TIFF, JPG, PNG, BMP, WEBP or GIF list of files in Google Storage URL (gs://bucket/path/file.pdf) format.
     - MIME TYPE: A standard MIME type describing the format of the contents. Format type/subtype. Example: image/png, video/mp4. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17
     - OUTPUT BUCKET: Output Bucket to store the results.
     - OUTPUT PATH: Folder to store the results in.
     - PROCESSOR ID: The ID of your processor. You will find this ID in your Google Cloud Console > Document AI > Processors > ID
     - REGION: Your processor's region, for example: us - United States eu - European Union. You will find this location in your Google Cloud Console > Document AI > Processors > Region
   Output Fields:
     - OPERATION NAME: ID of the operation, to be reused in the "GET ANALYZE FORM OPERATION RESULTS".

 4) Set up the action "GET ANALYZE FORM OPERATION RESULTS" in a recurring workflow ('Do every x seconds'), to poll the operation completion status on a regular basis.
   Configure this recurring workflow to retrieve the results once the OPERATION STATUS is 'SUCCEEDED', using Only When' Event Condition,
   Inputs Fields:
     - RESULT DATA TYPE: Returned type, must always be set to "RESULT (DOCUMENTAI)".
     - OPERATION NAME: ID of the operation to poll, returned by "START ANALYZE FORM OPERATION" action.
     - REGION: Your processor's region, for example: us - United States eu - European Union. You will find this location in your Google Cloud Console > Document AI > Processors > Region.

   Output Fields:
     - RESULTS: Returns a list of pages along with a list of fields' names and values along with the detected languages.

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

ℹ️ ADDITIONAL INFORMATION
======================
> Supported file formats for back-end actions: PDF, TIFF or GIF.
> RONT-END & NATIVE MOBILE element supports a wider range of formats with automatic conversion.

> Supported Languages: https://cloud.google.com/document-ai/docs/processors-list#expandable-14

> GOOGLE DOCUMENT AI service limits: https://cloud.google.com/document-ai/quotas

⚠️ 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 client side output" is selected in "Show Advanced".

For RONT-END & NATIVE MOBILE 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
===========================

⏱️ 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.

For back-end actions, the maximum retrievable result set is capped at 30 seconds duration time - this does not apply to RONT-END & NATIVE MOBILE actions.

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