- Publicity: Public Only All
action-procs.tcl
Procedures in the workflow::action namespace.
- Location:
- packages/workflow/tcl/action-procs.tcl
- Created:
- 9 January 2003
- Authors:
- Lars Pind <lars@collaboraid.biz>
- Peter Marklund <peter@collaboraid.biz>
- CVS Identification:
$Id: action-procs.tcl,v 1.44 2022/09/28 09:12:55 gustafn Exp $
Procedures in this file
- workflow::action::callback_insert (public)
- workflow::action::delete (public)
- workflow::action::edit (public)
- workflow::action::flush_cache (private)
- workflow::action::fsm::delete (public)
- workflow::action::fsm::edit (public)
- workflow::action::fsm::generate_spec (private)
- workflow::action::fsm::get (public)
- workflow::action::fsm::get_element (public)
- workflow::action::fsm::get_ids (public)
- workflow::action::fsm::get_new_state (public)
- workflow::action::fsm::new (public)
- workflow::action::fsm::parse_spec (private)
- workflow::action::fsm::set_enabled_in_state (public)
- workflow::action::generate_short_name (public)
- workflow::action::get (public)
- workflow::action::get_all_info (private)
- workflow::action::get_all_info_not_cached (private)
- workflow::action::get_allowed_roles (public)
- workflow::action::get_assigned_role (public)
- workflow::action::get_callbacks (private)
- workflow::action::get_element (public)
- workflow::action::get_existing_short_names (public)
- workflow::action::get_from_request_cache (private)
- workflow::action::get_id (public)
- workflow::action::get_ids (public)
- workflow::action::get_options (public)
- workflow::action::get_privileges (public)
- workflow::action::get_workflow_id (public)
- workflow::action::get_workflow_id_not_cached (private)
- workflow::action::new (public)
- workflow::action::pretty_name_unique_p (public)
- workflow::action::refresh_request_cache (private)
- workflow::action::update_sort_order (private)
Detailed information
workflow::action::callback_insert (public)
workflow::action::callback_insert -action_id action_id -name name \ [ -sort_order sort_order ]
Add a side-effect to an action.
- Switches:
- -action_id (required)
- The ID of the action.
- -name (required)
- Name of service contract implementation, in the form (impl_owner_name).(impl_name), for example, bug-tracker.CaptureResolutionCode
- -sort_order (optional)
- The sort_order for the rule. Leave blank to add to the end of the list
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::delete (public)
workflow::action::delete -action_id action_id
Delete action with given id.
- Switches:
- -action_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::edit (public)
workflow::action::edit [ -operation operation ] \ [ -action_id action_id ] [ -workflow_id workflow_id ] \ [ -array array ] [ -internal ] [ -no_complain ] \ [ -handlers handlers ]
Edit an action. Attributes of the array:
Deprecated but still supported:
- short_name
- pretty_name
- pretty_past_tense
- edit_fields
- description
- description_mime_type
- sort_order
- always_enabled_p
- assigned_role
- timeout_seconds
- trigger_type
- parent_action
- parent_action_id
- privileges
- allowed_roles
- callbacks
- child_actions
- initial_action_p
- Switches:
- -operation (optional, defaults to
"update"
)- insert, update, delete
- -action_id (optional)
- For update/delete: The action to update or delete. For insert: Optionally specify a pre-generated action_id for the action.
- -workflow_id (optional)
- For update/delete: Optionally specify the workflow_id. If not specified, we will execute a query to find it. For insert: The workflow_id of the new action.
- -array (optional)
- For insert/update: Name of an array in the caller's namespace with attributes to insert/update.
- -internal (optional, boolean)
- Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do.
- -no_complain (optional, boolean)
- Silently ignore extra attributes that we don't know how to handle.
- -handlers (optional, defaults to
" roles "workflow::role" actions "workflow::action" "
)- Returns:
- action_id
- Author:
- Lars Pind <lars@collaboraid.biz>
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::flush_cache (private)
workflow::action::flush_cache -workflow_id workflow_id
Flush all caches related to actions for the given workflow_id. Used internally by the workflow API only.
- Switches:
- -workflow_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::delete (public)
workflow::action::fsm::delete -action_id action_id
Delete FSM action with given id.
- Switches:
- -action_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::edit (public)
workflow::action::fsm::edit [ -operation operation ] \ [ -action_id action_id ] [ -workflow_id workflow_id ] \ [ -array array ] [ -internal ] [ -handlers handlers ]
Edit an action. Attributes:
- new_state_id
- enabled_states
- enabled_state_ids
- enabled_actions
- enabled_action_ids
- child_states
- Switches:
- -operation (optional, defaults to
"update"
)- insert, update, delete
- -action_id (optional)
- For update/delete: The action to update or delete. For insert: Optionally specify a pre-generated action_id for the action.
- -workflow_id (optional)
- For update/delete: Optionally specify the workflow_id. If not specified, we will execute a query to find it. For insert: The workflow_id of the new action.
- -array (optional)
- For insert/update: Name of an array in the caller's namespace with attributes to insert/update.
- -internal (optional, boolean)
- Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do.
- -handlers (optional, defaults to
" roles "workflow::role" actions "workflow::action::fsm" states "workflow::state::fsm" "
)- Returns:
- action_id
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::generate_spec (private)
workflow::action::fsm::generate_spec [ -action_id action_id ] \ [ -one_id one_id ] [ -handlers handlers ]
Generate the spec for an individual action definition.
- Switches:
- -action_id (optional)
- The id of the action to generate spec for.
- -one_id (optional)
- Same as action_id, just used for consistency across roles/actions/states.
- -handlers (optional)
- Returns:
- spec The actions spec
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::get (public)
workflow::action::fsm::get -action_id action_id -array array
Return information about an action with a given id, including FSM-related info: enabled_states, enabled_state_ids, assigned_states, assigned_state_ids, new_state, new_state_id.
- Switches:
- -action_id (required)
- -array (required)
- Authors:
- Peter Marklund
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::get_element (public)
workflow::action::fsm::get_element [ -action_id action_id ] \ [ -one_id one_id ] -element element
Return element from information about an action with a given id, including FSM-related info such as 'enabled_in_states', and 'new_state'. Return a single element from the information about a action.
- Switches:
- -action_id (optional)
- The ID of the action
- -one_id (optional)
- Same as action_id, just used for consistency across roles/actions/states.
- -element (required)
- The element you want
- Returns:
- The element you asked for
- Authors:
- Peter Marklund
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::get_ids (public)
workflow::action::fsm::get_ids [ -all ] -workflow_id workflow_id \ [ -parent_action_id parent_action_id ]
Get the action_id's of all the actions in the workflow.
- Switches:
- -all (optional, boolean)
- -workflow_id (required)
- The ID of the workflow
- -parent_action_id (optional)
- Returns:
- list of action_id's.
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::get_new_state (public)
workflow::action::fsm::get_new_state -action_id action_id
Return the ID of the new state for an action
- Switches:
- -action_id (required)
- The action_id of the action.
- Returns:
- The ID of the new state after executing this action, or the empty string if the action doesn't change the state.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::new (public)
workflow::action::fsm::new -workflow_id workflow_id \ [ -action_id action_id ] [ -sort_order sort_order ] \ [ -short_name short_name ] -pretty_name pretty_name \ [ -pretty_past_tense pretty_past_tense ] \ [ -edit_fields edit_fields ] [ -allowed_roles allowed_roles ] \ [ -assigned_role assigned_role ] [ -privileges privileges ] \ [ -enabled_states enabled_states ] \ [ -assigned_states assigned_states ] \ [ -enabled_state_ids enabled_state_ids ] \ [ -assigned_state_ids assigned_state_ids ] \ [ -new_state new_state ] [ -new_state_id new_state_id ] \ [ -callbacks callbacks ] [ -initial_action_p initial_action_p ] \ [ -always_enabled_p always_enabled_p ] \ [ -trigger_type trigger_type ] [ -parent_action parent_action ] \ [ -description description ] \ [ -description_mime_type description_mime_type ] \ [ -timeout_seconds timeout_seconds ]
Add an action to a certain FSM (Finite State Machine) workflow. This procedure invokes the generic workflow::action::new procedures and does additional inserts for FSM specific information. See the parameter documentation for the proc workflow::action::new.
- Switches:
- -workflow_id (required)
- -action_id (optional)
- -sort_order (optional)
- -short_name (optional)
- -pretty_name (required)
- -pretty_past_tense (optional)
- -edit_fields (optional)
- -allowed_roles (optional)
- -assigned_role (optional)
- -privileges (optional)
- -enabled_states (optional)
- -assigned_states (optional)
- -enabled_state_ids (optional)
- -assigned_state_ids (optional)
- -new_state (optional)
- -new_state_id (optional)
- -callbacks (optional)
- -initial_action_p (optional)
- -always_enabled_p (optional, defaults to
"f"
)- -trigger_type (optional, defaults to
"user"
)- -parent_action (optional)
- -description (optional)
- -description_mime_type (optional)
- -timeout_seconds (optional)
- Returns:
- the new action_id.
- Author:
- Peter Marklund
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::parse_spec (private)
workflow::action::fsm::parse_spec -workflow_id workflow_id \ -short_name short_name -spec spec \ [ -parent_action_id parent_action_id ]
Parse the spec for an individual action definition.
- Switches:
- -workflow_id (required)
- The id of the workflow to delete.
- -short_name (required)
- The short_name of the action
- -spec (required)
- The action spec
- -parent_action_id (optional)
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::fsm::set_enabled_in_state (public)
workflow::action::fsm::set_enabled_in_state -action_id action_id \ -state_id state_id [ -enabled ] [ -assigned ] \ [ -workflow_id workflow_id ]
Edit the enabled state of an action
- Switches:
- -action_id (required)
- -state_id (required)
- -enabled (optional, boolean)
- -assigned (optional, boolean)
- -workflow_id (optional)
- Optionally provide the workflow_id. If not, this will be gotten from a query.
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::generate_short_name (public)
workflow::action::generate_short_name -workflow_id workflow_id \ -pretty_name pretty_name [ -short_name short_name ] \ [ -action_id action_id ]
Generate a unique short_name from pretty_name.
- Switches:
- -workflow_id (required)
- -pretty_name (required)
- -short_name (optional)
- -action_id (optional)
- If you pass in this, we will allow that action's short_name to be reused.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get (public)
workflow::action::get -action_id action_id -array array
Return information about an action with a given id.
- Switches:
- -action_id (required)
- -array (required)
- Returns:
- The array will contain the following entries: workflow_id, sort_order, short_name, pretty_name, pretty_past_tense, assigned_role (short_name), assigned_role_id, always_enabled_p, trigger_type, parent_action, parent_action_id, description, description_mime_type values for an action.
- Authors:
- Peter Marklund
- Lars Pind <lars@collaboraid.biz>
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_all_info (private)
workflow::action::get_all_info -workflow_id workflow_id
This proc is for internal use in the workflow API only. Returns all information related to actions for a certain workflow instance. Uses util_memoize to cache values.
- Switches:
- -workflow_id (required)
- Author:
- Peter Marklund
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_all_info_not_cached (private)
workflow::action::get_all_info_not_cached -workflow_id workflow_id
This proc is for internal use in the workflow API only and should not be invoked directly from application code. Returns all information related to actions for a certain workflow instance. Goes to the database on every invocation and should be used together with util_memoize.
- Switches:
- -workflow_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_allowed_roles (public)
workflow::action::get_allowed_roles -action_id action_id
Return the allowed roles of the given action
- Switches:
- -action_id (required)
- The action_id of the action.
- Returns:
- List of role_id of the allowed roles
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_assigned_role (public)
workflow::action::get_assigned_role -action_id action_id
Return the assigned role of the given action
- Switches:
- -action_id (required)
- The action_id of the action.
- Returns:
- role_id of the assigned role.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_callbacks (private)
workflow::action::get_callbacks -action_id action_id \ -contract_name contract_name
Return a list of implementation names for the callbacks of a given workflow action.
- Switches:
- -action_id (required)
- -contract_name (required)
- Author:
- Peter Marklund
- See Also:
- workflow::case::role::get_callbacks
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_element (public)
workflow::action::get_element [ -action_id action_id ] \ [ -one_id one_id ] -element element
Return a single element from the information about a action.
- Switches:
- -action_id (optional)
- The ID of the action
- -one_id (optional)
- Same as action_id, just used for consistency across roles/actions/states.
- -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::action::get_existing_short_names (public)
workflow::action::get_existing_short_names -workflow_id workflow_id \ [ -ignore_action_id ignore_action_id ]
Returns a list of existing action short_names in this workflow. Useful when you're trying to ensure a short_name is unique, or construct a new short_name that is guaranteed to be unique.
- Switches:
- -workflow_id (required)
- -ignore_action_id (optional)
- If specified, the short_name for the given action will not be included in the result set.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_from_request_cache (private)
workflow::action::get_from_request_cache action_id [ element ]
This provides some abstraction for the Workflow API cache and also some optimization - we only convert lists to arrays once per request. Should be used internally by the workflow API only.
- Parameters:
- action_id (required)
- element (optional)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_id (public)
workflow::action::get_id -workflow_id workflow_id \ -short_name short_name
Return the action_id of the action with the given short_name in the given workflow.
- Switches:
- -workflow_id (required)
- The ID of the workflow
- -short_name (required)
- The short_name of the action
- Returns:
- action_id of the desired action, or the empty string if it can't be found.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_ids (public)
workflow::action::get_ids [ -all ] -workflow_id workflow_id \ [ -parent_action_id parent_action_id ]
Get the action_id's of all the actions in the workflow.
- Switches:
- -all (optional, boolean)
- -workflow_id (required)
- The ID of the workflow
- -parent_action_id (optional)
- Returns:
- list of action_id's.
- Author:
- Lars Pind <lars@collaboraid.biz>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_options (public)
workflow::action::get_options [ -all ] -workflow_id workflow_id \ [ -parent_action_id parent_action_id ]
Get an options list of actions for use with form builder.
- Switches:
- -all (optional, boolean)
- -workflow_id (required)
- -parent_action_id (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_privileges (public)
workflow::action::get_privileges -action_id action_id
Return the assigned role of the given action
- Switches:
- -action_id (required)
- The action_id of the action.
- Returns:
- List of privileges that give permission to do this action
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_workflow_id (public)
workflow::action::get_workflow_id -action_id action_id
Lookup the workflow_id of a certain action_id.
- Switches:
- -action_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::get_workflow_id_not_cached (private)
workflow::action::get_workflow_id_not_cached -action_id action_id
This is a proc that should only be used internally by the workflow API, applications should use workflow::action::get_workflow_id instead.
- Switches:
- -action_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::new (public)
workflow::action::new -workflow_id workflow_id \ [ -action_id action_id ] [ -sort_order sort_order ] \ [ -short_name short_name ] -pretty_name pretty_name \ [ -pretty_past_tense pretty_past_tense ] \ [ -edit_fields edit_fields ] [ -assigned_role assigned_role ] \ [ -allowed_roles allowed_roles ] [ -privileges privileges ] \ [ -callbacks callbacks ] [ -always_enabled_p always_enabled_p ] \ [ -initial_action_p initial_action_p ] \ [ -trigger_type trigger_type ] [ -parent_action parent_action ] \ [ -description description ] \ [ -description_mime_type description_mime_type ] \ [ -timeout_seconds timeout_seconds ] [ -internal ]
This procedure is normally not invoked from application code. Instead a procedure for a certain workflow implementation, such as for example workflow::action::fsm::new (for Finite State Machine workflows), is used.
- Switches:
- -workflow_id (required)
- The id of the FSM workflow to add the action to
- -action_id (optional)
- Optionally specify the ID of the new action.
- -sort_order (optional)
- The number which this action should be in the sort ordering sequence. Leave blank to add action at the end. If you provide a sort_order number which already exists, existing actions are pushed down one number.
- -short_name (optional)
- Short name of the action for use in source code. Should be on Tcl variable syntax.
- -pretty_name (required)
- Human readable name of the action for use in UI.
- -pretty_past_tense (optional)
- Past tense of pretty name
- -edit_fields (optional)
- A space-separated list of the names of form fields which should be opened for editing when this action is carried out.
- -assigned_role (optional)
- The short_name of an assigned role. Users in this role are expected (obliged) to take the action.
- -allowed_roles (optional)
- A list of role short_names or IDs. Users in these roles are allowed to take the action.
- -privileges (optional)
- Users with these privileges on the object treated by the workflow (i.e. a bug in the Bug Tracker) will be allowed to take this action.
- -callbacks (optional)
- List of names of service contract implementations of callbacks for the action in impl_owner_name.impl_name format.
- -always_enabled_p (optional, defaults to
"f"
)- -initial_action_p (optional)
- Deprecated. Use this switch to indicate that this is the initial action that will fire whenever a case of the workflow is created. The initial action is used to determine the initial state of the worklow as well as any procedures that should be executed when the case created.
- -trigger_type (optional, defaults to
"user"
)- user, auto, message, time, init, workflow, parallel, dynamic.
- -parent_action (optional)
- Short_name of the action's parent action.
- -description (optional)
- -description_mime_type (optional)
- -timeout_seconds (optional)
- If zero, the action will automatically fire whenever it becomes enabled. If greater than zero, the action will automatically fire x number of seconds after the action is enabled. If empty, will never fire automatically.
- -internal (optional, boolean)
- Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do.
- Returns:
- The id of the created action
- Author:
- Peter Marklund
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::pretty_name_unique_p (public)
workflow::action::pretty_name_unique_p -workflow_id workflow_id \ -pretty_name pretty_name [ -parent_action_id parent_action_id ] \ [ -action_id action_id ]
Check if suggested pretty_name is unique.
- Switches:
- -workflow_id (required)
- -pretty_name (required)
- -parent_action_id (optional)
- -action_id (optional)
- Returns:
- 1 if unique, 0 if not unique.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::refresh_request_cache (private)
workflow::action::refresh_request_cache workflow_id
Initializes the cached array with information about actions for a certain workflow so that it can be reused within one request.
- Parameters:
- workflow_id (required)
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
workflow::action::update_sort_order (private)
workflow::action::update_sort_order -workflow_id workflow_id \ -sort_order sort_order
Increase the sort_order of other actions, if the new sort_order is already taken.
- Switches:
- -workflow_id (required)
- -sort_order (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
Content File Source
ad_library { Procedures in the workflow::action namespace. @creation-date 9 January 2003 @author Lars Pind (lars@collaboraid.biz) @author Peter Marklund (peter@collaboraid.biz) @cvs-id $Id: action-procs.tcl,v 1.44 2022/09/28 09:12:55 gustafn Exp $ } namespace eval workflow::action {} namespace eval workflow:::action::fsm {} ##### # # workflow::action namespace # ##### d_proc -public workflow::action::new { {-workflow_id:required} {-action_id {}} {-sort_order {}} {-short_name {}} {-pretty_name:required} {-pretty_past_tense {}} {-edit_fields {}} {-assigned_role {}} {-allowed_roles {}} {-privileges {}} {-callbacks {}} {-always_enabled_p f} -initial_action_p {-trigger_type user} {-parent_action {}} {-description {}} {-description_mime_type {}} {-timeout_seconds {}} {-internal:boolean} } { This procedure is normally not invoked from application code. Instead a procedure for a certain workflow implementation, such as for example workflow::action::fsm::new (for Finite State Machine workflows), is used. @param workflow_id The id of the FSM workflow to add the action to @param action_id Optionally specify the ID of the new action. @param sort_order The number which this action should be in the sort ordering sequence. Leave blank to add action at the end. If you provide a sort_order number which already exists, existing actions are pushed down one number. @param short_name Short name of the action for use in source code. Should be on Tcl variable syntax. @param pretty_name Human readable name of the action for use in UI. @param pretty_past_tense Past tense of pretty name @param edit_fields A space-separated list of the names of form fields which should be opened for editing when this action is carried out. @param assigned_role The short_name of an assigned role. Users in this role are expected (obliged) to take the action. @param allowed_roles A list of role short_names or IDs. Users in these roles are allowed to take the action. @param privileges Users with these privileges on the object treated by the workflow (i.e. a bug in the Bug Tracker) will be allowed to take this action. @param callbacks List of names of service contract implementations of callbacks for the action in impl_owner_name.impl_name format. @param trigger_type user, auto, message, time, init, workflow, parallel, dynamic. @param parent_action Short_name of the action's parent action. @param initial_action_p Deprecated. Use this switch to indicate that this is the initial action that will fire whenever a case of the workflow is created. The initial action is used to determine the initial state of the worklow as well as any procedures that should be executed when the case created. @param timeout_seconds If zero, the action will automatically fire whenever it becomes enabled. If greater than zero, the action will automatically fire x number of seconds after the action is enabled. If empty, will never fire automatically. @param internal Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do. @return The id of the created action @see workflow::action::edit @see workflow::action::fsm::edit @see workflow::definition_changed_handler @author Peter Marklund } { # Wrapper for workflow::action::edit array set row [list] foreach col { initial_action_p sort_order short_name pretty_name pretty_past_tense edit_fields allowed_roles assigned_role privileges callbacks always_enabled_p description description_mime_type timeout_seconds trigger_type parent_action } { if { [info exists $col] } { set row($col) [set $col] } } set action_id [workflow::action::edit \ -operation "insert" \ -action_id $action_id \ -workflow_id $workflow_id \ -array row] return $action_id } d_proc -public workflow::action::edit { {-operation "update"} {-action_id {}} {-workflow_id {}} {-array {}} {-internal:boolean} {-no_complain:boolean} {-handlers { roles "workflow::role" actions "workflow::action" }} } { Edit an action. Attributes of the array: <ul> <li>short_name <li>pretty_name <li>pretty_past_tense <li>edit_fields <li>description <li>description_mime_type <li>sort_order <li>always_enabled_p <li>assigned_role <li>timeout_seconds <li>trigger_type <li>parent_action <li>parent_action_id <li>privileges <li>allowed_roles <li>callbacks <li>child_actions </ul> Deprecated but still supported: <ul> <li>initial_action_p </ul> @param operation insert, update, delete @param action_id For update/delete: The action to update or delete. For insert: Optionally specify a pre-generated action_id for the action. @param workflow_id For update/delete: Optionally specify the workflow_id. If not specified, we will execute a query to find it. For insert: The workflow_id of the new action. @param array For insert/update: Name of an array in the caller's namespace with attributes to insert/update. @param internal Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do. @param no_complain Silently ignore extra attributes that we don't know how to handle. @return action_id @author Lars Pind (lars@collaboraid.biz) @see workflow::action::new } { switch $operation { update - delete { if { $action_id eq "" } { error "You must specify the action_id of the action to $operation." } } insert {} default { error "Illegal operation '$operation'" } } switch $operation { insert - update { upvar 1 $array row if { ![array exists row] } { error "Array $array does not exist or is not an array" } foreach name [array names row] { set missing_elm($name) 1 } } } switch $operation { insert { if { $workflow_id eq "" } { error "You must supply workflow_id" } # Default sort_order if { (![info exists row(sort_order)] || $row(sort_order) eq "") } { set row(sort_order) [workflow::default_sort_order \ -workflow_id $workflow_id \ -table_name "workflow_actions"] } # Default short_name on insert if { ![info exists row(short_name)] } { set row(short_name) {} } } update - delete { if { $workflow_id eq "" } { set workflow_id [workflow::action::get_element \ -action_id $action_id \ -element workflow_id] } } } # Parse column values switch $operation { insert - update { # Special-case: array entry parent_action (takes short_name) and parent_action_id (takes action_id) -- # DB column is parent_action_id (takes action_id_id) if { [info exists row(parent_action)] } { if { [info exists row(parent_action_id)] } { error "You cannot supply both parent_action ($row(parent_action)) (takes short_name) and parent_action_id ($row(parent_action_id)) (takes action_id)" } if { $row(parent_action) ne "" } { set row(parent_action_id) [workflow::action::get_id \ -workflow_id $workflow_id \ -short_name $row(parent_action)] } unset row(parent_action) unset missing_elm(parent_action) } # Record if this is an initial action (deprecated) if { [info exists row(initial_action_p)] } { if { [info exists row(trigger_type)] && $row(trigger_type) ne "user" } { error "You can't specify both initial_action_p (which is deprecated) and trigger_type (which has replaced it) at the same time. Stick to trigger_type." } if { [string is true -strict $row(initial_action_p)] } { set row(trigger_type) "init" } unset row(initial_action_p) unset missing_elm(initial_action_p) } set update_clauses [list] set insert_names [list] set insert_values [list] # Handle columns in the workflow_actions table foreach attr { short_name pretty_name pretty_past_tense edit_fields description description_mime_type sort_order always_enabled_p assigned_role timeout_seconds trigger_type parent_action_id } { if { [info exists row($attr)] } { set varname attr_$attr # Convert the Tcl value to something we can use in the query switch $attr { short_name { if { (![info exists row(pretty_name)] || $row(pretty_name) eq "") } { if { $row(short_name) eq "" } { error "You cannot edit with an empty short_name without also setting pretty_name" } else { set row(pretty_name) {} } } set $varname [workflow::action::generate_short_name \ -workflow_id $workflow_id \ -pretty_name $row(pretty_name) \ -short_name $row(short_name) \ -action_id $action_id] } always_enabled_p { set $varname [db_boolean [string is true -strict $row($attr)]] } assigned_role { if { $row($attr) eq "" } { set $varname "" } else { # Get role_id by short_name set $varname [workflow::role::get_id \ -workflow_id $workflow_id \ -short_name $row($attr)] } } default { set $varname $row($attr) } } # Add the column to the insert/update statement switch $attr { timeout_seconds { lappend update_clauses "[db_map update_timeout_seconds_name] = [db_map update_timeout_seconds_value]" lappend insert_names [db_map update_timeout_seconds_name] lappend insert_values [db_map update_timeout_seconds_value] } default { lappend update_clauses "$attr = :$varname" lappend insert_names $attr lappend insert_values :$varname } } if { [info exists missing_elm($attr)] } { unset missing_elm($attr) } } } } } db_transaction { # Sort_order switch $operation { insert - update { if { [info exists row(sort_order)] } { workflow::action::update_sort_order \ -workflow_id $workflow_id \ -sort_order $row(sort_order) } } } # Do the insert/update/delete switch $operation { insert { if { $action_id eq "" } { set action_id [db_nextval "workflow_actions_seq"] } lappend insert_names action_id lappend insert_values :action_id lappend insert_names workflow_id lappend insert_values :workflow_id db_dml insert_action " insert into workflow_actions ([join $insert_names ", "]) values ([join $insert_values ", "]) " } update { if { [llength $update_clauses] > 0 } { db_dml update_action " update workflow_actions set [join $update_clauses ", "] where action_id = :action_id " } } delete { db_dml delete_action { delete from workflow_actions where action_id = :action_id } } } # Auxiliary rows switch $operation { insert - update { # Record which roles are allowed to take action if { [info exists row(allowed_roles)] } { db_dml delete_allowed_roles { delete from workflow_action_allowed_roles where action_id = :action_id } foreach allowed_role $row(allowed_roles) { db_dml insert_allowed_role {} } unset missing_elm(allowed_roles) } # Record which privileges enable the action if { [info exists row(privileges)] } { db_dml delete_privileges { delete from workflow_action_privileges where action_id = :action_id } foreach privilege $row(privileges) { db_dml insert_privilege {} } unset missing_elm(privileges) } # Callbacks if { [info exists row(callbacks)] } { db_dml delete_callbacks { delete from workflow_action_callbacks where action_id = :action_id } foreach callback_name $row(callbacks) { workflow::action::callback_insert \ -action_id $action_id \ -name $callback_name } unset missing_elm(callbacks) } # Child actions foreach { type namespace } $handlers { # type is 'roles', 'actions', 'states', etc. if { [info exists row(child_${type})] } { # First, delete existing objects foreach existing_action_id [${namespace}::get_ids \ -workflow_id $workflow_id \ -parent_action_id $action_id] { # LARS: Ugly as hell with the string range to cut from 'actions' to 'action_id' ${namespace}::edit -[string range $type 0 end-1]_id $existing_action_id } foreach { child_short_name child_spec } $row(child_${type}) { array unset child array set child $child_spec set child(short_name) $child_short_name set child(parent_action_id) $action_id # string trim everything foreach key [array names child] { set child($key) [string trim $child($key)] } ${namespace}::edit \ -internal \ -handlers $handlers \ -operation "insert" \ -workflow_id $workflow_id \ -array child } unset missing_elm(child_${type}) } } # Check that there are no unknown attributes if { [array size missing_elm] > 0 && !$no_complain_p } { error "Trying to set illegal action attributes: [join [array names missing_elm] ", "]" } } } if { !$internal_p } { workflow::definition_changed_handler -workflow_id $workflow_id } } return $action_id } d_proc -public workflow::action::delete { {-action_id:required} } { Delete action with given id. @author Peter Marklund } { workflow::action::edit -operation "delete" -action_id $action_id } d_proc -public workflow::action::get_assigned_role { {-action_id:required} } { Return the assigned role of the given action @param action_id The action_id of the action. @return role_id of the assigned role. } { return [get_from_request_cache $action_id "assigned_role_id"] } d_proc -public workflow::action::get_allowed_roles { {-action_id:required} } { Return the allowed roles of the given action @param action_id The action_id of the action. @return List of role_id of the allowed roles } { return [get_from_request_cache $action_id "allowed_role_ids"] } d_proc -public workflow::action::get_privileges { {-action_id:required} } { Return the assigned role of the given action @param action_id The action_id of the action. @return List of privileges that give permission to do this action } { return [get_from_request_cache $action_id "privileges"] } d_proc -public workflow::action::get_id { {-workflow_id:required} {-short_name:required} } { Return the action_id of the action with the given short_name in the given workflow. @param workflow_id The ID of the workflow @param short_name The short_name of the action @return action_id of the desired action, or the empty string if it can't be found. } { workflow::action::refresh_request_cache $workflow_id global __workflow_action_data,${workflow_id} foreach action_id [set __workflow_action_data,${workflow_id}(action_ids)] { array set one_action [set __workflow_action_data,${workflow_id}($action_id)] if {$one_action(short_name) eq $short_name} { return $action_id } } error "workflow::action::get_id: Action with short_name $short_name not found for workflow $workflow_id" } d_proc -public workflow::action::get_workflow_id { {-action_id:required} } { Lookup the workflow_id of a certain action_id. @author Peter Marklund } { return [util_memoize \ [list workflow::action::get_workflow_id_not_cached -action_id $action_id]] } d_proc -private workflow::action::get_workflow_id_not_cached { {-action_id:required} } { This is a proc that should only be used internally by the workflow API, applications should use workflow::action::get_workflow_id instead. @author Peter Marklund } { return [db_string select_workflow_id {}] } d_proc -public workflow::action::get { {-action_id:required} {-array:required} } { Return information about an action with a given id. @author Peter Marklund @author Lars Pind (lars@collaboraid.biz) @return The array will contain the following entries: workflow_id, sort_order, short_name, pretty_name, pretty_past_tense, assigned_role (short_name), assigned_role_id, always_enabled_p, trigger_type, parent_action, parent_action_id, description, description_mime_type values for an action. @see workflow::action::get_all_info @see workflow::action::get_all_info_not_cached } { # Select the info into the upvar'ed Tcl Array upvar $array row array set row [get_from_request_cache $action_id] } d_proc -public workflow::action::get_element { {-action_id {}} {-one_id {}} {-element:required} } { Return a single element from the information about a action. @param action_id The ID of the action @param one_id Same as action_id, just used for consistency across roles/actions/states. @param element The element you want @return The element you asked for @author Lars Pind (lars@collaboraid.biz) } { if { $action_id eq "" } { if { $one_id eq "" } { error "You must supply either action_id or one_id" } set action_id $one_id } else { if { $one_id ne "" } { error "You can only supply either action_id or one_id" } } get -action_id $action_id -array row return $row($element) } d_proc -public workflow::action::callback_insert { {-action_id:required} {-name:required} {-sort_order {}} } { Add a side-effect to an action. @param action_id The ID of the action. @param name Name of service contract implementation, in the form (impl_owner_name).(impl_name), for example, bug-tracker.CaptureResolutionCode @param sort_order The sort_order for the rule. Leave blank to add to the end of the list @author Lars Pind (lars@collaboraid.biz) } { db_transaction { # Get the impl_id set acs_sc_impl_id [workflow::service_contract::get_impl_id -name $name] # Get the sort order if { (![info exists sort_order] || $sort_order eq "") } { set sort_order [db_string select_sort_order {}] } # Insert the callback db_dml insert_callback {} } set workflow_id [workflow::action::get_workflow_id -action_id $action_id] workflow::action::flush_cache -workflow_id $workflow_id return $acs_sc_impl_id } d_proc -private workflow::action::get_callbacks { {-action_id:required} {-contract_name:required} } { Return a list of implementation names for the callbacks of a given workflow action. @see workflow::case::role::get_callbacks @author Peter Marklund } { array set callbacks [get_from_request_cache $action_id callbacks_array] set callback_ids [get_from_request_cache $action_id callback_ids] # Loop over the callbacks and return the impl_names of those with a matching # contract name set impl_names [list] foreach callback_id $callback_ids { array set one_callback $callbacks($callback_id) if {$one_callback(contract_name) eq $contract_name} { lappend impl_names $one_callback(impl_name) } } return $impl_names } d_proc -private workflow::action::update_sort_order { {-workflow_id:required} {-sort_order:required} } { Increase the sort_order of other actions, if the new sort_order is already taken. } { set sort_order_taken_p [db_string select_sort_order_p {}] if { $sort_order_taken_p } { db_dml update_sort_order {} } } d_proc -public workflow::action::get_existing_short_names { {-workflow_id:required} {-ignore_action_id {}} } { Returns a list of existing action short_names in this workflow. Useful when you're trying to ensure a short_name is unique, or construct a new short_name that is guaranteed to be unique. @param ignore_action_id If specified, the short_name for the given action will not be included in the result set. } { set result [list] foreach action_id [workflow::get_actions -all -workflow_id $workflow_id] { if { $ignore_action_id eq "" || $ignore_action_id ne $action_id } { lappend result [workflow::action::get_element -action_id $action_id -element short_name] } } return $result } d_proc -public workflow::action::generate_short_name { {-workflow_id:required} {-pretty_name:required} {-short_name {}} {-action_id {}} } { Generate a unique short_name from pretty_name. @param action_id If you pass in this, we will allow that action's short_name to be reused. } { set existing_short_names [workflow::action::get_existing_short_names \ -workflow_id $workflow_id \ -ignore_action_id $action_id] if { $short_name eq "" } { if { $pretty_name eq "" } { error "Cannot have empty pretty_name when short_name is empty" } set short_name [util_text_to_url \ -replacement "_" \ -existing_urls $existing_short_names \ -text $pretty_name] } else { # Make lowercase, remove illegal characters set short_name [string tolower $short_name] regsub -all {[- ]} $short_name {_} short_name regsub -all {[^a-zA-Z_0-9]} $short_name {} short_name if {$short_name in $existing_short_names} { error "Action with short_name '$short_name' already exists in this workflow." } } return $short_name } d_proc -public workflow::action::get_ids { {-all:boolean} {-workflow_id:required} {-parent_action_id {}} } { Get the action_id's of all the actions in the workflow. @param workflow_id The ID of the workflow @return list of action_id's. @author Lars Pind (lars@collaboraid.biz) } { # Use cached data about actions array set action_data [workflow::action::get_all_info -workflow_id $workflow_id] if { $all_p } { return $action_data(action_ids) } set action_ids [list] foreach action_id $action_data(action_ids) { if { [workflow::action::get_element \ -action_id $action_id \ -element parent_action_id] == $parent_action_id } { lappend action_ids $action_id } } return $action_ids } d_proc -public workflow::action::get_options { {-all:boolean} {-workflow_id:required} {-parent_action_id {}} } { Get an options list of actions for use with form builder. } { set result [list] foreach action_id [workflow::get_actions \ -all=$all_p \ -workflow_id $workflow_id \ -parent_action_id $parent_action_id] { workflow::action::get -action_id $action_id -array action lappend result [list $action(pretty_name) $action_id] } return $result } d_proc -public workflow::action::pretty_name_unique_p { -workflow_id:required -pretty_name:required {-parent_action_id {}} {-action_id {}} } { Check if suggested pretty_name is unique. @return 1 if unique, 0 if not unique. } { set exists_p [db_string name_exists { select count(*) from workflow_actions where workflow_id = :workflow_id and pretty_name = :pretty_name and (:parent_action_id is null or parent_action_id = :parent_action_id) and (:action_id is null or action_id != :action_id) }] return [expr {!$exists_p}] } ###################################################################### # # workflow::action::fsm # ###################################################################### d_proc -public workflow::action::fsm::new { {-workflow_id:required} {-action_id {}} {-sort_order {}} {-short_name {}} {-pretty_name:required} {-pretty_past_tense {}} {-edit_fields {}} {-allowed_roles {}} {-assigned_role {}} {-privileges {}} {-enabled_states {}} {-assigned_states {}} {-enabled_state_ids {}} {-assigned_state_ids {}} {-new_state {}} {-new_state_id {}} {-callbacks {}} -initial_action_p {-always_enabled_p f} {-trigger_type user} {-parent_action {}} {-description {}} {-description_mime_type {}} {-timeout_seconds {}} } { Add an action to a certain FSM (Finite State Machine) workflow. This procedure invokes the generic workflow::action::new procedures and does additional inserts for FSM specific information. See the parameter documentation for the proc workflow::action::new. @return the new action_id. @see workflow::action::fsm::edit @author Peter Marklund } { # Wrapper for workflow::action::edit array set row [list] foreach col { initial_action_p sort_order short_name pretty_name pretty_past_tense edit_fields allowed_roles assigned_role privileges callbacks always_enabled_p description description_mime_type timeout_seconds trigger_type parent_action } { if { [info exists $col] } { set row($col) [set $col] } } foreach elm { new_state new_state_id enabled_states assigned_states enabled_state_ids assigned_state_ids } { if { ([info exists $elm] && $$elm ne "") } { set row($elm) [set $elm] } } set action_id [workflow::action::fsm::edit \ -operation "insert" \ -action_id $action_id \ -workflow_id $workflow_id \ -array row] return $action_id } d_proc -public workflow::action::fsm::edit { {-operation "update"} {-action_id {}} {-workflow_id {}} {-array {}} {-internal:boolean} {-handlers { roles "workflow::role" actions "workflow::action::fsm" states "workflow::state::fsm" }} } { Edit an action. Attributes: <ul> <li>new_state_id <li>enabled_states <li>enabled_state_ids <li>enabled_actions <li>enabled_action_ids <li>child_states </ul> @param operation insert, update, delete @param action_id For update/delete: The action to update or delete. For insert: Optionally specify a pre-generated action_id for the action. @param workflow_id For update/delete: Optionally specify the workflow_id. If not specified, we will execute a query to find it. For insert: The workflow_id of the new action. @param array For insert/update: Name of an array in the caller's namespace with attributes to insert/update. @param internal Set this flag if you're calling this proc from within the corresponding proc for a particular workflow model. Will cause this proc to not flush the cache or call workflow::definition_changed_handler, which the caller must then do. @return action_id @see workflow::action::edit } { switch $operation { update - delete { if { $action_id eq "" } { error "You must specify the action_id of the action to $operation." } } insert {} default { error "Illegal operation '$operation'" } } switch $operation { insert - update { upvar 1 $array org_row if { ![array exists org_row] } { error "Array $array does not exist or is not an array" } array set row [array get org_row] } } switch $operation { insert { if { $workflow_id eq "" } { error "You must supply workflow_id" } } update - delete { if { $workflow_id eq "" } { set workflow_id [workflow::action::get_element \ -action_id $action_id \ -element workflow_id] } } } # Parse column values switch $operation { insert - update { # Special-case: array entry new_state (short_name) and new_state_id (state_id) -- DB column is new_state (state_id) if { [info exists row(new_state)] } { if { [info exists row(new_state_id)] } { error "You cannot supply both new_state (takes short_name) and new_state_id (takes state_id)" } if { $row(new_state) ne "" } { set row(new_state_id) [workflow::state::fsm::get_id \ -workflow_id $workflow_id \ -short_name $row(new_state)] } unset row(new_state) } set update_clauses [list] set insert_names [list] set insert_values [list] # Handle columns in the workflow_fsm_actions table foreach attr { new_state_id } { if { [info exists row($attr)] } { set varname attr_$attr # Convert the Tcl value to something we can use in the query switch $attr { new_state_id { set varname attr_new_state set $varname $row($attr) unset row($attr) set attr new_state } default { set $varname $row($attr) } } # Add the column to the insert/update statement switch $attr { default { lappend update_clauses "$attr = :$varname" lappend insert_names $attr lappend insert_values :$varname } } if { [info exists row($attr)] } { unset row($attr) } } } if { [info exists row(enabled_states)] } { if { [info exists row(enabled_state_ids)] } { error "You cannot supply both enabled_states and enabled_state_ids" } set row(enabled_state_ids) [list] foreach state_short_name $row(enabled_states) { lappend row(enabled_state_ids) [workflow::state::fsm::get_id \ -workflow_id $workflow_id \ -short_name $state_short_name] } unset row(enabled_states) } if { [info exists row(assigned_states)] } { if { [info exists row(assigned_state_ids)] } { error "You cannot supply both assigned_states and assigned_state_ids" } set row(assigned_state_ids) [list] foreach state_short_name $row(assigned_states) { lappend row(assigned_state_ids) [workflow::state::fsm::get_id \ -workflow_id $workflow_id \ -short_name $state_short_name] } unset row(assigned_states) } # Handle auxiliary rows array set aux [list] foreach attr { enabled_state_ids assigned_state_ids } { if { [info exists row($attr)] } { set aux($attr) $row($attr) unset row($attr) } } } } db_transaction { # Base row set action_id [workflow::action::edit \ -internal \ -handlers $handlers \ -operation $operation \ -action_id $action_id \ -workflow_id $workflow_id \ -array row] # Verify insert/update switch $operation { insert - update { set row_exists_p [db_string row_exists_p { select count(*) from workflow_fsm_actions where action_id = :action_id }] if { $row_exists_p } { set operation "update" } else { set operation "insert" } } } # FSM action row switch $operation { insert { lappend insert_names action_id lappend insert_values :action_id db_dml insert_action " insert into workflow_fsm_actions ([join $insert_names ", "]) values ([join $insert_values ", "]) " } update { if { [llength $update_clauses] > 0 } { db_dml update_action " update workflow_fsm_actions set [join $update_clauses ", "] where action_id = :action_id " } } delete { # Handled through cascading delete } } # Auxiliary rows switch $operation { insert - update { # Record in which states the action is enabled but not assigned if { [info exists aux(enabled_state_ids)] } { set assigned_p "f" db_dml delete_enabled_states {} foreach enabled_state_id $aux(enabled_state_ids) { db_dml insert_enabled_state {} } unset aux(enabled_state_ids) } # Record where the action is both enabled and assigned if { [info exists aux(assigned_state_ids)] } { set assigned_p "t" db_dml delete_enabled_states {} foreach enabled_state_id $aux(assigned_state_ids) { db_dml insert_enabled_state {} } unset aux(assigned_state_ids) } } } if { !$internal_p } { workflow::definition_changed_handler -workflow_id $workflow_id } } return $action_id } d_proc -public workflow::action::fsm::delete { {-action_id:required} } { Delete FSM action with given id. @author Peter Marklund } { workflow::action::fsm::edit -operation delete -action_id $action_id } d_proc -public workflow::action::fsm::get_new_state { {-action_id:required} } { Return the ID of the new state for an action @param action_id The action_id of the action. @return The ID of the new state after executing this action, or the empty string if the action doesn't change the state. } { return [workflow::action::get_from_request_cache $action_id "new_state_id"] } d_proc -public workflow::action::fsm::get { {-action_id:required} {-array:required} } { Return information about an action with a given id, including FSM-related info: enabled_states, enabled_state_ids, assigned_states, assigned_state_ids, new_state, new_state_id. @author Peter Marklund @author Lars Pind (lars@collaboraid.biz) } { # Select the info into the upvar'ed Tcl Array upvar $array row workflow::action::get -action_id $action_id -array row } d_proc -public workflow::action::fsm::get_element { {-action_id {}} {-one_id {}} {-element:required} } { Return element from information about an action with a given id, including FSM-related info such as 'enabled_in_states', and 'new_state'. Return a single element from the information about a action. @param action_id The ID of the action @param one_id Same as action_id, just used for consistency across roles/actions/states. @param element The element you want @return The element you asked for @author Peter Marklund @author Lars Pind (lars@collaboraid.biz) } { if { $action_id eq "" } { if { $one_id eq "" } { error "You must supply either action_id or one_id" } set action_id $one_id } else { if { $one_id ne "" } { error "You can only supply either action_id or one_id" } } workflow::action::fsm::get -action_id $action_id -array row return $row($element) } d_proc -public workflow::action::fsm::set_enabled_in_state { -action_id:required -state_id:required -enabled:boolean -assigned:boolean {-workflow_id {}} } { Edit the enabled state of an action @param workflow_id Optionally provide the workflow_id. If not, this will be gotten from a query. @author Lars Pind (lars@collaboraid.biz) } { if { $workflow_id eq "" } { set workflow_id [workflow::action::get_element \ -action_id $action_id \ -element workflow_id] } set currently_assigned_p [db_string enabled_p { select assigned_p from workflow_fsm_action_en_in_st where action_id = :action_id and state_id = :state_id } -default {}] set currently_enabled_p [expr {$currently_assigned_p ne ""}] set currently_assigned_p [string is true -strict $currently_assigned_p] set db_assigned_p [db_boolean $assigned_p] if { $currently_enabled_p != $enabled_p} { if { $enabled_p } { db_dml enabled { insert into workflow_fsm_action_en_in_st (action_id, state_id, assigned_p) values (:action_id, :state_id, :db_assigned_p) } } else { db_dml disable { delete from workflow_fsm_action_en_in_st where action_id = :action_id and state_id = :state_id } } } elseif { $currently_assigned_p != $assigned_p } { db_dml update_assigned_p { update workflow_fsm_action_en_in_st set assigned_p = :db_assigned_p where action_id = :action_id and state_id = :state_id } } workflow::definition_changed_handler -workflow_id $workflow_id } ##### # Private procs ##### d_proc -private workflow::action::fsm::parse_spec { {-workflow_id:required} {-short_name:required} {-spec:required} {-parent_action_id {}} } { Parse the spec for an individual action definition. @param workflow_id The id of the workflow to delete. @param short_name The short_name of the action @param spec The action spec @author Lars Pind (lars@collaboraid.biz) } { # Initialize array with default values array set action { pretty_past_tense {} edit_fields {} allowed_roles {} assigned_role {} privileges {} always_enabled_p f enabled_states {} assigned_states {} new_state {} trigger_type user callbacks {} } # Get the info from the spec foreach { key value } $spec { set action($key) [string trim $value] } set action(short_name) $short_name set action(parent_action_id) $parent_action_id # Create the action set action_id [workflow::action::fsm::edit \ -operation "insert" \ -workflow_id $workflow_id \ -array action] } d_proc -private workflow::action::fsm::generate_spec { {-action_id {}} {-one_id {}} {-handlers {}} } { Generate the spec for an individual action definition. @param action_id The id of the action to generate spec for. @param one_id Same as action_id, just used for consistency across roles/actions/states. @return spec The actions spec @author Lars Pind (lars@collaboraid.biz) } { if { $action_id eq "" } { if { $one_id eq "" } { error "You must supply either action_id or one_id" } set action_id $one_id } else { if { $one_id ne "" } { error "You can only supply either action_id or one_id" } } get -action_id $action_id -array row # Get rid of elements that shouldn't go into the spec array unset row short_name array unset row action_id array unset row workflow_id array unset row sort_order array unset row assigned_role_id array unset row new_state_id array unset row callbacks_array array unset row callback_ids array unset row allowed_roles_array array unset row allowed_role_ids array unset row enabled_state_ids array unset row assigned_state_ids array unset row parent_action array unset row parent_action_id foreach { type namespace } $handlers { # type is 'roles', 'actions', 'states', etc. # LARS: Ugly as hell with the string range to cut from 'actions' to 'action_ids' if { [info exists row(child_[string range $type 0 end-1]_ids)] } { set row(child_${type}) [list] foreach child_id $row(child_[string range $type 0 end-1]_ids) { set child_short_name [${namespace}::get_element \ -one_id $child_id \ -element short_name] set child_spec [${namespace}::generate_spec -one_id $child_id -handlers $handlers] lappend row(child_${type}) $child_short_name $child_spec } unset row(child_[string range $type 0 end-1]_ids) } } if { (![info exists row(description)] || $row(description) eq "") } { array unset row description_mime_type } # Get rid of a few defaults array set defaults { trigger_type user always_enabled_p f } set spec [list] foreach name [lsort [array names row]] { if { $row($name) ne "" && !([info exists defaults($name)] && $defaults($name) eq $row($name)) } { lappend spec $name $row($name) } } return $spec } d_proc -private workflow::action::flush_cache { {-workflow_id:required} } { Flush all caches related to actions for the given workflow_id. Used internally by the workflow API only. @author Peter Marklund } { # Flush the request cache global __workflow_action_data,${workflow_id} if { [info exists __workflow_action_data,${workflow_id}] } { foreach action_id [set __workflow_action_data,${workflow_id}(action_ids)] { global __workflow_one_action,$action_id if { [info exists __workflow_one_action,$action_id] } { unset __workflow_one_action,$action_id } } unset __workflow_action_data,${workflow_id} } # Flush the thread global cache util_memoize_flush [list workflow::action::get_all_info_not_cached -workflow_id $workflow_id] } ad_proc -private workflow::action::refresh_request_cache { workflow_id } { Initializes the cached array with information about actions for a certain workflow so that it can be reused within one request. @author Peter Marklund } { global __workflow_action_data,${workflow_id} if { ![info exists __workflow_action_data,${workflow_id}] } { array set __workflow_action_data,${workflow_id} [workflow::action::get_all_info -workflow_id $workflow_id] } } d_proc -private workflow::action::get_from_request_cache { action_id {element ""} } { This provides some abstraction for the Workflow API cache and also some optimization - we only convert lists to arrays once per request. Should be used internally by the workflow API only. @author Peter Marklund } { # Get the cache with all actions set workflow_id [workflow::action::get_workflow_id -action_id $action_id] refresh_request_cache $workflow_id global __workflow_action_data,${workflow_id} array set workflow_data [workflow::action::get_all_info -workflow_id $workflow_id] # A single action set action_var_name __workflow_one_action,${action_id} global $action_var_name if { ![info exists $action_var_name] } { array set $action_var_name [set __workflow_action_data,${workflow_id}($action_id)] } if { $element eq "" } { return [array get $action_var_name] } else { return [set "${action_var_name}($element)"] } } d_proc -private workflow::action::get_all_info { {-workflow_id:required} } { This proc is for internal use in the workflow API only. Returns all information related to actions for a certain workflow instance. Uses util_memoize to cache values. @see workflow::action::get_all_info_not_cached @author Peter Marklund } { return [util_memoize [list workflow::action::get_all_info_not_cached \ -workflow_id $workflow_id] [workflow::cache_timeout]] } d_proc -private workflow::action::get_all_info_not_cached { {-workflow_id:required} } { This proc is for internal use in the workflow API only and should not be invoked directly from application code. Returns all information related to actions for a certain workflow instance. Goes to the database on every invocation and should be used together with util_memoize. @author Peter Marklund } { # We avoid nested db queries in this proc to enhance performance # This is where we will ultimately deliver the results array set action_data {} # This will be a list of all action_id's set action_ids [list] # Get basic action info db_foreach action_info {} -column_array action_row { # Cache the mapping action_id -> workflow_id util_memoize_seed \ [list workflow::action::get_workflow_id_not_cached -action_id $action_row(action_id)] \ $workflow_id set action_id $action_row(action_id) array set action_array_${action_id} { callbacks_array {} callbacks {} callback_ids {} allowed_roles {} allowed_role_ids {} allowed_roles_array {} privileges {} assigned_states {} assigned_state_ids {} enabled_states {} enabled_state_ids {} child_states {} child_state_ids {} } array set action_array_${action_id} [array get action_row] if { $action_row(parent_action_id) ne "" } { lappend action_array_$action_row(parent_action_id)(child_action_ids) $action_id lappend action_array_$action_row(parent_action_id)(child_actions) $action_row(short_name) } lappend action_ids $action_id } foreach action_id $action_ids { if { ![info exists action_array_${action_id}(child_action_ids)] } { set action_array_${action_id}(child_action_ids) [list] set action_array_${action_id}(child_actios) [list] } } # Get child states foreach state_id [workflow::fsm::get_states -all -workflow_id $workflow_id] { workflow::state::fsm::get -state_id $state_id -array state_array if { $state_array(parent_action_id) ne "" } { lappend action_array_$state_array(parent_action_id)(child_state_ids) $state_id lappend action_array_$state_array(parent_action_id)(child_states) $state_array(short_name) } } # Build a separate array for all action callbacks of the workflow # Columns: impl_id, impl_name, impl_owner_name, contract_name, action_id db_foreach action_callbacks {} -column_array callback_row { set action_id $callback_row(action_id) lappend action_array_${action_id}(callbacks) \ "$callback_row(impl_owner_name).$callback_row(impl_name)" lappend action_array_${action_id}(callback_ids) $callback_row(impl_id) lappend action_array_${action_id}(callbacks_array) $callback_row(impl_id) [array get callback_row] } # Build an array for all allowed roles for all actions db_foreach action_allowed_roles {} -column_array allowed_role_row { set action_id $allowed_role_row(action_id) lappend action_array_${action_id}(allowed_roles) $allowed_role_row(short_name) lappend action_array_${action_id}(allowed_role_ids) $allowed_role_row(role_id) # The 'allowed_roles_array' entry is an array-list, keyed by role_id, with the value being # an array-list of the information returned by this call lappend action_array_${action_id}(allowed_roles_array) \ [list $allowed_role_row(role_id) [array get allowed_role_row]] } # Build an array of privileges for all actions db_foreach select_privileges {} { lappend action_array_${action_id}(privileges) $privilege } # Build arrays of enabled and assigned state short names for all actions db_foreach action_enabled_in_states {} { if {$assigned_p == "t"} { lappend action_array_${action_id}(assigned_states) $short_name lappend action_array_${action_id}(assigned_state_ids) $state_id } else { lappend action_array_${action_id}(enabled_states) $short_name lappend action_array_${action_id}(enabled_state_ids) $state_id } } # Move everything from the action_array_${action_id} arrays into the cacheo foreach action_id $action_ids { set action_data($action_id) [array get action_array_${action_id}] } set action_data(action_ids) $action_ids return [array get action_data] } d_proc -public workflow::action::fsm::get_ids { {-all:boolean} {-workflow_id:required} {-parent_action_id {}} } { Get the action_id's of all the actions in the workflow. @param workflow_id The ID of the workflow @return list of action_id's. @author Lars Pind (lars@collaboraid.biz) } { return [workflow::action::get_ids -all=$all_p -workflow_id $workflow_id -parent_action_id $parent_action_id] } # Local variables: # mode: tcl # tcl-indent-level: 4 # indent-tabs-mode: nil # End: