set_reap_at_interval

Set the given argument as reap_at time in the database, calls the persister if the workflow is already in run state. The interval must be in relativedate format (@see OpenXPKI::DateTime). Auto-Persist can be skipped by passing a true value as second argument.

set_archive_at

Set the auto-archiving interval (relative date format or epoch, see OpenXPKI::DateTime).

The interval is converted into an epoch timestamp and written to the "archive_at" field in the database.

Triggers a DB update via persister unless $skip_saving is set to a TRUE value.

get_global_actions

Return an ArrayRef with the names of the global actions like "wakeup", "resume" or "fail" on this workflow that are available to the session user.

Name

OpenXPKI::Server::Workflow

Description

This is the OpenXPKI specific subclass of Workflow.

Purpose: overwrite the Method "execute_action" of the baseclass to implement the feature of "pauseing / wake-up / resuming" workflows

The workflow-table is expanded with 4 new persistent fields (see database schema)

    workflow_proc_state
    workflow_wakeup_at
    workflow_count_try
    workflow_reap_at
    workflow_archive_at

Essential field is "workflow_proc_state", internally "proc_state". All known and possible proc_states and their follow-up actions are defined in %known_proc_states. "running" will be set, before SUPER::execute_action/Activity::run is called. After execution of one or more Activities, either "manual" (waiting for interaction) or "finished" will be set. If an exception occurs, the proc state "exception" is set. Also the message code (not translation) will be saved in WF context (key "wf_exception") The two states "pause" and "retry_exceeded" concern the "pause" feature.

Usage documentation and guidelines

Please refer to the documentation of Workflow Modul for basic usage

new

Constructor. Takes the original Workflow-Object as first argument and take all his properties - after that the object IS the original workflow.

execute_action

wrapper around super::execute_action. does some initialisation before, checks the current proc_state, trigger the "resume"/"wake_up" - hooks, sets the "reap_at"-timestamp, sets the proc state to "running".

after super::execute_action() the special "OpenXPKI::Server::Workflow::Pause"-exception will be handled and some finalisation takes place.

pause

should not be called manually/explicitly. Activities should always use $self->pause($msg) (= OpenXPKI::Server::Workflow::Activity::pause()). calculates and stores the "count_try" and "wake_up_at" information. if "max_count:_try" is exceeded, an special exception I18N_OPENXPKI_SERVER_WORKFLOW_ACTIVITY_RETRIES_EXEEDED will be thrown. The given cause of pausing will be stored in context key "wf_pause_msg". history etries are made, observers notified. Note that pause requires an epoch value for $wakeup_at and NOT a relative date!

_handle_proc_state

checks the current proc state and determines the follow up action (e.g. "pause"->"wake_up")

_wake_up

wrapper and try/catch around Activity::wake_up(). makes history entries and notifies observers. sets the proc_state to "wakeup".

_resume

wrapper and try/catch around Activity::resume(). makes history entries and notifies observers. sets the proc_state to "wakeup".

_runtime_exception

after calling Activity::runtime_exception() throws I18N_OPENXPKI_WORKFLOW_RUNTIME_EXCEPTION

_set_proc_state($state)

stores the proc_state in the class field "proc_state" and calls "_save".

_check_and_set_proc_state($old_state, $new_state)

Stores $new_state in the class attribute "proc_state" if the previous state in the database can be updated successfully.

Returns 1 on success and 0 if the database did not show the expected $old_state, e.g. if another parallel process already changed $old_state.

After successful update, calls "$self->_save()" which persists other workflow information and performs a database COMMIT.

_proc_state_exception

is called if an exception occurs during execute_action. the code of the exception (not the translation) is stored in context key "wf_exception". observers are notified, history written. the proc_state is set to "exception", if not otherwise specified (via param "next_proc_state" given to Exception::throw(), see pause() for details. Caveat: in any case the proc_state must be specified in %known_proc_states).

_has_paused

true, if the workflow has paused (i.e. the proc state is "pause" or "retry_exeeded")

is_running

true, if the workflow is running(i.e. the proc state is "running")

_get_next_state

overwritten from parent Workflow class. handles the special case "pause", otherwise it calls super::_get_next_state()

persist_context

Internal flag to control the behaviour of the context/attribute persister:

  0: do not persist anything
  1: persist only the internal flags (context starting with wf_)
  2: persist all updated values (context and attributes)

factory

return a ref to the workflows factory

_save

Calls $self->_factory()->save_workflow($self);

set

overwritten from parent Workflow class. adds the OpenXPKI-package to the "allowed" packages, which CAN set internal properties.

Workflow context

See documentation for OpenXPKI::Server::Workflow::Persister::DBI::update_workflow() for limitations that exist for data stored in Workflow Contexts.

Activities

Creating new activities

For creating a new Workflow activity it is advisable to start with the activity template available in OpenXPKI::Server::Workflow::Activity::Skeleton.

Authorization and access control