Records management

Records management is about being able to prove two opposite things: that something was kept for as long as it had to be, and that it was destroyed when it had to be. ADM has features for both, and both are enforced by the product rather than by policy: a document under a legal hold cannot be deleted by anybody, administrators included.

Feature	Guarantees
Retention policies	A document is not deleted before its date, and is deleted on it.
Legal hold	A document cannot be deleted at all until the hold is lifted.
Audit trail	Every action on every document, with who and when.
Access control	Only the right people could reach it in the first place.
Versioning	The document’s history, not just its current state.

Retention policies

A retention policy puts a date on a document. Until that date it cannot be deleted; on it, the daily job deletes it automatically.

begin
  adm_context_api.system_user_login('JDOE');

  adm_document_api.add_file_retention(
    p_document_id           => l_document_id
  , p_retention_delete_date => add_months(systimestamp, 120)   -- ten years
  , p_retention_category    => 'TAX'                           -- optional, free text
  );

  commit;
end;
/

The optional retention category classifies why the document is being retained. It is free text on the document and it is queryable, so “everything retained under TAX” is a where clause.

select document_name
     , retention_category
     , retention_delete_date
  from adm_documents
 where retention_delete_date is not null
   and deleted_flag = 'N'
 order by retention_delete_date;

Remove a policy with remove_file_retention — which is itself an audited action, so a removal is part of the record.

Retention deletion is permanent

delete_retention_files in the daily job permanently deletes documents whose date has passed. This is not a move to the trash and it is not recoverable from within ADM. Before applying retention at scale, be certain the date is the one your policy actually requires — and that your database backup retention is long enough to be the safety net if it is not.

Setting retention requires owner rights on the document (administrators have them everywhere). It cannot be applied to a trashed document, or to one already under a legal hold.

Legal hold

A legal hold blocks deletion indefinitely — for litigation, an audit, an investigation. There is no date and no automatic expiry; somebody has to lift it.

begin
  adm_context_api.system_user_login('JDOE');

  adm_document_api.add_legal_hold(p_document_id => l_document_id);
  -- ... later, when the matter is closed
  adm_document_api.lift_legal_hold(p_document_id => l_document_id);

  commit;
end;
/

Both require owner rights, and both are audited. While a hold is on:

• Trashing the document fails with c_err_legal_hold_active.
• Permanent deletion fails.
• Retention cannot be applied on top of it.
• The document is otherwise normal — readable, editable, shareable.

-- everything currently on hold
select document_name
     , user_owner
     , group_owner
  from adm_documents
 where legal_hold_flag = 'Y';

Holds are per document, not per folder

There is no “hold this folder and everything in it”. Placing a hold across a set of documents is a loop over the documents you have identified, so the query that identifies them is what you keep:

begin
  adm_context_api.system_login;

  for r in (
    select doc.document_id
      from adm_documents doc
      join adm_folders f on f.folder_id = doc.folder_id
     where f.folder_path like '/groups/legal/case-4711%'
       and doc.deleted_flag = 'N'
       and doc.legal_hold_flag = 'N'
  ) loop
    adm_document_api.add_legal_hold(p_document_id => r.document_id);
  end loop;

  commit;
end;
/

A file added to that folder after you ran this is not on hold. Re-run it, or hook the upload event — see Hooks.

Audit trail

Retention and legal hold changes are audited as first-class actions — ADD_FILE_RETENTION, REMOVE_FILE_RETENTION, ADD_LEGAL_HOLD, LIFT_LEGAL_HOLD, FILE_RETENTION_DELETE — alongside every access, share and modification.

select action_date
     , action_type
     , user_id
     , document_name
     , action_details
  from adm_report_audit_log_v
 where action_type in ('ADD_LEGAL_HOLD', 'LIFT_LEGAL_HOLD',
                       'ADD_FILE_RETENTION', 'REMOVE_FILE_RETENTION',
                       'FILE_RETENTION_DELETE')
 order by action_date desc;

The audit log itself has no retention job — see Administration.

Three kinds of deletion

Three different things are all called “delete”:

	Effect	Reversible
Trash	Moved to the user’s trash folder	Yes, until the trash is emptied
Trash expiry	Permanently deleted after CLEAN_TRASH_DAYS	No
Retention deletion	Permanently deleted on the retention date	No

A permanent deletion also revokes every share, link share and embed token that pointed at the document, so nothing keeps resolving to a file that is gone. See Sharing.

Also refer to

• The security model
• Administration
• Jobs and maintenance
• Working with documents
• adm_document_api