state-procs.tcl

Procedures in the workflow::fsm::state namespace and in its child namespaces.

Location:
packages/workflow/tcl/state-procs.tcl
Created:
8 January 2003
Authors:
Lars Pind <lars@collaboraid.biz>
Peter Marklund <peter@collaboraid.biz>
CVS Identification:
$Id: state-procs.tcl,v 1.25 2022/09/28 09:12:55 gustafn Exp $

Procedures in this file

Detailed information

workflow::state::flush_cache (private)

 workflow::state::flush_cache -workflow_id workflow_id

Flush all caches related to state information for the given workflow. Used internally by the workflow API only.

Switches:
-workflow_id (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::edit (public)

 workflow::state::fsm::edit [ -operation operation ] \
    [ -state_id state_id ] [ -workflow_id workflow_id ] \
    [ -array array ] [ -internal ] [ -no_complain ] \
    [ -handlers handlers ]

Edit a workflow state. Attributes of the array are:

  • short_name
  • pretty_name
  • sort_order
  • hide_fields
  • parent_action

Switches:
-operation (optional, defaults to "update")
insert, update, delete
-state_id (optional)
For update/delete: The state to update or delete. For insert: Optionally specify a pre-generated state_id for the state.
-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 state.
-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)
Returns:
state_id
Authors:
Peter Marklund
Lars Pind <lars@collaboraid.biz>
See Also:
  • workflow::state::new

Testcases:
No testcase defined.

workflow::state::fsm::generate_short_name (public)

 workflow::state::fsm::generate_short_name -workflow_id workflow_id \
    -pretty_name pretty_name [ -short_name short_name ] \
    [ -state_id state_id ]

Generate a unique short_name from pretty_name.

Switches:
-workflow_id (required)
-pretty_name (required)
-short_name (optional)
-state_id (optional)
If you pass in this, we will allow that state's short_name to be reused.

Testcases:
No testcase defined.

workflow::state::fsm::generate_spec (private)

 workflow::state::fsm::generate_spec [ -state_id state_id ] \
    [ -one_id one_id ] [ -handlers handlers ]

Generate the spec for an individual state definition.

Switches:
-state_id (optional)
The id of the state to generate spec for.
-one_id (optional)
Same as state_id, just used for consistency across roles/actions/states.
-handlers (optional)
Returns:
spec The states spec
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
No testcase defined.

workflow::state::fsm::generate_states_spec (private)

 workflow::state::fsm::generate_states_spec -workflow_id workflow_id

Generate the spec for the block containing the definition of all states for the workflow.

Switches:
-workflow_id (required)
The id of the workflow to get the states spec for
Returns:
The states spec
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
No testcase defined.

workflow::state::fsm::get (public)

 workflow::state::fsm::get -state_id state_id -array array

Return workflow_id, sort_order, short_name, and pretty_name for a certain FSM workflow state.

Switches:
-state_id (required)
-array (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::get_all_info (private)

 workflow::state::fsm::get_all_info -workflow_id workflow_id

This proc is for internal use in the workflow API only. Returns all information related to states for a certain workflow instance. Uses util_memoize to cache values.

Switches:
-workflow_id (required)
Author:
Peter Marklund
See Also:

Testcases:
No testcase defined.

workflow::state::fsm::get_all_info_not_cached (private)

 workflow::state::fsm::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 states 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

Testcases:
No testcase defined.

workflow::state::fsm::get_element (public)

 workflow::state::fsm::get_element [ -state_id state_id ] \
    [ -one_id one_id ] -element element

Return a single element from the information about a state.

Switches:
-state_id (optional)
The ID of the workflow
-one_id (optional)
Same as state_id, just used for consistency across roles/actions/states.
-element (required)
Returns:
The element you asked for
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
No testcase defined.

workflow::state::fsm::get_existing_short_names (public)

 workflow::state::fsm::get_existing_short_names \
    -workflow_id workflow_id [ -ignore_state_id ignore_state_id ]

Returns a list of existing state 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_state_id (optional)
If specified, the short_name for the given state will not be included in the result set.

Testcases:
No testcase defined.

workflow::state::fsm::get_id (public)

 workflow::state::fsm::get_id -workflow_id workflow_id \
    -short_name short_name

Return the id of the state with given short name

Switches:
-workflow_id (required)
The id of the workflow the state belongs to.
-short_name (required)
The name of the state to return the id for.
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::get_ids (private)

 workflow::state::fsm::get_ids [ -all ] -workflow_id workflow_id \
    [ -parent_action_id parent_action_id ]

Get the state_id's of all the states in the workflow.

Switches:
-all (optional, boolean)
-workflow_id (required)
The ID of the workflow
-parent_action_id (optional)
Returns:
list of state_id's.
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
No testcase defined.

workflow::state::fsm::get_workflow_id (public)

 workflow::state::fsm::get_workflow_id -state_id state_id

Lookup the workflow that the given state belongs to.

Switches:
-state_id (required)
Returns:
The id of the workflow the state belongs to.
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::get_workflow_id_not_cached (private)

 workflow::state::fsm::get_workflow_id_not_cached -state_id state_id

This proc is used internally by the workflow API only. Use the proc workflow::state::fsm::get_workflow_id instead.

Switches:
-state_id (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::new (public)

 workflow::state::fsm::new -workflow_id workflow_id [ -internal ] \
    [ -short_name short_name ] -pretty_name pretty_name \
    [ -hide_fields hide_fields ] [ -sort_order sort_order ] \
    [ -parent_action parent_action ]

Creates a new state for a certain FSM (Finite State Machine) workflow.

Switches:
-workflow_id (required)
The id of the FSM workflow to add the state to
-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.
-short_name (optional)
If you leave blank, the short_name will be generated from pretty_name.
-pretty_name (required)
-hide_fields (optional)
A space-separated list of the names of form fields which should be hidden when in this state, because they're irrelevant in a certain state.
-sort_order (optional)
The number which this state should be in the sort ordering sequence. Leave blank to add state at the end. If you provide a sort_order number which already exists, existing states are pushed down one number.
-parent_action (optional)
Which action with trigger_type 'workflow' does this state belong to.
Returns:
ID of new state.
Author:
Peter Marklund

Testcases:
No testcase defined.

workflow::state::fsm::parse_spec (private)

 workflow::state::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 state definition.

Switches:
-workflow_id (required)
The id of the workflow to delete.
-short_name (required)
The short_name of the state
-spec (required)
The state spec
-parent_action_id (optional)
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
No testcase defined.

workflow::state::fsm::pretty_name_unique_p (public)

 workflow::state::fsm::pretty_name_unique_p -workflow_id workflow_id \
    -pretty_name pretty_name [ -parent_action_id parent_action_id ] \
    [ -state_id state_id ]

Check if suggested pretty_name is unique.

Switches:
-workflow_id (required)
-pretty_name (required)
-parent_action_id (optional)
-state_id (optional)
Returns:
1 if unique, 0 if not unique.

Testcases:
No testcase defined.

workflow::state::fsm::update_sort_order (private)

 workflow::state::fsm::update_sort_order -workflow_id workflow_id \
    -sort_order sort_order

Increase the sort_order of other states, if the new sort_order is already taken.

Switches:
-workflow_id (required)
-sort_order (required)

Testcases:
No testcase defined.
[ show source ]