adm_user_items_api

Personal “my stuff” of a user: the Recent list and color labels.

Recent keeps the documents the user worked with last. ADM fills it by itself: every VIEW_DOCUMENT, DOWNLOAD_DOCUMENT, CREATE_DOCUMENT, ADD_DOCUMENT_VERSION, MERGE_DOCUMENT_VERSION and RESTORE_DOCUMENT_VERSION audit entry of a document calls record_document_activity. The setting RECENT_DOCUMENTS_LIMIT (default 50) sets how many documents each user keeps; 0 switches Recent off.

Color labels work like the Finder: a user puts one or more of seven colors (red, orange, yellow, green, blue, purple, gray) on documents and folders, and can give each color a name of their own.

Everything here is private to the user of the ADM session context. There is no username parameter on purpose. Reading is done with the views adm_my_recent_documents_v, adm_my_color_labels_v and adm_my_color_label_names_v, which show only items the session may still see: an item that was trashed, or that the user lost access to, drops out of them without a trace.

begin
  adm_context_api.system_user_login('ALICE');
  adm_user_items_api.add_color_label(p_color => 'red', p_document_id => 42);
  adm_user_items_api.set_color_name(p_color => 'red', p_name => 'Urgent');
end;
/
select item_name, color, color_name from adm_my_color_labels_v;

Functions and Procedures

record_document_activity

Notes that the session user worked with a document. Called by adm_audit_api.add_audit; there is normally no reason to call it yourself.

Never raises: a failure is logged and the caller goes on. It does nothing for the system user, for a session without a user, for an embed session, for a document the user can reach only through a share link, when RECENT_DOCUMENTS_LIMIT is 0, and for any action other than the six listed in the package description. It does not commit.

Signature:

procedure record_document_activity (
  p_document_id in adm_documents.document_id%type,
  p_action in adm_audit_log.action_type%type
);

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The document
p_action	in	adm_audit_log.action_type%type	Audit action type, for example VIEW_DOCUMENT

---

remove_recent_document

Removes one document from the Recent list of the session user.

Signature:

procedure remove_recent_document (
  p_document_id in adm_documents.document_id%type
);

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The document

---

clear_recent_documents

Empties the Recent list of the session user.

Signature:

procedure clear_recent_documents;

---

add_color_label

Puts a color label on a document or a folder. Does nothing when the label is already there. Give exactly one of p_document_id and p_folder_id.

Signature:

procedure add_color_label (
  p_color in varchar2,
  p_document_id in adm_documents.document_id%type default null,
  p_folder_id in adm_folders.folder_id%type default null
);

Parameters:

Name	Direction	Type	Description
p_color	in	varchar2	One of red, orange, yellow, green, blue, purple, gray
p_document_id	in	adm_documents.document_id%type default null	The document to label
p_folder_id	in	adm_folders.folder_id%type default null	The folder to label

---

remove_color_label

Takes a color label off a document or a folder. Does nothing when the label is not there. It needs no view right, so a user who lost access can still drop their own label. Give exactly one of p_document_id and p_folder_id.

Signature:

procedure remove_color_label (
  p_color in varchar2,
  p_document_id in adm_documents.document_id%type default null,
  p_folder_id in adm_folders.folder_id%type default null
);

Parameters:

Name	Direction	Type	Description
p_color	in	varchar2	One of red, orange, yellow, green, blue, purple, gray
p_document_id	in	adm_documents.document_id%type default null	The document
p_folder_id	in	adm_folders.folder_id%type default null	The folder

---

set_color_labels

Replaces all color labels of the session user on a document or a folder by the given set. An empty or null set removes all of them. Give exactly one of p_document_id and p_folder_id.

Signature:

procedure set_color_labels (
  p_colors in apex_t_varchar2,
  p_document_id in adm_documents.document_id%type default null,
  p_folder_id in adm_folders.folder_id%type default null
);

Parameters:

Name	Direction	Type	Description
p_colors	in	apex_t_varchar2	The colors the item gets
p_document_id	in	adm_documents.document_id%type default null	The document
p_folder_id	in	adm_folders.folder_id%type default null	The folder

---

get_color_labels

The colors the session user put on a document or a folder, in the order red, orange, yellow, green, blue, purple, gray. Empty when there are none or when the user may not see the item. Give exactly one of p_document_id and p_folder_id.

Signature:

function get_color_labels (
  p_document_id in adm_documents.document_id%type default null,
  p_folder_id in adm_folders.folder_id%type default null
) return apex_t_varchar2;

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type default null	The document
p_folder_id	in	adm_folders.folder_id%type default null	The folder

Returns: apex_t_varchar2 - The colors

---

set_color_name

Gives a color a name of the session user’s own. A null or empty name returns the color to its default name.

Signature:

procedure set_color_name (
  p_color in varchar2,
  p_name in varchar2
);

Parameters:

Name	Direction	Type	Description
p_color	in	varchar2	One of red, orange, yellow, green, blue, purple, gray
p_name	in	varchar2	The name, at most 50 characters, or null to reset

---

get_color_names

The name of every color for the session user, the default name where the user set none. The array is indexed by the color code.

Signature:

function get_color_names return t_color_names;

Returns: t_color_names - The names of all seven colors

---

get_default_color_name

The default name of a color, for example Red for red.

Signature:

function get_default_color_name (
  p_color in varchar2
) return varchar2;

Parameters:

Name	Direction	Type	Description
p_color	in	varchar2	One of red, orange, yellow, green, blue, purple, gray

Returns: varchar2 - The default name

---