Document Handling

Default table

By default, APEX Office Edit uses the default table AOE_DEFAULT_FILES to store documents. The default table uses the sequence AOE_DEFAULT_FILES_SEQ and triggers BI_AOE_DEFAULT_FILES. The default table, trigger, and sequence are created with the sample application and the plug-in DDL installation script.

Column Name	Data Type	Nullable	Primary Key	Description
ID	NUMBER			Column is used to uniquely identify a document
CONTENT	BLOB			Column is used to store a document contents
FILENAME	VARCHAR2(4000)			Column is used to store a document filename
MIME_TYPE	VARCHAR2(4000)			Column is used to store a document MIME-type
BLOB_OWNER	VARCHAR2(4000)			Column is used to store a document owner name
VERSION	NUMBER			Column is used to store a document current version
LAST_UPDATE_DATE	TIMESTAMP(6)			Column is used to store a document last modification time
CREATE_BY	VARCHAR2(255)			Audit field containing APEX username that created a file
CREATE_DATE	DATE			Audit field containing DATE value when a file was created
UPDATE_BY	VARCHAR2(255)			Audit field containing APEX username that modified a file
UPDATE_DATE	DATE			Audit field containing DATE value when a file was modified

Flows

Creating, loading, updating, saving as a new file and renaming documents are the result of communication between the AOE host server and the plug-in Oracle RESTful service module APEX Office Edit. If the RESTful handler request is interrupted by PL/SQL error, the plug-in shows a user-friendly error to the end user. Learn more about error handling in RESTful service \ Error Handling.

Assumptions:

• the flows described below are illustrative and should be considered as-is
• the flows don't include a flow path when the RESTful service handler raises an error
• flows below describe when the Source attribute is set to Default Table.

Loading documents

1. The end-user initializes loading a document by the sequence of events in an application using APEX Office Edit:

   1. a page item defined in the Item Containing Primary Key(s) Value(s) attribute is set with a document id

   2. the AOE is refreshed

   3. an AOE access token is generated containing information about the requested document and the configuration

   4. AOE submits the form and sends the information to the AOE server.

2. The AOE server handles the form submission and initializes a request to the RESTful service to fetch document meta-data

   1. The Get a document information RESTful service handler

      1. evaluates the configuration delivered through the access token (access token validity, end-user permissions, region read-only mode, and others)

      2. fetches document meta-data

      3. returns document meta-data and AOE editor features

3. The AOE server interprets the returned document meta-data and initializes a request to the RESTful service requesting document contents

   1. The RESTful service handler fetches the document contents as a BLOB

   2. The RESTful service handler executes a PL/SQL read callback (if defined)

   3. The REST service handler returns the document's contents

4. The AOE server renders the AOE editor with the loaded document as the contents of the iframe

5. The plug-in requests the RESTful service to get the document meta-data

6. Once the editor is fully loaded, the AOE Document loaded event is triggered

Creating a new document

1. The end-user initializes the creation of a new document by clicking on the desired document type tile in the new file panel

2. The widget requests the REST Service handler Create a new document to create a new document

3. The RESTful service handler:

   1. evaluates the configuration delivered through the access token (access token validity, end-user permissions, region read-only mode, and others)

   2. checks if the default filename is already taken. If yes, it assigns a new filename using the first available number in brackets. For example, the default filename is New file, but the filename is already taken, so a new document filename is New file (1)

   3. inserts blank document contents into AOE_DEFAULT_FILES

   4. inserts the first (empty) version of a document into AOE_DEFAULT_VERSIONS (if the plug-in flag g_default_versioning is set to true)

   5. (if defined) executes PL/SQL insert callback

   6. returns document meta-data (a new document ID, filename, a document owner, last modification time)

4. The plug-in evaluates the response and

   1. sets a new document ID as the value of a page item defined in the Item Containing Primary Key(s) Value(s) attribute
   2. refreshes the AOE region

5. Go to flow Loading documents

Saving document contents

1. The end-user clicks the Save button in the AOE editor toolbar (or click the menu position File \ Save or presses the key shortcut CTRL+S)

   1. The widget initializes a save action

   2. The AOE Before Update event is triggered

2. The AOE server reacts to the save action and starts a request to the RESTful service handler Update a document's contents

3. The RESTful service handler:

   1. evaluates the configuration delivered through the access token (access token validity)

   2. updates the document contents in the table AOE_DEFAULT_FILES

   3. inserts a new version of a document into AOE_DEFAULT_VERSIONS (if the flag g_default_versioning is set to true)

   4. (if defined) executes PL/SQL update callback

   5. returns document last modification time

4. The AOE server interprets the request result and notifies the widget about the successful action result

5. The AOE editor requests the RESTful service for a document meta-data

6. The AOE After Update event is triggered

Saving a document as a new document with a new filename

1. The end-user clicks the Save As button (menu position File \ Save As)

2. AOE shows a dialog with a form to save a document with a new filename

   1. The end-user provides a new filename

   2. the end-user clicks the dialog Save as button

   3. the AOE server is notified about the save as action

   4. The AOE Before Save As event is triggered

3. The AOE server reacts to the save as action and starts a request to the RESTful Service handler Save a document as a copy with a new filename

4. The REST service handler:

   1. evaluates the configuration delivered through the access token (access token validity)

   2. checks if the filename is already taken. If yes, it assigns a new filename using the first available number in brackets.

   3. inserts an updated document with a new filename into the table AOE_DEFAULT_FILES

   4. inserts the first version of a document into AOE_DEFAULT_VERSIONS (if the plug-in flag g_default_versioning is set to true)

   5. (if defined) executes PL/SQL save as callback

   6. generates and returns a new access token for a new document along with document meta-data

5. The AOE Server interprets the results and notifies the AOE Editor widget that a document was successfully saved as a new file with a new filename

6. The AOE Server notifies the AOE editor widget that a document was reloaded

7. The AOE editor requests the RESTful service for document meta-data

8. The AOE After Save As event is triggered

Renaming a document

1. The end-user updates the filename in the AOE editor toolbar and presses ENTER key.
2. The AOE Host Server starts the renaming action and requests the RESTful service handler Rename a document
3. The REST service handler:
   1. evaluates the configuration delivered through the access token (access token validity)
   2. renames a document in the table AOE_DEFAULT_FILES
   3. inserts the first version of a document into AOE_DEFAULT_VERSIONS (if the plug-in flag g_default_versioning is set to true)
   4. (if defined) executes PL/SQL rename callback
   5. generates and returns a new access token for a new document along with document meta-data
4. The AOE server interprets the results and notifies the AOE editor widget that a document was successfully renamed
5. The AOE editor requests the RESTful service for document meta-data
6. The AOE After Rename event is triggered