The upload and update workflow
The upload and update workflow can be customized using standard attribute Initialization JavaScript Code. Learn more in upload workflow customization guidelines.
The update and upload workflow is used by the plug-in to monitor the process of uploading images and notify the end-user about the current progress and possible image issues. The workflow is used when the plug-in is configured to upload images on page submission using page item attribute Upload Image(s) on Request(s) or when the dynamic action Upload on Demand is triggered. The workflow includes steps described in the table below.
| Workflow Step | Descritption |
|---|---|
| Collect images | The plug-in scans a document for images and collects image meta-data |
| Downlaod images | The plug-in downloads not uplaoded images as base64 encoded images |
| Uplaod images | The plug-in uplaods base64 images using plug-in RESTful service |
| Update the plug-in session state | The plug-in updates it's session state by updating a document content and updating images meta-data |
| Finalize the upload | The plug-in last verification step before submitting a page (or exectuing dynamic action JavaScript callbacks) |
Downloading and uploading images may raise issues which might be needed to be handled by the end-user before saving a document in the database. For example, downloading image from WEB may raise CORS policy violation, or uploading an image might be canceled due to the image upload validations. On the other hand, the application session can expire while end-user works with rich text document, and step updating the plug-in session state will raise PL/SQL error.
In order to have full control over the uploading and updating process, the plug-in exposes workflow steps configuration using JavaScript code to perform one of the following actions:
- Continue - ignore issues (continue the workflow to the next step)
- Cancel - cancel the workflow and don't submit a page (or execute JavasScript cancel callback)
- Confirm - ask the end-user whether ignore issues (continue) or cancel the workflow
These actions can be executed by the workflow when:
- download step raises at least one image issue
- upload step raises at least one image issue
- finalize the upload step recognizes at least one download or upload issue
- Re-run workflow
- Test it on-line
- Example animation
When the workflow is canceled, the end-user can verify download and upload issues using the plug-in workflow summary (computed when downloading and uploading images). Once issues are fixed, the end-user can re-run the upload and update workflow.
The Rich Text Editor Pro sample application is available online and it allows testing the upload and update workflow on page submission and testing dynamic action Upload on Demand callbacks.
The animation presents the workflow default configuration notyfing the end-user about download and upload issues. The end-user fixes download CORS policy error by manualy downloading image (bypassing an error) and replacing the image with downloaded file fixing the download issue (downloaded image is added as base64 image and doesn't require downloading).
The upload error is raised, because the example page doesn't allow uploading PNG images. In this case, the end-user can do the following:
- ignore uplaod issue and leave the PNG image as it is without uploading it ,
- remove it from document to satisfy the upload and update workflow configuration, or
- download image, convert it to allowed MIME-TYPE, and use it as replacement
Collect images
The plug-in scans a document for images and collects images meta-data. Not uploaded images (base64 images and images referenced by URL) are queued to download in download images step.
Download images
The plug-in iterates over images collected in collect images step and download them using the plug-in AJAX request. Downloaded images are embeded in a document as base64 images ready to be uploaded on upload images step.
It might happen that image hosted on external server can't be downloaded (ie. due to CORS policy), and if any image fails to download, the update & upload workflow can be configured to:
- Ignore download issues and continue
- Cancel the workflow automatically at the download images step
- Ask end-user what whether continue or cancel
- No issues
- Ignore issues
- Cancel workflow
- Ask end-user
The plug-in downloaded all images, or none image required downloading. The plug-in proceeds to the next step Upload image.
When the plug-in is configured to automatically ignore download issues, the plug-in:
- replaces downloaded images in a document with downloaded image base64 representation
- proceeds to the next workflow step: upload images
When the workflow is canceled automatically, the plug-in displays message "Uploading canceled automatically.". Once the workflow is canceled, the end-user can preview the upload summary showing what images failed downloading. When the step is canceled by the plug-in or the end-user, then:
- images successfuly downloaded are not replaced with base64 encoded representation
- page submission is canceled (when the workflow is triggered by page submit request)
- JavaScript callback cancel is triggered (when the workflow is triggered by supporting dynamic action)
- a document HTML is not updated in the plug-in session state (see draft CLOB)
- images meta data is not updated in the plug-in session state (see Image meta data)
- the workflow can be re-run after fixing download issues
When the plug-in is configured to confront download errors with end-user, the plug-in displays browser confirm box allowing end-user to cancel the workflow or ignore download errors, and continue to next workflow step (upload images).
When canceled by the end-user, then the message "Uploading canceled by the end-user." is displayed, and the end-end user can verify download issues using plug-in summarry.
Upload images
The plug-in iterates over collected base64 images (including downloaded images), performs image validation and initializes the upload using AJAX POST request to RESTful upload handler using upload query parameters. An image upload validation checks if an image mime-type is allowed and if an image size doesn't exceeds maximum value. When an image is successfuly uploaded it's src property is replaced with URL returned from RESTful upload handler.
When any image validation fails, or uploading image using RESTful service raise an error, the update and upload workflow can be configured to:
- Ignore upload issues and continue
- Cancel the workflow at upload images step
- Ask end-user whether continue or cancel
- No issues
- Ignore issues
- Cancel workflow
- Ask end-user
The plug-in uploaded all images or there none image required uploading. The plug-in proceeds to the next step Update the plug-in session state.
When the plug-in is configured to automatically ignore upload issues, the plug-in:
- updates uploaded images
srcattribute in a rich text document, with URL returned from RESTful upload handler - proceeds to the next workflow step: upload images: Update the plug-in session state
When the workflow is canceled automatically, the plug-in displayes message "Updating canceled automatically due to upload errors". Once the workflow is canceled, the end-user can preview the workflow summary showing what images failed uploading.
When the step is canceled by the plug-in or the end-user, then:
- images succesfully uploaded are replaced in document HTML (image
srcattribute is replaced with URL returned from REST upload handler) - page submission is canceled (when the workflow is triggered by page submit request)
- JavaScript callback cancel is triggered (when the workflow is triggered by supporting dynamic action)
- a document HTML is not updated in the plug-in session state (see draft CLOB)
- images meta data is not updated in the plug-in session state (see Image meta data)
- the workflow can be re-run after fixing upload issues
When the plug-in is configured to confront upload errors with end-user, the plug-in displays a browser confirm popup allowing end-user to cancel the workflow or ignore upload errors and continue to the next workflow step (Update the plug-in session state).
When canceled by the end-user, then the message "Uploading canceled by the end-user." is displayed, and the end-end user can verify download issues using plug-in summarry.
Update the plug-in session state
At this point, images are downloaded and uploaded (issues might be ignored due to the plug-in configuration), the plug-in proceeds to update it's session state in the plug-in collection. This workflow step is divided into two sub-steps updating document draft CLOB, and updating image meta-data in the plug-in session state. If no issues are raised, and an application session doesn't expire, the plug-in proceeds to the next step Finalize the update and upload.
- When session expires
- Error after submitting a page
- Error after uploading images on demand
An application session may expire due to inactivity of the end-user, or when a new session for an application is created. Uploading images is not affected by the session expiration time because it's handled by RESTful service. Nevertheless, depending on how workflow was triggered (page submission or the plug-in dynamic action), the plug-in handles error differently.
If the workflow was executed on a page submission, and an error is raised:
- the page submission is canceled,
- the plug-in displays message "Updating terminated due to AJAX error."
- a page item validation message "Ajax request failed: Your session has ended." is shown.
If the workflow was executed by dynamic action Upload on Demand, and an error is raised:
- the plug-in executes JavaScript fail callback defined in dynamic action
- the plug-in displays message "Updating terminated due to AJAX error."
- a page item validation message "Ajax request failed: Your session has ended." is shown.
Finalize
This step purpose is to let the end-user react to download or upload issues ignored in previous steps. Up until now, the plug-in did the following:
- Downloaded images (or ignored download issues)
- Uploaded images (or ignored upload issues)
- Updated document in the plug-in session state
- Updated images meta-data in the plug-in session state
This is the last moment, when the upload and update workflow can be canceled by the plug-in or on the end-user decision. This step can be configured to do the following:
- Ignore all issues and submit page (or execute JavaScript done callback)
- Cancel the workflow without reinitializing page submission (or execute JavaScript cancel callback)
- Ask end-user whether ignore issues and continue submitting a page or cancel the workflow
- No issues
- Ignore issues
- Cancel workflow
- Ask end-user
If workflow was triggered by a page submission, the plug-in re-submits a page. If workflow was triggered by dynamic action, the JavaScript done callback is executed.
When downlaod or uplaod errors are ignored automatically, a page is re-submitted, or the JavaScript done callback is executed. In this case, not downloaded and not uplaoded images remain in a document as is.
When the workflow is canceled automatically, the plug-in displays message "Finishing canceled automatically due to download or upload error(s).". Once the workflow is canceled, the end-user can preview the workflow summary showing what images failed to download or upload. After fixing download and uplaod issues, the end-user can re-run the workflow process without refreshing a page.
The plug-in displays browser confirm popup allowing the end-user to cancel the workflow, or ignore issues from previous steps proceeding to submit page (or execute JavaScript done callback).
When the end-user cancels the upload and update workflow:
- the plug-in displays message "Uploading canceled by the end-user."
- a page submission is not reinitialized, or the JavaScript cancel callback is executed
The end-user can verify download and upload issues using workflow summary, and restart the process again.