+ By Lars Pind +
+ ++ This requirements and design document is primarily motivated by: +
+ ++ Use cases: +
+ ++ The timer will always be of the form "This action will automatically + execute x amount of time after it becomes enabled". If it is later + un-enabled (disabled) because another action (e.g. a vote action in + the second use casae above) was executed, then the timer will be + reset. If the action later becomes enabled, the timer will start + anew. +
+ ++ We currently do not have any information on which actions are + enabled, and when they're enabled. We will probably need a table, + perhaps one just for timed actions, in which a row is created when a + timed action is enabled, and the row is deleted again when the state + changes. +
+ ++create table workflow_actions( + ... + -- The number of seconds after having become enabled the action + -- will automatically execute + timeout interval + ... +); ++ +
+ DESIGN NOTE: The 'interval' datatype is not supported in + Oracle. +
+ ++create table workflow_case_enabled_actions( + case_id integer + constraint wf_case_enbl_act_case_id_nn + not null + constraint wf_case_enbl_act_case_id_fk + references workflow_cases(case_id) + on delete cascade, + action_id integer + constraint wf_case_enbl_act_action_id_nn + not null + constraint wf_case_enbl_act_action_id_fk + references workflow_actions(action_id) + on delete cascade, + -- the timestamp when this action will fires + execution_time timestamptz + constraint wf_case_enbl_act_timeout_nn + not null, + constraint workflow_case_enabled_actions_pk + primary key (case_id, action_id) +); ++ +
+ After executing an action, workflow::case::action::execute will:
+
worklfow_case_enabled_actions which are no longer enabled.
+ workflow_case_enabled_actions, with
+ fire_timestamp = current_timestamp + workflow_actions.timeout_seconds .
+ + NOTE: We need to keep running, so if another automatic action + becomes enabled after this action fires, they'll fire as well. +
+ +
+ The sweeper will find rows in
+ workflow_case_enabled_actions with fire_timetsamp
+ < current_timestamp, ordered by fire_timstamp, and execute
+ them.
+
+ It should do a query to find the action to fire first, then release + the db-handle and execute it. Then do a fresh query to find the + next, etc. That way we will handle the situation correctly where the + first action firing causes the second action to no longer be + enabled. +
+ ++ Every time the sweeper runs, at least one DB query will be made, + even if there are no timed actions to be executed. +
+ ++ Possible optimizations: +
+ ++ Use cases: +
+ +
+create table workflow_actions(
+ ...
+ child_workflow integer
+ constraint wf_action_child_wf_fk
+ references workflows(workflow_id),
+ ...
+);
+
+create table workflow_fsm_states(
+ ...
+ -- does this state imply that the case is completed?
+ complete_p boolean,
+ ...
+);
+
+create table workflow_action_fsm_output_map(
+ action_id integer
+ not null
+ references workflow_actions(action_id)
+ on delete cascade,
+ acs_sc_impl_id integer
+ not null
+ references acs_sc_impls(impl_id)
+ on delete cascade,
+ output_value varchar(4000),
+ new_state integer
+ references workflow_fsm_states
+);
+
+create table workflow_action_child_role_map(
+ parent_action_id integer
+ constraint wf_act_chid_rl_map_prnt_act_fk
+ references workflow_actions(action_id),
+ parent_role integer
+ constraint wf_act_chid_rl_map_prnt_rl_fk
+ references workflow_roles(role_id),
+ child_role integer
+ constraint wf_act_chid_rl_map_chld_rl_fk
+ references workflow_roles(role_id),
+ mapping_type char(40)
+ constraint wf_act_chid_rl_map_type_ck
+ check (mapping_type in
+ ('per_role','per_member','per_user'))
+);
+
+
+create table workflow_cases(
+ ...
+ state char(40)
+ constraint workflow_cases_state_ck
+ check (state in ('active', 'completed',
+ 'closed', 'canceled', 'suspended'))
+ default 'active',
+ suspended_until timestamptz,
+ parent_enabled_action_id integer
+ constraint workflow_cases_parent_fk
+ references workflow_case_enabled_actions(enabled_action_id)
+);
+
+create table workflow_case_enabled_actions(
+ enabled_action_id integer
+ constraint wf_case_enbl_act_case_id_pk
+ primary key,
+ case_id integer
+ constraint wf_case_enbl_act_case_id_nn
+ not null
+ constraint wf_case_enbl_act_case_id_fk
+ references workflow_cases(case_id)
+ on delete cascade,
+ action_id integer
+ constraint wf_case_enbl_act_action_id_nn
+ not null
+ constraint wf_case_enbl_act_action_id_fk
+ references workflow_actions(action_id)
+ on delete cascade,
+ enabled_state char(40)
+ constraint wf_case_enbl_act_state_ck
+ check (enabled_state in ('enabled','completed','canceled','refused')),
+ -- the timestamp when this action automatically fires
+ fire_timestamp timestamp
+ constraint wf_case_enbl_act_timeout_nn
+ not null,
+ constraint wf_case_ena_act_case_act_un
+ primary key (case_id, action_id)
+);
+
+
+
+enabled_state of the row in
+ workflow_case_enabled_actions will be set to
+ 'refused'.
+ + The callbacks returning 'output' above must enumerate all the values + they can possible output (similar contruct to GetObjectType + operation on other current workflow service contracts), and the + callback itself must return one of those possible values. +
+ ++ The workflow engine will then allow the workflow designer to map + these possible output values of the callback to new states, in the + case of an FSM, or similar relevant state changes for other models. +
+ ++ Executed when an action which was previously not enabled becomes enabled. +
+ ++ Executed when an action which was previously enabled is no longer + enabled, because the workflow's state was changed by some other + action. +
+ ++ We execute the OnChildCaseStateChange callback, if any. This gets to + determine whether the parent action is now complete and should fire. +
+ ++ We provide a default implementation, which simply checks if the + child cases are in the 'complete' state, and if so, fires. +
+ ++ NOTE: What do we do if any of the child cases are canceled? Consider + the complete and move on with the parent workflow? Cancel the parent + workflow? +
+ ++ NOTE: Should we provide this as internal workflow logic or as a + default callback implementation? If we leave this as a service + contract with a default implementation, then applications can + customize. But would that ever be relevant? Maybe this callback is + never needed. +
+ ++ When the action finally fires. +
+ ++ If there's any OnFire callback defined, we execute this. +
+ +
+ If the callback has output values defined, we use the mappings in
+ workflow_action_fsm_output_map to determine which state to
+ move to.
+
+ After firing, we execute the SideEffect callbacks and send off + notifications. +
+ ++ DESIGN QUESTION: How do we handle notifications for child cases? We + should consider the child case part of the parent in terms of + notifications, so when a child action executes, we notify those who + have requested notifications on the parent. And when the last child + case completes, which will also complete the parent action, we + should avoid sending out duplicate notifications. How? +
+ ++ Cases can be active, complete, suspended, or canceled. +
+ +
+ They start out as active. For FSMs, when they hit a state with
+ complete_p = t, the case is moved to 'complete'.
+
+ Users can choose to cancel or suspend a case. When suspending, they + can type in a date, on which the case will spring back to 'active' + life. +
+ ++ When a parent worfklow completes an action with a sub-workflow, the + child cases that are 'completed' are marked 'closed', and the child + cases that are 'active' are marked 'canceled'. +
+ ++ The difference between 'completed' and 'closed' is that completed + does not prevent the workflow from continuing (e.g. bug-tracker + 'closed' state doesn't mean that it cannot be reopened), whereas a + closed case cannot be reactivarted (terminology confusion alert!). +
+ + ++ An action does not become avilable until a given list of other + actions have completed. The advanced version is that you can also + specify for each of these other tasks how many times they must've + been executed. +
+ ++create table workflow_action_dependencies( + action_id integer + constraint wf_action_dep_action_fk + references workflow_actions(action_id), + dependent_on_action integer + constraint wf_action_dep_dep_action_fk + references workflow_actions(action_id), + min_n integer default 1, + max_n integer, + constraint wf_action_dep_act_dep_pk + primary key (action_id, dependent_on_action) +); ++ +
+ When an action is about to be enabled, and before calling the + CanEnableP callback, we check the workflow_case_enabled_actions table + to see that the required actions have the required number of rows in + the workflow_case_enabled_actions table with enabled_state + 'completed'. +
+ + + ++ An action can at most be executed a certain number of times. +
+ ++create table workflow_actions( + ... + max_n integer + ... +); ++ +
+ When an action is about to be enabled, and before calling the + CanEnableP callback, we check the workflow_case_enabled_actions table + to see how many rows exist with enabled_state 'completed'. +
+ + + ++ The bug-tracker has resolution codes under the "Resolve" action. It + would be useful if these could be customized. +
+ ++ In addition, I saw one other dynamic-workflow product (TrackStudio) + on the web, and they have the concept of resolution codes + included. That made me realize that this is generally useful. +
+ ++ In general, a resolution code is a way of distinguishing different + states, even though those states are identical in terms of the + workflow process. +
+ ++ Currently, the code to make these happen is fairly clumsy, what with + the "FormatLogTitle" callback which we invented. +
+ ++create sequence ... + +create table workflow_action_resolutions( + resolution_id integer + constraint wf_act_res_pk + primary key, + action_id integer + constraint wf_act_res_action_fk + references workflow_actions(action_id) + on delete cascade, + sort_order integer + constraint wf_act_res_sort_order_nn + not null, + short_name varchar(100) + constraint wf_act_res_short_name_nn + not null, + pretty_name varchar(200) + constraint wf_act_res_pretty_name_nn + not null +); + +create index workflow_act_res_act_idx on workflow_action_resolutions(action_id); + +create table workflow_action_res_output_map( + action_id integer + not null + references workflow_actions(action_id) + on delete cascade, + acs_sc_impl_id integer + not null + references acs_sc_impls(impl_id) + on delete cascade, + output_value varchar(4000), + resolution_id integer + not null + references workflow_action_resolutions(resolution_id) + on delete cascade, +); + +-- FK index on action_id +-- FK index on acs_sc_impl_id +-- FK index on resolution ++ + + + + +
+TIP Master Workflow + Model = FSM + Roles + Submitter + Voter + States + Proposed + Voting + Withdrawn + Approved + Rejected + Actions + Propose + Initial action + New state = Proposed + Vote + Enabled in state = Proposed + Role = Voter + Sub-workflow = Individual Vote + In progress state = Voting + Sub-role Voter = pparent role Voter + One sub-case per user in the Voter role + New state = Approved | Rejected + Logic = + 0 Rejects + > 0 Approvals = Approved + 2/3rds Approvals => Approved + Otherwise => Rejected + Withdraw + Enabled in state = Proposed, Voting + Role = Submitter + New state = Withdrawn + +TIP Individual Vote Workflow + Model = FSM + Roles + Voter + States + Open + Approved + Rejected + Abstained + Actions + Open + Initial action + New state = Open + Approve + Enabled in state = Open + Role = Voter + New state = Approved + Reject + Enabled in state = Open + Role = Voter + New state = Rejected + Abstain + Enabled in state = Open + Role = Voter + New state = Abstained + No Vote + Enabled in state = Open + Timeout = 7 days + New state = Abstained ++ + +