workflow::action::fsm::edit (public)

 workflow::action::fsm::edit [ -operation operation ] \
    [ -action_id action_id ] [ -workflow_id workflow_id ] \
    [ -array array ] [ -internal ] [ -handlers handlers ]

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

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:

• workflow::action::edit

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

Testcases:

No testcase defined.

Source code:

    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

Generic XQL file:

<fullquery name="workflow::action::fsm::edit.update_fsm_action">
    <querytext>
        update workflow_fsm_actions
        set    new_state = :new_state_id
        where  action_id = :action_id
    </querytext>
</fullquery>

<fullquery name="workflow::action::fsm::edit.delete_enabled_states">
    <querytext>
        delete from workflow_fsm_action_en_in_st
        where  action_id = :action_id
        and    assigned_p = :assigned_p
    </querytext>
</fullquery>

<fullquery name="workflow::action::fsm::edit.insert_enabled_state">
    <querytext>
        insert into workflow_fsm_action_en_in_st
                (action_id, state_id, assigned_p)
         values (:action_id, :enabled_state_id, :assigned_p)
    </querytext>
</fullquery>

packages/workflow/tcl/action-procs.xql

PostgreSQL XQL file:

packages/workflow/tcl/action-procs-postgresql.xql

Oracle XQL file:

packages/workflow/tcl/action-procs-oracle.xql