adm_signing_policy_api

The signing policy of a folder: what ADM does with the PDFs in it.

Mode	What ADM does
OFF	Nothing. ADM does not classify the PDFs of the folder, see adm_pdf_provenance_api.
WATCH	ADM records where every PDF comes from (adm_pdf_api.get_provenance). ADM signs nothing. This is the default.
SIGN	Like WATCH. ADM also signs the PDFs that it makes, with the key of the setting AUTO_SIGN_KEY_ID.

No mode refuses an upload. A user can download a PDF, change it, and upload it again. ADM does not sign such a file. It records that the file is not the file that ADM signed.

A policy has a folder path pattern, a mode and an active flag. The pattern works like the pattern of a storage policy (adm_storage_api.determine_storage_location):

• A pattern is a path prefix. It starts with a slash and is written in lower case, because the path of a folder is in lower case. /contracts/ covers the folder /contracts and every folder below it.
• ADM adds a slash to the end of the path of the folder, and then looks for the patterns that the path starts with. The longest pattern wins. So /contracts/emea/ beats /contracts/ for the folder /contracts/emea/2026.
• A pattern without a slash at the end also covers the folders with a longer name. /contracts covers /contracts-archive. End a pattern with a slash.
• An inactive policy is ignored.
• A folder that no policy covers has the mode of the setting AUTO_SIGN_DEFAULT_MODE, and WATCH if the setting is empty.

The path of a folder changes when an administrator moves or renames it, and so does its policy. ADM reads the path at every call. Nothing is cached.

Only an administrator can create, change, switch and delete a policy (adm_error.e_admin_required). A change to a policy writes an entry to the audit trail. A policy with the mode SIGN needs a signing key that can sign: the setting AUTO_SIGN_KEY_ID names an active key whose certificate is valid now. Otherwise the call raises adm_error.e_signing_key_unusable and changes nothing.

Example: sign everything that ADM makes in /contracts/, and record only in the rest

declare
  l_policy_id number;
begin
  adm_context_api.system_user_login('ADMIN');

  l_policy_id := adm_signing_policy_api.create_policy(
                   p_folder_path_pattern => '/contracts/'
                 , p_signing_mode        => adm_signing_policy_api.c_mode_sign
                 , p_description         => 'Contracts are signed by ADM'
                 );
end;

Types

t_policy

One signing policy, as list_policies and determine_policy return it.

Definition:

type t_policy is record (
  policy_id adm_signing_policies.policy_id%type,
  folder_path_pattern adm_signing_policies.folder_path_pattern%type,
  signing_mode adm_signing_policies.signing_mode%type,
  is_active adm_signing_policies.is_active%type,
  description adm_signing_policies.description%type
);

Fields:

Name	Type	Description
policy_id	adm_signing_policies.policy_id%type	-
folder_path_pattern	adm_signing_policies.folder_path_pattern%type	-
signing_mode	adm_signing_policies.signing_mode%type	-
is_active	adm_signing_policies.is_active%type	-
description	adm_signing_policies.description%type	-

---

Functions and Procedures

is_valid_mode

True for OFF, WATCH and SIGN, in upper case.

Signature:

function is_valid_mode (
  p_mode in varchar2
) return boolean;

Parameters:

Name	Direction	Type	Description
p_mode	in	varchar2	The mode

Returns: boolean - True or false, never null

---

determine_policy

Finds the policy of a folder path: the active policy with the longest pattern that the path starts with. The path is normalized like for a storage policy: null is the root, a slash is added at the start and at the end. Any user can call it. It reads one table.

Signature:

function determine_policy (
  p_folder_path in varchar2
) return t_policy;

Parameters:

Name	Direction	Type	Description
p_folder_path	in	varchar2	The path of a folder, for example /contracts/emea

Returns: t_policy - The policy. The policy_id is null when no active policy covers the path.

---

create_policy

Creates a policy. Only an administrator can call it. The new policy is active.

Signature:

function create_policy (
  p_folder_path_pattern in varchar2,
  p_signing_mode in varchar2,
  p_description in varchar2 default null
) return adm_signing_policies.policy_id%type;

Parameters:

Name	Direction	Type	Description
p_folder_path_pattern	in	varchar2	The pattern, see the description of the package. Starts with a slash, lower case, up to 1000 characters.
p_signing_mode	in	varchar2	OFF, WATCH or SIGN
p_description	in	varchar2 default null	What the policy is for. Optional.

Returns: adm_signing_policies.policy_id%type - The ID of the policy

---

update_policy

Changes the pattern, the mode and the description of a policy. Only an administrator can call it. The checks are the checks of create_policy.

Signature:

procedure update_policy (
  p_policy_id in adm_signing_policies.policy_id%type,
  p_folder_path_pattern in varchar2,
  p_signing_mode in varchar2,
  p_description in varchar2 default null
);

Parameters:

Name	Direction	Type	Description
p_policy_id	in	adm_signing_policies.policy_id%type	The policy
p_folder_path_pattern	in	varchar2	The pattern
p_signing_mode	in	varchar2	OFF, WATCH or SIGN
p_description	in	varchar2 default null	What the policy is for

---

activate_policy

Switches a policy on. For the mode SIGN the call needs a usable signing key, like create_policy. Only an administrator can call it.

Signature:

procedure activate_policy (
  p_policy_id in adm_signing_policies.policy_id%type
);

Parameters:

Name	Direction	Type	Description
p_policy_id	in	adm_signing_policies.policy_id%type	The policy

---

deactivate_policy

Switches a policy off. The folders that it covered use the next shorter pattern, or the default mode. Only an administrator can call it.

Signature:

procedure deactivate_policy (
  p_policy_id in adm_signing_policies.policy_id%type
);

Parameters:

Name	Direction	Type	Description
p_policy_id	in	adm_signing_policies.policy_id%type	The policy

---

delete_policy

Deletes a policy. Only an administrator can call it.

Signature:

procedure delete_policy (
  p_policy_id in adm_signing_policies.policy_id%type
);

Parameters:

Name	Direction	Type	Description
p_policy_id	in	adm_signing_policies.policy_id%type	The policy

---

list_policies

The policies, with the longest pattern first. Only an administrator can call it.

Signature:

function list_policies return t_policies;

Returns: t_policies - All policies, active or not

---