Editing and converting documents

ADM opens files in the browser rather than making users download, edit and re-upload. What you get depends on the file type, and two of the features depend on external services you have to configure.

What renders where

File type	Opens as
PDF	Inline PDF viewer
Images (PNG, JPEG, GIF, …)	Image viewer, with editing — see Editing images
HTML, Markdown	Rendered inline
.msg, .eml	Email viewer: headers, body and the attachment list
Office documents (Word, Excel, PowerPoint)	The AOE editor — see Editing Office documents
Anything else	Download

Files larger than DOWNLOAD_FILE_THRESHOLD (50 MB by default) offer a download instead of a preview, whatever their type. See Settings reference.

Editing Office documents

APEX Office Edit (AOE) opens a Word, Excel or PowerPoint document in the browser and saves the result back into ADM as a new version of the same document. The document keeps its id, so its shares, tags, comments and audit history carry straight over.

Setting it up

AOE is a hosted service that your database talks to, and that talks back to your APEX instance.

Two directions of traffic

AOE is not a one-way API call. The editor needs to read back from your instance, through an ORDS REST endpoint at {your apex host}/{workspace}/aoe/. ADM computes that URL for you with adm_utils.get_aoe_rest_url. Two consequences: the schema must be REST-enabled, and the AOE plug-in’s REST module has to be published in the workspace. If editing loads but saving fails, check both.

1. Set the endpoint and key:

   Setting	Value
   AOE_API_URL	https://api.apexofficeedit.com/, or your own AOE server
   AOE_API_KEY	your AOE key

2. Check outbound access from the database to that URL — an ACL entry and, in most networks, a proxy. Without it every AOE call fails before it leaves the database.

3. Use Administration → Test AOE with Oracle Cloud to verify the round trip before telling users about it.

4. If a save fails, Administration → AOE RESTful service logs shows what the service sent and what came back.

Note

The adm_aoe package holds the callback procedures the AOE plug-in calls — create, save-as, rename, update, get-file-info. It is the plug-in’s interface, not an API to call yourself. To create a version from your own code, use adm_document_api.add_document_version.

Converting to PDF

APEX Office Print (AOP) converts a document to PDF. The PDF is stored as a new document in the same folder, not as a version of the original — you keep both.

From the row menu of a document, choose Convert to PDF. From PL/SQL:

begin
  adm_context_api.system_user_login('JDOE');

  adm_aop_api.convert_to_pdf(
    p_document_id   => l_document_id
  , p_document_name => null    -- default: the source name with a .pdf extension
  , p_overwrite     => false   -- false: a name clash gets a timestamp appended
                               -- true:  a name clash becomes a new version of the existing PDF
  );

  commit;
end;
/

Configure it with two settings:

Setting	Value
AOP_API_URL	https://api.apexofficeprint.com/, or your own on-premise AOP server
AOP_API_KEY	your AOP key. Admin-only, so reading it needs an admin context

Converting in bulk

convert_to_pdf is an ordinary procedure, so converting a folder full of documents is a loop — but each call is a round trip to an external service. Do it in a scheduled job rather than in a page process, and be aware of your AOP plan’s rate limits.

Editing images

Images open in an editor that can crop, rotate and adjust in place. Saving writes a new version of the document, exactly like an Office edit.

Comments

Any document can carry comments, optionally tied to the version they were written against. See Working with documents.

Also refer to

• Working with documents
• Settings reference
• Installation — plug-in licensing, which AOE and AOP both need
• adm_aop_api