case-procs.tcl

Publicity: Public Only All

case-procs.tcl

Procedures in the case namespace.

Location:

packages/workflow/tcl/case-procs.tcl
Created:

13 January 2003
Authors:

Lars Pind <lars@collaboraid.biz>
Peter Marklund <peter@collaboraid.biz>
CVS Identification:

$Id: case-procs.tcl,v 1.59 2024/10/13 09:03:15 gustafn Exp $

Procedures in this file

workflow::case::action::available_p (public)
workflow::case::action::do_side_effects (public)
workflow::case::action::enabled_p (public)
workflow::case::action::execute (public)
workflow::case::action::notify (public)
workflow::case::action::permission_p (public)
workflow::case::active_p (public)
workflow::case::add_log_data (public)
workflow::case::delete (public)
workflow::case::enabled_action_get (public)
workflow::case::enabled_action_get_element (public)
workflow::case::fsm::get (public)
workflow::case::fsm::get_current_state (public)
workflow::case::fsm::get_element (public)
workflow::case::get (public)
workflow::case::get_available_actions (public, deprecated)
workflow::case::get_available_enabled_action_ids (public)
workflow::case::get_element (public)
workflow::case::get_enabled_action_ids (public)
workflow::case::get_enabled_action_ids_not_cached (public)
workflow::case::get_enabled_actions (public, deprecated)
workflow::case::get_id (public)
workflow::case::get_log_data (public)
workflow::case::get_log_data_by_key (public)
workflow::case::get_notification_object (public)
workflow::case::get_notification_request_url (public)
workflow::case::get_notification_requests_multirow (public)
workflow::case::get_user_roles (public)
workflow::case::new (public)
workflow::case::role::add_assignee_widgets (public)
workflow::case::role::assign (public)
workflow::case::role::assignee_insert (public)
workflow::case::role::assignee_remove (public)
workflow::case::role::assignees_remove (public)
workflow::case::role::get_assignee_widget (public)
workflow::case::role::get_assignees (public)
workflow::case::role::get_picklist (public)
workflow::case::role::get_search_query (public)
workflow::case::role::set_assignee_values (public)
workflow::case::role::set_default_assignees (public)
workflow::case::timed_actions_sweeper (public)

Detailed information

workflow::case::action::available_p (public)

 workflow::case::action::available_p \
    [ -enabled_action_id enabled_action_id ] [ -case_id case_id ] \
    [ -action_id action_id ] [ -user_id user_id ]

Is this action currently enabled and does the user have permission to perform it?

Switches:

-enabled_action_id (optional)
The enabled action you want to test for permission on.
-case_id (optional)
Deprecated. The ID of the case.
-action_id (optional)
Deprecated. The ID of the action
-user_id (optional)
The user.

Returns:
true or false.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::action::do_side_effects (public)

 workflow::case::action::do_side_effects -case_id case_id \
    -action_id action_id -entry_id entry_id

Fire the side-effects for this action

Switches:

-case_id (required)
-action_id (required)
-entry_id (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::action::enabled_p (public)

 workflow::case::action::enabled_p -case_id case_id \
    -action_id action_id

Is this action currently enabled.

Switches:

-case_id (required)
The ID of the case.
-action_id (required)
The ID of the action

Returns:
true or false.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::action::execute (public)

 workflow::case::action::execute [ -no_notification ] \
    [ -no_perm_check ] [ -no_logging ] \
    [ -enabled_action_id enabled_action_id ] [ -case_id case_id ] \
    [ -action_id action_id ] \
    [ -parent_enabled_action_id parent_enabled_action_id ] \
    [ -comment comment ] [ -comment_mime_type comment_mime_type ] \
    [ -user_id user_id ] [ -initial ] [ -entry_id entry_id ] \
    [ -package_id package_id ]

Execute the action. Either provide (case_id, action_id, parent_enabled_action_id), or simply enabled_action_id.

Switches:

-no_notification (optional, boolean)
-no_perm_check (optional, boolean)
Set this switch if you do not want to have any workflow_case loggings.
-no_logging (optional, boolean)
-enabled_action_id (optional)
The ID of the enabled action to execute. Alternatively, you can specify the case_id/action_id pair.
-case_id (optional)
The ID of the case.
-action_id (optional)
The ID of the action
-parent_enabled_action_id (optional)
-comment (optional)
Comment for the case activity log
-comment_mime_type (optional, defaults to "text/plain")
MIME Type of the comment, according to OpenACS standard text formatting
-user_id (optional)
The user who's executing the action
-initial (optional, boolean)
Use this switch to signal that this is the initial action. This causes permissions/enabled checks to be bypasssed, and causes all roles to get assigned.
-entry_id (optional)
Optional item_id for double-click protection. If you call workflow::case::fsm::get with a non-empty action_id, it will generate a new entry_id for you, which you can pass in here.
-package_id (optional)
The package_id the case object belongs to. This is optional but is useful if the case objects are not CR items.

Returns:
entry_id of the new log entry (will be a cr_item).

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::action::notify (public)

 workflow::case::action::notify -case_id case_id -action_id action_id \
    -entry_id entry_id -comment comment \
    -comment_mime_type comment_mime_type

Send out notifications to relevant people.

Switches:

-case_id (required)
-action_id (required)
-entry_id (required)
-comment (required)
-comment_mime_type (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::action::permission_p (public)

 workflow::case::action::permission_p \
    [ -enabled_action_id enabled_action_id ] [ -case_id case_id ] \
    [ -action_id action_id ] [ -user_id user_id ]

Does the user have permission to perform this action. Doesn't check whether the action is enabled.

Switches:

-enabled_action_id (optional)
The enabled action you want to test for permission on.
-case_id (optional)
Deprecated. The ID of the case.
-action_id (optional)
Deprecated. The ID of the action
-user_id (optional)
The user.

Returns:
true or false.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::active_p (public)

 workflow::case::active_p -case_id case_id

Returns true if the case is active, otherwise false.

Switches:

-case_id (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::add_log_data (public)

 workflow::case::add_log_data -entry_id entry_id -key key -value value

Adds extra data information to a log entry, which can later be retrieved using workflow::case::get_log_data_by_key. Data are stored as simple key/value pairs.

Switches:

-entry_id (required)
The ID of the log entry to which you want to attach data.
-key (required)
The data key.
-value (required)
The data value

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::get_log_data_by_key
workflow::case::get_log_data

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::delete (public)

 workflow::case::delete -case_id case_id

Delete a workflow case.

Switches:

-case_id (required)
The case_id you wish to delete

Author:

Simon Carstensen <simon@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::enabled_action_get (public)

 workflow::case::enabled_action_get \
    -enabled_action_id enabled_action_id -array array

Get information about an enabled action

Switches:

-enabled_action_id (required)
-array (required)
The name of an array in which information will be returned.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::enabled_action_get_element (public)

 workflow::case::enabled_action_get_element \
    -enabled_action_id enabled_action_id -element element

Return a single element from the information about an enabled action

Switches:

-enabled_action_id (required)
-element (required)
The element you want

Returns:
The element you asked for

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::fsm::get (public)

 workflow::case::fsm::get -case_id case_id -array array \
    [ -parent_enabled_action_id parent_enabled_action_id ] \
    [ -action_id action_id ] [ -enabled_action_id enabled_action_id ]

Get information about an FSM case set as values in your array. case_id state_short_name pretty_state state_hide_fields state_id parent_enabled_action_id parent_case_id entry_id top_case_id workflow_id object_id

Switches:

-case_id (required)
The ID of the case
-array (required)
The name of an array in which information will be returned.
-parent_enabled_action_id (optional)
If specified, will return the sub-case information for the given action.
-action_id (optional)
Deprecated. Same effect as enabled_action_id, but will not work for dynamic workflows.
-enabled_action_id (optional)
If specified, will return the case information as if the given action had already been executed. This is useful for presenting forms for actions that do not take place until the user hits OK.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::fsm::get_current_state (public)

 workflow::case::fsm::get_current_state -case_id case_id

Gets the current state_id of this case.

Switches:

-case_id (required)
The case_id.

Returns:
The state_id of the state which this case is in

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::fsm::get_element (public)

 workflow::case::fsm::get_element -case_id case_id -element element \
    [ -parent_enabled_action_id parent_enabled_action_id ] \
    [ -action_id action_id ]

Return a single element from the information about a case.

Switches:

-case_id (required)
The ID of the case
-element (required)
The element you want
-parent_enabled_action_id (optional)
-action_id (optional)
If specified, will return the case information as if the given action had already been executed. This is useful for presenting forms for actions that do not take place until the user hits OK.

Returns:
The element you asked for

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get (public)

 workflow::case::get -case_id case_id -array array \
    [ -action_id action_id ]

Get information about a case. Implemented by workflow::case::fsm::get, because we do not yet support multiple workflow engines.

Switches:

-case_id (required)
The case ID
-array (required)
The name of an array in which information will be returned.
-action_id (optional)
If specified, will return the case information as if the given action had already been executed. This is useful for presenting forms for actions that do not take place until the user hits OK.

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::fsm::get

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_available_actions (public, deprecated)

 workflow::case::get_available_actions -case_id case_id \
    [ -user_id user_id ]

Deprecated. Invoking this procedure generates a warning.

Get the actions which are enabled and which the current user have permission to execute.

Switches:

-case_id (required)
The ID of the case.
-user_id (optional)

Returns:
A list of ID's of the available actions.

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::get_available_enabled_action_ids

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_available_enabled_action_ids (public)

 workflow::case::get_available_enabled_action_ids -case_id case_id \
    [ -user_id user_id ]

Get the enabled_action_id's of the actions available to the given user.

Switches:

-case_id (required)
The ID of the case.
-user_id (optional)

Returns:
A list of ID's of the available actions.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_element (public)

 workflow::case::get_element -case_id case_id -element element \
    [ -action_id action_id ]

Return a single element from the information about a case.

Switches:

-case_id (required)
The ID of the case
-element (required)
The element you want
-action_id (optional)
If specified, will return the case information as if the given action had already been executed. This is useful for presenting forms for actions that do not take place until the user hits OK.

Returns:
The element you asked for

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_enabled_action_ids (public)

 workflow::case::get_enabled_action_ids -case_id case_id \
    [ -trigger_type trigger_type ]

Get the currently enabled_action_id's of enabled user actions in the case. Note that this is different from get_enabled_actions, which only returns the action_id, which will not work for dynamic actions.

Switches:

-case_id (required)
The ID of the case.
-trigger_type (optional, defaults to "user")
You can limit to e.g. user actions here. Defaults to user actions. Specify the empty string if you want all actions.

Returns:
A list of currently available enabled_action_id's.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_enabled_action_ids_not_cached (public)

 workflow::case::get_enabled_action_ids_not_cached case_id \
    [ trigger_type ]

Used internally by the workflow API only. Goes to the database to get the enabled actions for the case.

Parameters:

case_id (required)

trigger_type (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_enabled_actions (public, deprecated)

 workflow::case::get_enabled_actions -case_id case_id

Deprecated. Invoking this procedure generates a warning.

Get the currently enabled user actions, based on the state of the case

Switches:

-case_id (required)
The ID of the case.

Returns:
A list of action_id's of the actions which are currently enabled

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::get_enabled_action_ids

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_id (public)

 workflow::case::get_id -object_id object_id \
    -workflow_short_name workflow_short_name

Gets the case_id from the object_id which the case is about, along with the short_name of the workflow.

Switches:

-object_id (required)
The object_id which the case is about
-workflow_short_name (required)
The short_name of the workflow.

Returns:
The case_id of the case. Returns the empty string if no case could be found.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_log_data (public)

 workflow::case::get_log_data -entry_id entry_id

Retrieve extra data for a workflow log entry, previously stored using workflow::case::add_log_data.

Switches:

-entry_id (required)
The ID of the log entry to which the data you want are attached.

Returns:
A tcl list of key/value pairs in array-list format, i.e. { key1 value1 key2 value2 ... }.

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::add_log_data
workflow::case::get_log_data_by_key

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_log_data_by_key (public)

 workflow::case::get_log_data_by_key -entry_id entry_id -key key

Retrieve extra data for a workflow log entry, previously stored using workflow::case::add_log_data.

Switches:

-entry_id (required)
The ID of the log entry to which the data you want are attached.
-key (required)
The key of the data you're looking for.

Returns:
The value, or the empty string if no such key exists for this entry.

Author:

Lars Pind <lars@collaboraid.biz>

See Also:

workflow::case::add_log_data
workflow::case::get_log_data

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_notification_object (public)

 workflow::case::get_notification_object -type type \
    [ -workflow_id workflow_id ] [ -case_id case_id ]

Get the relevant object for this notification type.

Switches:

-type (required)
Type is one of 'workflow_assignee', 'workflow_my_cases', 'workflow_case' (requires case_id), and 'workflow' (requires workflow_id).
-workflow_id (optional)
-case_id (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_notification_request_url (public)

 workflow::case::get_notification_request_url -type type \
    [ -workflow_id workflow_id ] [ -case_id case_id ] \
    [ -return_url return_url ] [ -pretty_name pretty_name ]

Get the URL to subscribe to notifications

Switches:

-type (required)
Type is one of 'workflow_assignee', 'workflow_my_cases', 'workflow_case' (requires case_id), and 'workflow' (requires workflow_id).
-workflow_id (optional)
-case_id (optional)
-return_url (optional)
-pretty_name (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_notification_requests_multirow (public)

 workflow::case::get_notification_requests_multirow \
    -multirow_name multirow_name [ -label label ] \
    [ -workflow_id workflow_id ] [ -case_id case_id ] \
    [ -return_url return_url ]

Returns a multirow with columns url, label, title, of the possible workflow notification types. Use this to present the user with a list of subscription links.

Switches:

-multirow_name (required)
-label (optional)
-workflow_id (optional)
-case_id (optional)
-return_url (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::get_user_roles (public)

 workflow::case::get_user_roles -case_id case_id [ -user_id user_id ]

Get the roles which this user is assigned to. Takes deputies into account, so that if the user is a deputy for someone else, he or she will have the roles of the user for whom he/she is a deputy.

Switches:

-case_id (required)
The ID of the case.
-user_id (optional)
The user_id of the user for which you want to know the roles. Defaults to ad_conn user_id.

Returns:
A list of role_id's of the roles which the user is assigned to in this case.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::new (public)

 workflow::case::new [ -no_notification ] -workflow_id workflow_id \
    [ -case_id case_id ] [ -object_id object_id ] [ -comment comment ] \
    [ -comment_mime_type comment_mime_type ] [ -user_id user_id ] \
    [ -assignment assignment ] [ -package_id package_id ] \
    [ -initial_action_id initial_action_id ]

Start a new case for this workflow and object.

Switches:

-no_notification (optional, boolean)
-workflow_id (required)
The ID of the workflow for the case.
-case_id (optional)
-object_id (optional)
The object_id which the case is about
-comment (optional)
-comment_mime_type (optional)
text/html, text/plain, text/pre, text/enhanced.
-user_id (optional)
-assignment (optional)
Array-list of role_short_name and list of party_ids to assign to roles before starting.
-package_id (optional)
-initial_action_id (optional)

Returns:
The case_id of the case.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::add_assignee_widgets (public)

 workflow::case::role::add_assignee_widgets -case_id case_id \
    -form_name form_name [ -prefix prefix ] [ -role_ids role_ids ]

Get the assignee widget for use with ad_form for this role.

Switches:

-case_id (required)
the ID of the case.
-form_name (required)
-prefix (optional, defaults to "role_")
-role_ids (optional)
Only add assignee widgets for the roles supplied. If no roles are specified then all roles are used.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::assign (public)

 workflow::case::role::assign -case_id case_id -array array \
    [ -replace ]

Assign roles from an array with entries like this: array(short_name) = [list of party_ids].

Switches:

-case_id (required)
The ID of the case.
-array (required)
Name of array with assignment info
-replace (optional, boolean)
Should the new assignees replace existing assignees?

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::assignee_insert (public)

 workflow::case::role::assignee_insert -case_id case_id \
    -role_id role_id -party_ids party_ids [ -replace ]

Insert a new assignee for this role

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role to assign.
-party_ids (required)
-replace (optional, boolean)

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::assignee_remove (public)

 workflow::case::role::assignee_remove -case_id case_id \
    -role_id role_id -party_id party_id

Remove an assignee from this role

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role to remove the assignee from.
-party_id (required)
the ID of party to remove from the role

Author:

Peter Marklund

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::assignees_remove (public)

 workflow::case::role::assignees_remove -case_id case_id \
    -role_id role_id

Remove all assignees in this role

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role to remove the assignees from.

Author:

Ryan Gallimore

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::get_assignee_widget (public)

 workflow::case::role::get_assignee_widget -case_id case_id \
    -role_id role_id [ -prefix prefix ]

Get the assignee widget for use with ad_form for this role.

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role.
-prefix (optional, defaults to "role_")

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::get_assignees (public)

 workflow::case::role::get_assignees -case_id case_id -role_id role_id

Get the current assignees for a role in a case as a list of [array get]'s of party_id, email, name.

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role.

Returns:
a list of [array get]'s of party_id, email, name.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::get_picklist (public)

 workflow::case::role::get_picklist -case_id case_id -role_id role_id

Get the picklist for this role.

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::get_search_query (public)

 workflow::case::role::get_search_query -case_id case_id \
    -role_id role_id

Get the search query for this role.

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::set_assignee_values (public)

 workflow::case::role::set_assignee_values -case_id case_id \
    -form_name form_name [ -prefix prefix ]

Get the assignee widget for use with ad_form for this role.

Switches:

-case_id (required)
the ID of the case.
-form_name (required)
-prefix (optional, defaults to "role_")

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::role::set_default_assignees (public)

 workflow::case::role::set_default_assignees -case_id case_id \
    -role_id role_id

Find the default assignee for this role.

Switches:

-case_id (required)
the ID of the case.
-role_id (required)
the ID of the role to assign.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

workflow::case::timed_actions_sweeper (public)

 workflow::case::timed_actions_sweeper

Sweep for timed actions ready to fire.

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

[ show source ]