Integrating APEX with OCI Document Understanding

My customer engagements have allowed me to explore the integration with Oracle Cloud Infrastructure (OCI) as an APEX developer.

Once these projects results have been demonstrated the work, at least from my efforts, just sit in my instance waiting for a re-use opportunity. In an effort to increase those chances, I will be sharing some of the templates with a short guideline on how-to use or expand the definitions that I share.

Before Getting Started

In my first post, I harp on about reading the documentation and navigating its pages. This will be a recurring theme and it should be no surprise that I will start by sharing the links to the documentation for OCI Document Understanding and its API.

The service is described as an AI service that lets developers extract text, tables, and other key data from document files. In a nutshell this is the premise of the use case with automation for document uploads and display & ingestion of the results into the Oracle database.

Use Case

Develop a solution that will extract document details; authors, topic, keywords, references, affiliates, etc., allowing search and match of articles for researchers. The documents were primarily research articles in PDF format.

Oracle APEX will provide a seamless user experience to manage document storage & processing, search and review article topics of interest.

OCI Document Understanding AnalyzeDocument API was invoked to perform the different types of analysis with a custom model.

APEX REST Data Source

A REST data source was configured for each variation of the API's POST method.

The document understanding uses the POST method in APIs to submit document analysis jobs. The two APIs used were the AnalyzeDocument and the CreateProcessorJob during the testing and the key difference being that the AnalyzeDocument supports both Inline and Object Storage input and output document locations. The CreateProcessorJob only supports analysis of documents and storing of the analysis results in an Object storage bucket.

A step-by-step guide on creating APEX REST Data Source has not provided but I would suggest to either use the advanced or manual options while creating the definition.

The request body template samples are provided as-is and may need to be adapted. In addition each request sets the content-type header to "application/json" and stores the API response in a RESPONSE OUT parameter, not defined in the template.

Request Body Template Samples

All of the request operations use the HTTP POST method with parameters generated from the request body template.

In my previous post, explained how I use and navigate the OCI REST API documentation to discover the structured need to submit requests and understanding responses. I have done the same for these integrations, including the minimum set of parameters required for the use case.

If additional parameters are required, review the API documentation and ensure to expand the parameter's type definition and allowed values.

A perfect example of this can be seen in the comparison of the AnalyzeDocument with Inline Document and Inline Results vs. using a document located on Object Storage and again storing the results on Object Storage.

Although the Data Type references used by the AnalyzeDocument and CreateProcessorJob are similar, they are different, so ensure that the correct documentation is referenced.

AnalyzeDocument: Inline Document with Inline Results

{

   "features": [{
      "featureType": "#FEATURE#",
      "maxResults": 5
   }],
   "document": {
      "source": "INLINE",
      "data": "#DOC_DATA#"
   }
}

AnalyzeDocument: Object Storage Document with Inline Results

{
   "document": {
      "source": "OBJECT_STORAGE",
      "bucketName": "#IN_BUCKET_NAME#",
      "namespaceName": "#NAMESPACE#",
      "objectName": "#OBJECT_NAME#"
   },
   "features": [{
      "featureType": "#FEATURE#",
      "modelId": "#MODEL_ID#"
   }],
   "compartmentId": "#COMPARTMENT_ID#"
}

AnalyzeDocument: Object Storage Document with Results written to Object Storage

{
   "document": {
      "source": "OBJECT_STORAGE",
      "bucketName": "#IN_BUCKET_NAME#",
      "namespaceName": "#NAMESPACE#",
      "objectName": "#OBJECT_NAME#"
   },"outputLocation": {
     "namespaceName": "#NAMESPACE#",
     "bucketName": "#OUT_BUCKET_NAME#",
     "prefix": "#FOLDER_PREFIX#"
   },
   "features": [{
      "featureType": "#FEATURE#",
      "maxResults": 5
   }],
   "compartmentId": "#COMPARTMENT_ID#"
}

CreateProcessorJob

{
     "processorConfig": {
     "processorType": "GENERAL",
     "features": [
     {
        "featureType": "#FEATURE_TYPE#",
        "maxResults": 5
     }
    ]
    },
     "inputLocation": {
     "sourceType": "OBJECT_STORAGE_LOCATIONS",
     "objectLocations": [{
        "bucketName": "#IN_BUCKET_NAME#",
        "namespaceName": "#NAMESPACE#",
        "objectName": "#OBJECT_NAME#"
     }]
   },"outputLocation": {
     "bucketName": "#OUT_BUCKET_NAME#",
     "namespaceName": "#NAMESPACE#",
     "prefix": "#FOLDER_PREFIX#"
   },
     "compartmentId": "#COMPARTMENT_ID#"
}

Conclusion

The request body templates will aide in the creation of the APEX REST Data Source as well as provide some understanding of how to translate the documentation into a usable request body.

Once created the REST Data Source is used in an APEX page, typically using the invoke API process type. All of the defined parameters are exposed to the consumer and mapped to page items with response JSON parsed as required or stored as a document in the database.

APEX also offers a PL/SQL package and functions to make REST requests but the templates would not used then.

Happy reuse in your efforts