• 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

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>

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

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:

  • 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
Deprecated but still supported:
  • 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:

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

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:

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>

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>

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>

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.

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:

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>

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.

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:

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

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.

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>

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.

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.

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>

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)

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

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

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:

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.

Testcases:
No testcase defined.
[ show source ]