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 ]

Defined in packages/workflow/tcl/state-procs.tcl

Edit a workflow state. Attributes of the array are:

• short_name
• pretty_name
• sort_order
• hide_fields
• parent_action

Switches:

-operation

(defaults to "update") (optional)

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

(boolean) (optional)

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

(boolean) (optional)

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

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

Testcases:

No testcase defined.

Source code:

    switch $operation {
        update - delete {
            if { $state_id eq "" } {
                error "You must specify the state_id of the state 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_fsm_states"]
            }
            # Default short_name on insert
            if { ![info exists row(short_name)] } {
                set row(short_name) {}
            }
        }
        update {
            if { $workflow_id eq "" } {
                set workflow_id [workflow::state::fsm::get_element  -state_id $state_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 (takes short_name) and 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)
            }

            set update_clauses [list]
            set insert_names [list]
            set insert_values [list]

            # Handle columns in the workflow_fsm_states table
            foreach attr {
                short_name pretty_name hide_fields sort_order 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::state::fsm::generate_short_name  -workflow_id $workflow_id  -pretty_name $row(pretty_name)  -short_name $row(short_name)  -state_id $state_id]
                        }
                        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 missing_elm($attr)] } {
                        unset missing_elm($attr)
                    }
                }
            }

            # Auxiliary helper attributes (enabled_actions -> enabled_action_ids, assigned_actions -> assigned_action_ids)

            # Enabled actions
            if { [info exists row(enabled_actions)] } {
                if { [info exists row(enabled_action_ids)] } {
                    error "You cannot supply both enabled_actions and enabled_actions_ids"
                }
                set row(enabled_action_ids) [list]
                foreach action_short_name $row(enabled_actions) {
                    lappend row(enabled_action_ids) [workflow::action::get_id  -workflow_id $workflow_id  -short_name $action_short_name]
                }
                unset row(enabled_actions)
            }

            # Assigend actions
            if { [info exists row(assigned_actions)] } {
                if { [info exists row(assigned_action_ids)] } {
                    error "You cannot supply both assigned_actions and assigned_action_ids"
                }
                set row(assigned_action_ids) [list]
                foreach action_short_name $row(assigned_actions) {
                    lappend row(assigned_action_ids) [workflow::action::get_id  -workflow_id $workflow_id  -short_name $action_short_name]
                }
                unset row(assigned_actions)
            }

            # Handle auxiliary rows
            array set aux [list]
            foreach attr {
                enabled_action_ids assigned_action_ids
            } {
                if { [info exists row($attr)] } {
                    set aux($attr) $row($attr)
                    unset row($attr)
                }
            }
        }
    }

    db_transaction {
        # Sort_order
        switch $operation {
            insert - update {
                if { [info exists row(sort_order)] } {
                    workflow::state::fsm::update_sort_order  -workflow_id $workflow_id  -sort_order $row(sort_order)
                }
            }
        }
        # Do the insert/update/delete
        switch $operation {
            insert {
                if { $state_id eq "" } {
                    set state_id [db_nextval "workflow_fsm_states_seq"]
                }

                lappend insert_names state_id
                lappend insert_values :state_id
                lappend insert_names workflow_id
                lappend insert_values :workflow_id

                db_dml insert_state "
                    insert into workflow_fsm_states
                    ([join $insert_names ", "])
                    values
                    ([join $insert_values ", "])
                "
            }
            update {
                if { [llength $update_clauses] > 0 } {
                    db_dml update_state "
                        update workflow_fsm_states
                        set    [join $update_clauses ", "]
                        where  state_id = :state_id
                    "
                }
            }
            delete {
                db_dml delete_state {
                    delete from workflow_fsm_states
                    where state_id = :state_id
                }
            }
        }

        # Auxiliary rows
        switch $operation {
            insert - update {

                # Record in which actions the action is enabled but not assigned
                if { [info exists aux(enabled_action_ids)] } {
                    set assigned_p "f"
                    db_dml delete_enabled_actions {}
                    foreach enabled_action_id $aux(enabled_action_ids) {
                        db_dml insert_enabled_action {}
                    }
                    unset aux(enabled_action_ids)
                }

                # Record where the action is both enabled and assigned
                if { [info exists aux(assigned_action_ids)] } {
                    set assigned_p "t"
                    db_dml delete_enabled_actions {}
                    foreach enabled_action_id $aux(assigned_action_ids) {
                        db_dml insert_enabled_action {}
                    }
                    unset aux(assigned_action_ids)
                }

                # Check that there are no unknown attributes
                if { [array size missing_elm] > 0 && !$no_complain_p } {
                    error "Trying to set illegal state attributes: [join [array names missing_elm] ", "]"
                }
            }
        }

        if { !$internal_p } {
            workflow::definition_changed_handler -workflow_id $workflow_id
        }
    }

    return $state_id

XQL Not present:

PostgreSQL, Oracle

Generic XQL file:

<fullquery name="workflow::state::fsm::edit.delete_enabled_actions">
    <querytext>
        delete from workflow_fsm_action_en_in_st
        where  state_id = :state_id
        and    assigned_p = :assigned_p
    </querytext>
</fullquery>

<fullquery name="workflow::state::fsm::edit.insert_enabled_action">
    <querytext>
        insert into workflow_fsm_action_en_in_st
                (action_id, state_id, assigned_p)
         values (:enabled_action_id, :state_id, :assigned_p)
    </querytext>
</fullquery>

packages/workflow/tcl/state-procs.xql