Skip to content
APEX Document Management

Object storage

ADM can keep file content in an OCI Object Storage bucket instead of in database BLOBs. This page covers the DBMS_CLOUD prerequisite, the bucket, the credentials, and how to migrate content that is already in the database.

For what object storage means for the product — the two locations, per-folder storage policies, delayed deletion, checksum verification — read Storage and versioning first. Every setting mentioned below is described in the settings reference.

Install DBMS_CLOUD packages

Section titled “Install DBMS_CLOUD packages”

On an autonomous Oracle database DBMS_CLOUD is normally already installed.

On a non-autonomous database you may have to install the DBMS_CLOUD package yourself. Follow these guides from Oracle:

Grant privileges

Section titled “Grant privileges”

Grant execute privileges on the DBMS_CLOUD package to the ADM schema user. Replace {adm_schema} with your ADM schema name.

grant execute on DBMS_CLOUD to {adm_schema};

Additionally compile adm_oci package with the following command:

ALTER PACKAGE adm_oci COMPILE PLSQL_CCFLAGS = 'DBMS_CLOUD:TRUE';

Set up object storage in OCI

Section titled “Set up object storage in OCI”

Create the bucket

Section titled “Create the bucket”

Log-in to your Oracle Cloud Infrastructure (OCI) account and navigate to the Buckets section under Storage.

Click Create Bucket, provide a name for your bucket, and use these settings:

  • Default Storage Tier: Standard
  • Enable Auto-Tiering: optional; it saves cost on infrequently accessed documents
  • Enable Object Versioning: No (ADM already handles versioning)
  • Emit Object Storage Events: No
  • Uncommitted Multipart Uploads Cleanup: Yes
  • Encryption: your choice
  • Resource logging: keep enabled
  • Tags: optional

Open the bucket info page and copy the namespace attribute value. On this page you can also monitor the bucket usage and size.

Also open the user menu in the top right corner and note the email address shown. Then click the region dropdown in the header, click Manage regions, and note the Region identifier of the current region.

Generate an auth token

Section titled “Generate an auth token”

Click on your user icon in the top right corner and select User Settings. Then, navigate to the Tokens and keys section and click on Generate Token in the Auth Tokens section. Give a description and copy the generated token. The token is not shown again after you close the dialog.

Store credentials in the database

Section titled “Store credentials in the database”

Enter the auth token into the database. Choose any credential name. The username is the email address of your OCI account. Click on the profile icon and on the email entry. On the page there is a username field.

begin
  dbms_cloud.create_credential (
    credential_name => '{credential_name}',
    username       => '{oci_username}',
    password     => '{oci_auth_token}'
  );
end;
/

Init object storage

Section titled “Init object storage”

Run this code to set up object storage. The procedure raises if something goes wrong.

begin
  adm_context_api.system_login(apex_debug.c_log_level_app_trace);


  adm_settings_api.configure_object_storage(
    p_bucket        => '{bucket_name}',
    p_region        => '{region_identifier}',
    p_namespace     => '{namespace}',
    p_credential_id => '{credential_name}',
    p_verify_checksums => 'Y'
  );
end;
/

Create storage policies

Section titled “Create storage policies”

Storage policies decide which files are stored in object storage.

declare
  l_policy_id number;
begin
  l_policy_id := adm_storage_api.create_storage_policy(
    p_folder_path_pattern => '/',
    p_storage_location    => 'OBJECT_STORAGE',
    p_description         => 'All files should be in object storage'
  );


  -- or
  l_policy_id := adm_storage_api.create_storage_policy(
    p_folder_path_pattern => '/groups',
    p_storage_location    => 'OBJECT_STORAGE',
    p_description         => 'All group files should be in object storage'
  );


  -- or
  l_policy_id := adm_storage_api.create_storage_policy(
    p_folder_path_pattern => '/users/philipp/test',
    p_storage_location    => 'OBJECT_STORAGE',
    p_description         => 'Philipps test files should be in object storage'
  );


  commit;
end;

Run the migration

Section titled “Run the migration”

Run this block to mark all impacted files for migration:

begin
  adm_storage_api.apply_adm_object_storage_policies (
    p_defer => true
  );


  commit;
end;
/

With p_defer, the procedure marks the files for upload instead of uploading them immediately.

The nightly job picks up the marked files and uploads them. To run the first batch by hand:

declare
  l_error_occurred boolean;
begin
  adm_job_automations_api.process_storage_migrations(l_error_occurred);
  sys.dbms_output.put_line('Error occurred: ' || case when l_error_occurred then 'Y' else 'N' end);


  commit;
end;

Query the status of the migration:

select d.document_name
     , f.folder_path
     , dv.version_number
     , dv.migrate_to_storage
     , dv.migration_status
     , dv.storage_location
     , dv.object_storage_key
     , dv.migration_date
     , dv.migration_error
     , dv.migration_retry_count
  from adm_document_versions dv
  join adm_documents d on dv.document_id = d.document_id
  join adm_folders f on d.folder_id = f.folder_id
 where dv.migrate_to_storage is not null;

List bucket objects from the database

Section titled “List bucket objects from the database”
select *
  from dbms_cloud.list_objects(
        credential_name => adm_settings_api.get_object_storage_credential_id,
        location_uri    => adm_oci.get_bucket_url
       );

Enable full-text search

Section titled “Enable full-text search”

Files stored in BLOB storage are indexed for full-text search by an Oracle Text index. For files in object storage, turn on this setting:

begin
  update adm_settings
     set sett_value = 'Y'
   where sett_key = adm_settings_api.c_sett_obj_storage_index;


  commit;
end;

Files are indexed the next time a user opens them, when the content is downloaded from object storage into the database.

Also refer to

Section titled “Also refer to”