workflow::edit (public)

 workflow::edit [ -operation operation ] [ -workflow_id workflow_id ] \
    [ -array array ] [ -internal ] [ -no_complain ]

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

Edit a workflow. Attributes of the array are:

• short_name
• pretty_name
• object_id
• package_key
• object_type
• description
• description_mime_type
• callbacks
• context_id
• creation_user
• creation_ip

Switches:

-operation (optional, defaults to "update")

insert, update, delete

-workflow_id (optional)

For update/delete: The workflow to update or delete.

-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.

Returns:

workflow_id

Authors:

Peter Marklund

Lars Pind <lars@collaboraid.biz>

See Also:

• workflow::new

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

Testcases:

No testcase defined.

Source code:

    switch $operation {
        update - delete {
            if { $workflow_id eq "" } {
                error "You must specify the workflow_id of the workflow 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 {
            # Check that they didn't try to supply a workflow_id
            if { [info exists row(workflow_id)] } {
                error "Cannot supply a workflow_id when creating"
            }
            # Default short_name on insert
            if { ![info exists row(short_name)] } {
                set row(short_name) {}
            }
            # Default package_key
            if { ![info exists row(package_key)] } {
                if { [ad_conn isconnected] } {
                    set row(package_key) [ad_conn package_key]
                }
            }
            # Default creation_user and creation_ip
            if { ![info exists row(creation_user)] } {
                if { [ad_conn isconnected] } {
                    set row(creation_user) [ad_conn user_id]
                } else {
                    set row(creation_user) ""
                }
            }
            if { ![info exists row(creation_ip)] } {
                if { [ad_conn isconnected] } {
                    set row(creation_ip) [ad_conn peeraddr]
                } else {
                    set row(creation_ip) ""
                }
            }
            # Default object_type
            if { ![info exists row(object_type)] } {
                set row(object_type) "acs_object"
            }
            # Check required values
            foreach attr { pretty_name package_key object_id  } {
                if { ![info exists row($attr)] } {
                    error "$attr is required when creating a new workflow"
                }
            }
            # Default context_id
            if { ![info exists row(context_id)] } {
                set row(context_id) $row(object_id)
            }
            # These are used when validating/generating short_name
            set workflow_array(package_key) $row(package_key)
            set workflow_array(object_id) $row(object_id)
        }
        update {
            # These are used when validating/generating short_name
            if { [info exists row(package_key)] || ![info exists row(object_id)]  } {
                workflow::get -workflow_id $workflow_id -array workflow_array
            }
            if { [info exists row(package_key)] } {
                set workflow_array(package_key) $row(package_key)
            }
            if { [info exists row(object_id)]  } {
                set workflow_array(object_id) $row(object_id)
            }
        }
    }


    # Parse column values
    switch $operation {
        insert - update {
            set update_clauses [list]
            set insert_names [list]
            set insert_values [list]

            # Handle columns in the workflows table
            foreach attr {
                short_name
                pretty_name
                object_id
                package_key
                object_type
                description
                description_mime_type
                creation_user
                creation_ip
                context_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 $operation with an empty short_name without also setting pretty_name"
                                } else {
                                    set row(pretty_name) {}
                                }
                            }

                            set $varname [workflow::generate_short_name  -workflow_id $workflow_id  -pretty_name $row(pretty_name)  -short_name $row(short_name)  -package_key $workflow_array(package_key)  -object_id $workflow_array(object_id)]
                        }
                        default {
                            set $varname $row($attr)
                        }
                    }
                    # Add the column to the insert/update statement
                    switch $attr {
                        short_name - pretty_name - package_key - object_id - object_type {
                            switch $operation {
                                insert {
                                    # Handled by the PL/SQL call
                                }
                                update {
                                    lappend update_clauses "$attr = :$varname"
                                }
                            }
                        }
                        creation_user - creation_ip - context_id {
                            if { $operation ne "insert" } {
                                error "Cannot update creation_user, creation_ip, context_id"
                            }
                        }
                        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 {
        # Do the insert/update/delete
        switch $operation {
            insert {
                # Insert the workflow -- uses a PL/SQL call because it's an object
                set workflow_id [db_exec_plsql do_insert {}]

                # Deal with attributes not handled by the PL/SQL call
                if { [llength $update_clauses] > 0 } {
                    db_dml update_workflow "
                        update workflows
                        set    [join $update_clauses ", "]
                        where  workflow_id = :workflow_id
                    "
                }
            }
            update {
                if { [llength $update_clauses] > 0 } {
                    db_dml update_workflow "
                        update workflows
                        set    [join $update_clauses ", "]
                        where  workflow_id = :workflow_id
                    "
                }
            }
            delete {
                db_dml delete_workflow {
                    delete from workflows
                    where workflow_id = :workflow_id
                }
            }
        }

        switch $operation {
            insert - update {
                # Callbacks
                if { [info exists row(callbacks)] } {
                    db_dml delete_callbacks {
                        delete from workflow_callbacks
                        where  workflow_id = :workflow_id
                    }
                    foreach callback_name $row(callbacks) {
                        workflow::callback_insert  -workflow_id $workflow_id  -name $callback_name
                    }
                    unset missing_elm(callbacks)
                }

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

    if { !$internal_p } {
        # Flush the workflow cache, as changing an workflow changes the entire workflow
        # e.g. initial_workflow_p, enabled_in_states.
        workflow::flush_cache -workflow_id $workflow_id
    }

    return $workflow_id

Generic XQL file:

packages/workflow/tcl/workflow-procs.xql

PostgreSQL XQL file:

<fullquery name="workflow::edit.do_insert">
    <querytext>
        select workflow__new (
            :attr_short_name,
            :attr_pretty_name,
            :attr_package_key,            
            :attr_object_id,
            :attr_object_type,
            :attr_creation_user,
            :attr_creation_ip,
            :attr_context_id
        );
    </querytext>
</fullquery>

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

Oracle XQL file:

<fullquery name="workflow::edit.do_insert">
    <querytext>
        begin
        :1 := workflow.new (
            short_name => :attr_short_name,
            pretty_name => :attr_pretty_name,
            package_key => :attr_package_key,            
            object_id => :attr_object_id,
            object_type => :attr_object_type,
            creation_user => :attr_creation_user,
            creation_ip => :attr_creation_ip,
            context_id => :attr_context_id
        );
        end;
    </querytext>
</fullquery>

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