Google Cloud Storage Dropzone

0 : GOOGLE CLOUD STORAGE DROPZONE =============================

ELEMENT DESCRIPTION
--------------------------------
GOOGLE CLOUD STORAGE is a visual element allowing to drop or select single- or multi-files supporting uploading, opening and deleting files.

STEP-BY-STEP SETUP
--------------------------------
The steps from 0) to 2) d) 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-dropzone.py && python3 wiseable-gcp-dropzone.py

Otherwise, follow these manual steps:

 0) Set-up a project from Google Cloud Console : https://cloud.google.com/speech-to-text/docs/libraries#setting_up_authentication
 - Create or select a project
 - Enable the GOOGLE CLOUD STORAGE 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) a) Create a bucket: https://cloud.google.com/storage/docs/quickstart-console#create_a_bucket

 2) b) Open your BUCKET, tab PERMISSION, set the following as follow:
     - ACCESS CONTROL: FINE-GRAINED
     - PUBLIC ACCESS PREVENTION: NOT ENABLED BY ORG POLICY OR BUCKET SETTING
     - PUBLIC ACCESS STATUS: SUBJECT TO OBJECT ACLS

 2) c) Grant permissions to the service account:
 - Go to the IAM & ADMIN, ROLES section : https://console.cloud.google.com/iam-admin/roles
 - If not already preselected, select the PROJECT_ID defined before
 - Click on CREATE ROLE, enter a CUSTOM ROLE NAME
 - Click on ADD PERMISSIONS and in FILTER PERMISSIONS BY ROLE
 - Select STORAGE OBJECT ADMIN and STORAGE OBJECT CREATOR to grant the read/write permissions in GOOLE STORAGE buckets
 - SAVE the permissions
 - GO back to IAM & ROLES, IAM section : https://console.cloud.google.com/iam-admin
 - Click on ADD, enter in NEW MEMBERS the CLIENT_EMAIL defined before
 - Select the CUSTOM ROLE name created before, and SAVE.

 2) d) Set the CORS configuration by opening the GOOGLE CLOUD CONSOLE by clicking on the top-right corner icon.

 Execute:
   echo '[
           {
               "origin": [
                   "*"
               ],
               "responseHeader": [
                   "X-Requested-With",
                   "Access-Control-Allow-Origin",
                   "Content-Type"
               ],
               "method": [
                   "GET",
                   "POST",
                   "HEAD",
                   "PUT"
               ],
               "maxAgeSeconds": 3600
           }
       ]' > cors.json

 Execute:
   gsutil cors set cors.json gs://bucket-name

 3) Drap and drop up the visual element GOOGLE CLOUD STORAGE DROPZONE in your app, containing the dropzone.

 4) Select the GOOGLE CLOUD STORAGE DROPZONE element, in APPEARANCE section, configure the following fields :
 
 FIELDS :
 - OUTPUT TYPE : Returned type. Must always be set to FILE METADATA (GOOGLE CLOUD STORAGE DROPZONE).
 - ACCEPTED FILES TYPES : Either a case-insensitive filename extension, Format .ext. Example: .jpg, .pdf, or .doc. Or a standard MIME type, with no extensions. The string audio/* matches any audio file. The string video/* matches any video file. The string image/* matches any image file. Format type/subtype. Example: image/png, video/mp4. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17. Leave empty to accept any types.
 - CAPTURE TYPE : When capturing live media on mobile devices, specifies either the user-facing or environment-facing media input to use, such as camera or microphone. Supported values: user | environment
 - UPLOAD MULTIPLE FILES : Enable multi-file upload.
 - RETAIN FOLDER STRUCTURE : Retain folder structure when uploading a folder.
 - MAX FILE SIZE : Maximum allowed file size in MiB.

  THUMBNAIL SETTINGS
 - THUMBNAIL MAX WIDTH : If set, the thumbnail will be generated and resized to this maximum width before upload. The other dimension will be adjusted proportionally to maintain the aspect ratio and avoid distortion.
 - THUMBNAIL MAX HEIGHT : If set, the thumbnail will be generated and resized to this maximum height before upload. The other dimension will be adjusted proportionally to maintain the aspect ratio and avoid distortion.
 - THUMBNAIL QUALITY : If set, the thumbnail will be generated and compressed to the specified quality. The higher the number the higher the quality. Valid range is 0.0-1.0.
 - MAX FILE SIZE : When the file exceeds this limit, the thumbnail will not be generated
 
  IMAGE RESIZING & COMPRESSION
 - MAX WIDTH : If set, the image will be resized to this maximum width before upload. The other dimension will be adjusted proportionally to maintain the aspect ratio and avoid distortion.
 - MAX HEIGHT : If set, the image will be resized to this maximum height before upload. The other dimension will be adjusted proportionally to maintain the aspect ratio and avoid distortion.
 - IMAGE QUALITY : Image quality. The higher the number the higher the quality. Valid range is 0.0-1.0.

 5) Integrate the logic into your application using the following GOOGLE CLOUD STORAGE DROPZONE, states and actions:

 EVENTS :
 - ACCEPTED FILE LOOP : Event which is triggered for each accepted file, satisfying the ACCEPTED FILES TYPES and MAX FILE SIZE (MIB). The workflow started by this event must contains the GET UPLOAD PRESIGNED EXPIRING URL action to generate and pass the URL to the UPLOAD CURRENT FILE element action to upload the file.
 - REJECTED FILE LOOP : Event which is triggered for each rejected file, e.g. not satisfying the ACCEPTED FILES TYPES or the MAX FILE SIZE (MIB).
 - UPLOADED FILE LOOP : Event which is triggered after each successful file upload.
 - ALL FILES UPLOADED : Event which is triggered when all files have been uploaded.

 
 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 CLOUD STORAGE DROPZONE element :
 - ACCEPTED FILES : List of files' metadata satisfying the ACCEPTED FILES TYPES criteria in the dropzone. The available metadata are
     file_name - name of the dropped file.
     upload_percentage - number between 0 and 100 showing the upload progress.
     file_size_bytes - size of the file in bytes.
     thumbnail_preview_data - base 64 encoded image data.
     thumbnail_width- width of the thumbnail.
     thumbnail_height- height of the thumbnail.
     status - added, queued, uploading, error, success.
       added - means the file is dropped to the dropzone and the destination URL is not assigned.
       queued - means to URL is assigned but there are other files uploading (2 files are uploaded at the same time).
       uploading - file is uploading.
       error - there was an error during the upload.
       success - upload is successful.
     uuid - is a random identifier of this file.
     upload_filepath - Path & File Name. The format is [path/]filename.ext.
     upload_bytes_sent - upload progress in bytes.
 - CURRENT FILE : Current file's metadata being uploaded and cleared once completed. The available metadata are same as above state.
 - LATEST UPLOADED FILE : Latest uploaded file's metadata, accessible while the next file is not successfully uploaded. The available metadata are same as above state.
 - REJECTED FILES : List of rejected files’ metadata. Same metadata as ACCEPTED FILES added the following:
     message - rejection reason.
 - TOTAL UPLOAD PROGRESS : Number between 0 and 100 showing total uploaded bytes divided by the upload list’s file's size.
 - DRAGGING OVER : Returns true if a file is dragging over the dropzone, else otherwise.

 ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
   - UPLOAD CURRENT FILE : Triggers the uploading of the CURRENT FILE via the presigned UPLOAD URL.
   - REMOVE FILE : Removes the specified file in the dropzone, identified by its UUID.
   - RESET : Reset the dropzone to its initial state.
   - CANCEL UPLOAD : Cancel the specified file being uploaded, identified by its UUID.

1 : GET UPLOAD PRESIGNED EXPIRING URL
===============================

ACTION DESCRIPTION
--------------------------------
 GET UPLOAD PRESIGNED EXPIRING URL generates an URL allowing uploading for the specified bucket and path. This action is used in conjunction with the GOOGLE CLOUD STORAGE DROPZONE visual element.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2 of the first action of this documentation.

 3) Set up the "GET UPLOAD PRESIGNED EXPIRING URL" action in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name of the file.
     - PATH & FILE NAME : Path & File Name to process. 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.
   Output Fields :
     - URL : Returns the presigned expiring URL.

2 : GENERATE DOWNLOAD PRESIGNED EXPIRING URL
===========================================

ACTION DESCRIPTION
--------------------------------
 GENERATE DOWNLOAD PRESIGNED EXPIRING URL generates an URL allowing access to the specified object, expiring after the specified duration. The signed URLs are useful if you want your user/customer to be able to download a specific object from your bucket, but you don't require them to have Google Cloud security credentials, permissions, nor bucket public access.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2 of the first action of this documentation.

 1) Set up the action "GENERATE DOWNLOAD PRESIGNED EXPIRING URL" in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name containing the file.
     - PATH & FILE NAME : Path & File Name to process. 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.
     - EXPIRE AFTER: The number of seconds before the presigned URL expires. Max is 7 days. Defaults to 15 minutes.
     Output Fields :
       - URL : Returns the signed expiring URL.

3 : SAVE FILE TO GOOGLE CLOUD STORAGE
=======================================

ACTION DESCRIPTION
--------------------------------
 SAVE FILE TO GOOGLE CLOUD STORAGE stores a file in your GOOGLE CLOUD STORAGE Bucket, and returns the object key or URL if the operation is successful. The file must be less than 22 megabytes to be executable in backend workflow.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2) b) of the first action of this documentation.

 1) Set up the action "SAVE FILE TO GOOGLE CLOUD STORAGE" in the workflow.

   Inputs Fields :
     - FILE TO STORE (URL) : 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. The file must be less than 22 megabytes.
     - BUCKET NAME : Bucket Name to which the file will be saved.
     - PATH & 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.
     - GENERATE URLS : Generate Google Cloud Storage public URLs format in the response. Format is https://storage.googleapis.com/bucket-name/file.ext.
   Output Fields :
     - FILE : Returns the object key or URL.

4 : GET FILE BASE64 DATAURI FROM GOOGLE CLOUD STORAGE
========================================

ACTION DESCRIPTION
--------------------------------
 GET FILE BASE64 DATAURI FROM GOOGLE CLOUD STORAGE retrieves the file's base64 DataURI from your GOOGLE CLOUD STORAGE bucket. Use this action to load the datastream in an element supporting this format, such as an audio player, or store the datastream into a database. The file must be less than 4.5 megabytes to be executable in backend workflow.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2) b) of the first action of this documentation.

 1) Set up the action "GET FILE BASE64 DATAURI FROM GOOGLE CLOUD STORAGEE" in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name from which the file will be retrieved.
     - PATH & FILE NAME : Path & File Name to retrieve. The file must be less than 4.5 megabytes. 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.
   Output Fields :
     - DATAURI : Returns the file's data.

5 : DELETE FILE FROM GOOGLE CLOUD STORAGE
===========================================

ACTION DESCRIPTION
--------------------------------
 DELETE FILE FROM GOOGLE CLOUD STORAGE deletes a file from your GOOGLE CLOUD STORAGE bucket, returning the object key or URL if the operation is successful.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2) b) of the first action of this documentation.

 1) Set up the action "DELETE FILE FROM GOOGLE CLOUD STORAGE" in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name from which the file will be deleted.
     - PATH & FILE NAME : Path & File Name to delete. 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.
     - GENERATE URLS : Generate Google Cloud Storage public URLs format in the response. Format is https://storage.googleapis.com/bucket-name/file.ext.
     Output Fields :
     - FILE : Returns the object key or URL.

6 : GET FILE METADATA FROM GOOGLE CLOUD STORAGE
===========================================

ACTION DESCRIPTION
--------------------------------
 GET FILE METADATA FROM GOOGLE CLOUD STORAGE retrieves the metadata of the specified object.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2) b) of the first action of this documentation.

 1) Set up the action " GET FILE METADATA FROM GOOGLE CLOUD STORAGE" in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name containing the file.
     - PATH & FILE NAME : Path & File Name to process. 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.
     Output Fields :
       - FILE SIZE : Returns the size of the file's content in bytes
       - CREATION AT : Returns the date and time at which the file was created (RFC 3339 date-time).
     - TAGS : Returns a list of tags. Each tag is formatted as key=value.


7 : LIST FILES FROM GOOGLE CLOUD STORAGE
=============================

ACTION DESCRIPTION
--------------------------------
 LIST FILES FROM GOOGLE CLOUD STORAGE returns the list of files' key or URLs from a GOOGLE CLOUD STORAGE bucket.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 2) b) of the first action of this documentation.

 1) Set up the "LIST FILES FROM GOOGLE CLOUD STORAGE" action in the workflow.

   Inputs Fields :
     - BUCKET NAME : Bucket Name from which the list will be retrieved.
     - PREFIX FILTER : Limit the response to keys that begin with the specified string, starting from the bucket name root.
     - GENERATE URLS : Generate Google Cloud Storage public URLs format in the response. Format is https://storage.googleapis.com/bucket-name/file.ext.
   Output Fields :
     - LIST : Returns the list of files’ key or URL.

8 : COPY FILE BETWEEN GOOGLE CLOUD STORAGE BUCKETS
=====================================================

ACTION DESCRIPTION
--------------------------------
 COPY FILE BETWEEN GOOGLE CLOUD STORAGE BUCKETS copy a file from a source bucket and path to a target bucket and path, then returns the object key or URL of the target file.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 3 of the first action of this documentation.

 1) Set up the “COPY FILE BETWEEN GOOGLE CLOUD STORAGE BUCKETS action in the workflow.

   Inputs Fields :
     - SOURCE BUCKET : Bucket Name of the source file.
     - SOURCE PATH & FILE NAME : Source Path & File Name that will be copied. 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.
     - TARGET BUCKET : Bucket Name to which the file will be retrieved from.
     - TARGET PATH & FILE NAME : Target Path & File Name. 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.
     - GENERATE URLS : Generate Google Cloud Storage public URLs format in the response. Format is https://storage.googleapis.com/bucket-name/file.ext.
   Output Fields :
     - FILE : Returns the object key or URL.

9 : SET FILE PUBLIC ACCESS IN GOOGLE CLOUD STORAGE
==================================================

ACTION DESCRIPTION
--------------------------------
SET FILE PUBLIC ACCESS IN GOOGLE CLOUD STORAGE enables or disable public access via the Google Cloud Storage public URL.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 3 of the first action of this documentation.

 1) Set up the “SET FILE PUBLIC ACCESS IN GOOGLE CLOUD STORAGE" action in the workflow.

   Inputs Fields :
     - BUCKET : Bucket Name of the file.
     - PATH & FILE NAME : Path & File Name. 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.
     - PUBLIC ACCESS : Enable public access via the Google Cloud Storage public URL.
     - GENERATE URLS : Generate Google Cloud Storage public URLs format in the response. Format is https://storage.googleapis.com/bucket-name/file.ext.
   Output Fields :
     - FILE : Returns the object key or URL.

10 : CREATE BUCKET IN GOOGLE CLOUD STORAGE
===========================================

ACTION DESCRIPTION
--------------------------------
CREATE BUCKET IN GOOGLE CLOUD STORAGE creates a bucket with a standard default object class at a specified location.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 3 of the first action of this documentation.

 1) Set up the “CREATE BUCKET IN GOOGLE CLOUD STORAGE" action in the workflow.

   Inputs Fields :
     - BUCKET NAME: Bucket Name of the file.
     - LOCATION : Location where you want to store your bucket's object data. For example, US-EAST1. See https://cloud.google.com/storage/docs/locations
   Output Fields :
     - BUCKET NAME : Name of the created bucket.  

11 : EDIT DEFAULT BUCKET STORAGE CLASS IN GOOGLE CLOUD STORAGE
===============================================================

ACTION DESCRIPTION
--------------------------------
EDIT DEFAULT BUCKET STORAGE CLASS IN GOOGLE CLOUD STORAGE modifies the default object class of an existing bucket.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 3 of the first action of this documentation.

 1) Set up the “EDIT DEFAULT BUCKET STORAGE CLASS IN GOOGLE CLOUD STORAGE" action in the workflow.

   Inputs Fields :
     - BUCKET NAME: Bucket Name of the file.
     - STORAGE CLASS : Storage class of your bucket. Valid vales are STANDARD | NEARLINE | COLDLINE | ARCHIVE. See https://cloud.google.com/storage/docs/storage-classes#classes
   Output Fields :
     - BUCKET NAME : Name of the modified bucket when successful.  

12 : DELETE BUCKET FROM GOOGLE CLOUD STORAGE
===============================================================

ACTION DESCRIPTION
--------------------------------
DELETE BUCKET FROM GOOGLE CLOUD STORAGE deletes the specified bucket.

STEP-BY-STEP SETUP
--------------------------------
 0) If not already done, perform the steps 0 to 3 of the first action of this documentation.

 1) Set up the “DELETE BUCKET FROM GOOGLE CLOUD STORAGE action in the workflow.

   Inputs Fields :
     - BUCKET NAME: Bucket Name of the file.
   Output Fields :
     - BUCKET NAME : Name of the modified bucket when successful.            

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

ADDITIONAL INFORMATION
======================
N/A

TROUBLESHOOTING
================
Any plugin related error will be posted either to:
    - Your browser Javascript console: Instructions here https://webmasters.stackexchange.com/questions/8525/how-do-i-open-the-javascript-console-in-different-browsers
    - 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
===========================

SAVE FILE TO GOOGLE CLOUD STORAGE ACTION
-----------------------------------------------
 This implementation posts file data to GOOGLE CLOUD STORAGE ACTION.
 The file must be less than 22 megabytes to be executable in backend workflow, as the maximum allowable file size is capped by Bubble.io's Workflow Action maximum execution time to perform this transfer operation.

GET FILE BASE64-DATAURI FROM GOOGLE CLOUD STORAGE ACTION
---------------------------------------------------------------------------
 This implementation gets file data from GOOGLE CLOUD STORAGE ACTION.
 The file must be less than 4.5 megabytes to be executable in backend workflow, as the maximum allowable file size is capped by Bubble.io's Workflow Action maximum execution time to perform this transfer operation.

QUESTIONS ?
===========
Contact us at bubble@wiseable.io for any additional feature you would require or support question.