adm_ai_form_admin_api

Administration of form extraction: the typed server side of the form extraction manager (<adm-form-extraction-manager>).

Everything here is for administrators. Every method starts with adm_access_control_api.assert_admin, so any other caller gets adm_error.e_admin_required before anything is read. The write methods delegate to adm_ai_form_config_api and adm_ai_form_extract_api, which apply their own validation and their own checks again; this package adds the JSON shapes and the background runs.

No method commits, with one exception that is not a method of the caller’s transaction: start_processing and start_measurement create a scheduler job, which is an implicit commit, so they create it in an autonomous transaction and leave the transaction of the caller alone. The job itself (run_processing_job, run_measurement_job) is the top of its own transaction and commits after each document.

The read methods return JSON text, so that one call gives a screen everything it needs. Ids are strings, dates are ISO 8601 with a numeric offset, a nullable member is written as null, fields is a JSON object and line_items a JSON array:

select json_value(adm_ai_form_admin_api.get_profile(1), '$.counts.REVIEW')
  from dual;

Functions and Procedures

get_profile

Returns one profile: its row, its configuration with the defaults written out, the counts of its extraction results, its document types and forms, the size of its test set, the number of documents the automatic processing would take next, the state of its background runs and its last measurement. Each entry of forms has form_id, form_code, doc_type_id, doc_type, description, active, marker_count, has_line_pattern and model_input (text or file).

Signature:

function get_profile (
  p_profile_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile

Returns: clob - JSON with profile, config, counts, doc_types, forms, test_case_count, pending_count, jobs and last_measurement

---

get_config_options

The lists and limits that the editors of the manager need: providers and models of uc_ai, the OCR providers, the vision_model providers that can read a file (file_providers, for a form with model_input file), defaults (among them max_file_bytes and model_input), limits, the field types and the vocabulary of the check expressions. text_extraction_enabled is true when the setting AI_TEXT_EXTRACTION is Y: with N the OCR section of a profile reads no document.

Signature:

function get_config_options return clob;

Returns: clob - JSON with providers, models, ocr_providers, file_providers, defaults, limits, field_types, text_extraction_enabled and expression

---

validate_profile

Checks a profile configuration with the rules of create_profile, without writing. It lists the broken rule of every section of the configuration, not only the first one. A rule that needs a value of a broken section is not checked. Each error has the path of the field it belongs to: source_folder_path, source_file_annotation_key, text_model, vision_model, ocr_text_extraction, review_tag, min_text_chars, max_text_chars, rules, process_new_documents, max_documents_per_run or max_file_bytes. With p_profile_id the configuration is also checked against the forms of that profile, as update_profile does: a form with model_input file needs a vision_model that can read a file, and the error (path vision_model) names the form. A rule of the whole configuration (not JSON, not an object, an unknown key) has a null path.

Signature:

function validate_profile (
  p_config_json in clob,
  p_profile_name in varchar2 default null,
  p_profile_id in number default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_config_json	in	clob	The configuration, an object
p_profile_name	in	varchar2 default null	Name of the profile, for the messages; null takes the name of the

                stored profile, or else "configuration" |

| p_profile_id | in | number default null | The stored profile whose forms must still fit; null for a new one |

Returns: clob - JSON {valid, errors: [{path, message}]}; errors is empty when valid is true

---

create_profile

Creates a profile.

Signature:

function create_profile (
  p_profile_name in varchar2,
  p_description in varchar2 default null,
  p_config_json in clob
) return number;

Parameters:

Name	Direction	Type	Description
p_profile_name	in	varchar2	Unique name
p_description	in	varchar2 default null	Description
p_config_json	in	clob	The profile configuration

Returns: number - The id of the new profile

---

update_profile

Changes a profile. A null parameter keeps the stored value.

Signature:

procedure update_profile (
  p_profile_id in number,
  p_profile_name in varchar2 default null,
  p_description in varchar2 default null,
  p_config_json in clob default null
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_profile_name	in	varchar2 default null	New name
p_description	in	varchar2 default null	New description
p_config_json	in	clob default null	New configuration, which replaces the whole of the stored one

---

delete_profile

Deletes a profile with everything that belongs to it.

Signature:

procedure delete_profile (
  p_profile_id in number
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile

---

get_doc_type

Returns one document type: its row, its configuration, its scalar fields at the level of the document and of a line, and the codes of the forms that use it.

Signature:

function get_doc_type (
  p_doc_type_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_doc_type_id	in	number	The document type

Returns: clob - JSON with doc_type, config, fields and forms

---

validate_doc_type

Checks a document type configuration with the rules of create_doc_type and update_doc_type, without writing.

Signature:

function validate_doc_type (
  p_profile_id in number,
  p_doc_type_id in number default null,
  p_config_json in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile the document type belongs to
p_doc_type_id	in	number default null	The stored document type that is being changed, so that its forms are checked against the new schema; null for a new one
p_config_json	in	clob	The configuration, an object

Returns: clob - JSON {valid, errors: [{path, message}]}

---

validate_expression

Checks one check expression against a JSON schema.

Signature:

function validate_expression (
  p_json_schema in clob,
  p_expression in varchar2,
  p_level in varchar2 default 'DOCUMENT'
) return clob;

Parameters:

Name	Direction	Type	Description
p_json_schema	in	clob	The json_schema of a document type
p_expression	in	varchar2	The expression
p_level	in	varchar2 default 'DOCUMENT'	DOCUMENT or LINE

Returns: clob - JSON {valid, sql, message}

---

create_doc_type

Creates a document type.

Signature:

function create_doc_type (
  p_profile_id in number,
  p_doc_type in varchar2,
  p_config_json in clob
) return number;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_doc_type	in	varchar2	Code of the document type
p_config_json	in	clob	The configuration

Returns: number - The id of the new document type

---

update_doc_type

Changes a document type. A null parameter keeps the stored value.

Signature:

procedure update_doc_type (
  p_doc_type_id in number,
  p_doc_type in varchar2 default null,
  p_config_json in clob default null
);

Parameters:

Name	Direction	Type	Description
p_doc_type_id	in	number	The document type
p_doc_type	in	varchar2 default null	New code
p_config_json	in	clob default null	New configuration

---

delete_doc_type

Deletes a document type. Refused while forms use it.

Signature:

procedure delete_doc_type (
  p_doc_type_id in number
);

Parameters:

Name	Direction	Type	Description
p_doc_type_id	in	number	The document type

---

get_form

Returns one form: its row, its configuration and the fields of its document type.

Signature:

function get_form (
  p_form_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_form_id	in	number	The form

Returns: clob - JSON with form, config and fields

---

validate_form

Checks a form configuration against a document type with the rules of create_form and update_form, without writing.

Signature:

function validate_form (
  p_profile_id in number,
  p_doc_type_id in number,
  p_config_json in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile the form belongs to
p_doc_type_id	in	number	The document type that defines the fields
p_config_json	in	clob	The configuration, an object

Returns: clob - JSON {valid, errors: [{path, message}]}

---

create_form

Creates a form.

Signature:

function create_form (
  p_profile_id in number,
  p_form_code in varchar2,
  p_doc_type_id in number,
  p_description in varchar2,
  p_config_json in clob,
  p_active in boolean default true
) return number;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_form_code	in	varchar2	Code of the form
p_doc_type_id	in	number	The document type
p_description	in	varchar2	What the document is
p_config_json	in	clob	The configuration
p_active	in	boolean default true	False leaves the form out of the extraction

Returns: number - The id of the new form

---

update_form

Changes a form. A null parameter keeps the stored value.

Signature:

procedure update_form (
  p_form_id in number,
  p_form_code in varchar2 default null,
  p_doc_type_id in number default null,
  p_description in varchar2 default null,
  p_config_json in clob default null,
  p_active in boolean default null
);

Parameters:

Name	Direction	Type	Description
p_form_id	in	number	The form
p_form_code	in	varchar2 default null	New code
p_doc_type_id	in	number default null	New document type
p_description	in	varchar2 default null	New description
p_config_json	in	clob default null	New configuration
p_active	in	boolean default null	New state

---

delete_form

Deletes a form.

Signature:

procedure delete_form (
  p_form_id in number
);

Parameters:

Name	Direction	Type	Description
p_form_id	in	number	The form

---

list_documents

The documents in the scope of a profile, for the document pickers.

Signature:

function list_documents (
  p_profile_id in number,
  p_filter in varchar2 default 'ALL',
  p_search in varchar2 default null,
  p_offset in number default 0,
  p_limit in number default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_filter	in	varchar2 default 'ALL'	ALL (default), NO_RESULT (no extraction of the latest version), TO_PROCESS (the documents the automatic processing takes next) or NO_TEST_CASE
p_search	in	varchar2 default null	Only documents whose name contains this text (case-insensitive)
p_offset	in	number default 0	First row, from 0
p_limit	in	number default null	Rows in a page; null is 50, at most 200

Returns: clob - JSON {total, offset, limit, documents: [...]}

---

inspect_document

What the extraction would see in a document, without a model call and without OCR: the text, the text for the markers, and the saved active forms whose markers all match. With a form configuration that is not saved (p_config_json), also which of its markers match and which lines its line_pattern reads. The markers and the line pattern run in the code of the extraction itself.

Signature:

function inspect_document (
  p_profile_id in number,
  p_document_id in number,
  p_doc_type_id in number default null,
  p_config_json in clob default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document
p_doc_type_id	in	number default null	The document type whose schema types the line items; with p_config_json
p_config_json	in	clob default null	A form configuration, saved or not; null for the document only

Returns: clob - JSON with document, text_source, text_chars, min_text_chars, text, marker_text, truncated, matching_forms, markers, line_items and line_error

---

list_extractions

The extraction results of a profile, newest first.

Signature:

function list_extractions (
  p_profile_id in number,
  p_status in varchar2 default null,
  p_search in varchar2 default null,
  p_offset in number default 0,
  p_limit in number default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_status	in	varchar2 default null	OK, REVIEW, FAILED or APPROVED; null lists all
p_search	in	varchar2 default null	Only documents whose name contains this text (case-insensitive)
p_offset	in	number default 0	First row, from 0
p_limit	in	number default null	Rows in a page; null is 50, at most 200

Returns: clob - JSON {total, offset, limit, counts, extractions: [...]}

---

get_extraction

One document of a profile: its result, its test case and the forms the reviewer can pick.

Signature:

function get_extraction (
  p_profile_id in number,
  p_document_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document

Returns: clob - JSON with document, extraction, test_case and forms

---

extract_preview

Runs the extraction of a document with the model and returns the result, without writing a result or annotations. Waits for the model.

Signature:

function extract_preview (
  p_profile_id in number,
  p_document_id in number,
  p_model in varchar2 default null,
  p_vision_model in varchar2 default null,
  p_prompt in varchar2 default null,
  p_think in boolean default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document
p_model	in	varchar2 default null	Another model for text
p_vision_model	in	varchar2 default null	Another model for images
p_prompt	in	varchar2 default null	rules (default) or naive
p_think	in	boolean default null	True or false sets the reasoning of the model; null keeps the profile

Returns: clob - The result of adm_ai_form_extract_api.extract, with form_id as a string

---

extract_document

Extracts a document and writes and publishes the result. Waits for the model.

Signature:

function extract_document (
  p_profile_id in number,
  p_document_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document

Returns: clob - JSON {status} of the written result

---

approve

Approves the result of a document, see adm_ai_form_extract_api.approve.

Signature:

procedure approve (
  p_profile_id in number,
  p_document_id in number,
  p_form_code in varchar2 default null,
  p_corrections in clob default null,
  p_line_items in clob default null,
  p_add_to_test_set in boolean default true,
  p_version_id in number default null
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document
p_form_code	in	varchar2 default null	The form, when the extraction found none or the wrong one
p_corrections	in	clob default null	The changed fields, a JSON object
p_line_items	in	clob default null	The complete line items, a JSON array
p_add_to_test_set	in	boolean default true	True writes the approved values to the test set
p_version_id	in	number default null	The version whose result the person reviewed; null skips the check

---

list_test_cases

The test cases of a profile.

Signature:

function list_test_cases (
  p_profile_id in number,
  p_search in varchar2 default null,
  p_offset in number default 0,
  p_limit in number default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_search	in	varchar2 default null	Only documents whose name contains this text (case-insensitive)
p_offset	in	number default 0	First row, from 0
p_limit	in	number default null	Rows in a page; null is 50, at most 200

Returns: clob - JSON {total, offset, limit, test_cases: [...]}

---

set_test_case

Writes the test case of a document, see adm_ai_form_extract_api.set_expected. A null form code with null fields and line items marks a document that is no form.

Signature:

procedure set_test_case (
  p_profile_id in number,
  p_document_id in number,
  p_form_code in varchar2 default null,
  p_fields in clob default null,
  p_line_items in clob default null
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document
p_form_code	in	varchar2 default null	The form of the document
p_fields	in	clob default null	The correct fields, a JSON object
p_line_items	in	clob default null	The correct line items, a JSON array

---

delete_test_case

Deletes the test case of a document.

Signature:

procedure delete_test_case (
  p_profile_id in number,
  p_document_id in number
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_document_id	in	number	The document

---

job_state

The state of the background runs of a profile.

Signature:

function job_state (
  p_profile_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile

Returns: clob - JSON {processing, measuring, measuring_label}; the states are IDLE, SCHEDULED or RUNNING

---

start_processing

Starts a background run that extracts documents_to_process of the profile one by one, with a commit after each document. The run has the ADM context of the calling administrator. Returns at once.

Signature:

function start_processing (
  p_profile_id in number
) return varchar2;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile

Returns: varchar2 - The name of the scheduler job

---

start_measurement

Starts a background run that measures the test set of the profile, see adm_ai_form_extract_api.measure, with a commit after each document. The run has the ADM context of the calling administrator. Returns at once.

Signature:

function start_measurement (
  p_profile_id in number,
  p_label in varchar2,
  p_form_code in varchar2 default null,
  p_name_like in varchar2 default null,
  p_model in varchar2 default null,
  p_vision_model in varchar2 default null,
  p_prompt in varchar2 default null,
  p_think in boolean default null
) return varchar2;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_label	in	varchar2	Name of the run, unique in the profile
p_form_code	in	varchar2 default null	Only the test cases of this form
p_name_like	in	varchar2 default null	Only the documents whose name is like this
p_model	in	varchar2 default null	Another model for text
p_vision_model	in	varchar2 default null	Another model for images
p_prompt	in	varchar2 default null	rules (default) or naive
p_think	in	boolean default null	See extract_preview

Returns: varchar2 - The name of the scheduler job

---

list_measurements

The measurement runs of a profile, newest first. A run that is still being measured is listed with the rows it has so far, and without finished_at.

Signature:

function list_measurements (
  p_profile_id in number
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile

Returns: clob - JSON {runs: [{label, started_at, finished_at, documents, outcomes, models, prompt_tokens, completion_tokens, seconds}]}

---

get_measurement

One measurement run with its rows. Each row has method (TEXT, IMAGE, FILE or NONE; missing when the row measured nothing or was written before the column existed) besides text_source.

Signature:

function get_measurement (
  p_profile_id in number,
  p_label in varchar2
) return clob;

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_label	in	varchar2	Name of the run

Returns: clob - JSON {run, rows: [...]}

---

delete_measurement

Deletes one measurement run.

Signature:

procedure delete_measurement (
  p_profile_id in number,
  p_label in varchar2
);

Parameters:

Name	Direction	Type	Description
p_profile_id	in	number	The profile
p_label	in	varchar2	Name of the run

---