NAME BPM::Engine - Business Process Execution Engine VERSION 0.01 SYNOPSIS Create a new BPM engine use BPM::Engine; my $callback = sub { my($runner, $entity, $event, $node, $instance) = @_; ... }; my $engine = BPM::Engine->new( log_dispatch_conf => 'log.conf', connect_info => { dsn => $dsn, user => $user, password => $password }, callback => $callback ); Save an XPDL file with workflow process definitions, and retrieve the process definitions my $package = $engine->create_package('/path/to/model.xpdl'); my @processes = $engine->get_process_definitions->all; Create and run a process instance my $instance = $engine->create_process_instance( $process, { instance_name => 'My first process run' } ); $engine->start_process_instance($instance, { param1 => 'value1' }); DISCLAIMER This is ALPHA SOFTWARE. Use at your own risk. Features may change. DESCRIPTION BPM::Engine is an embeddable workflow process engine with persistence. It handles saving and loading XPDL packages in a database, and running workflow processes. INTERFACE CONSTRUCTORS BPM::Engine->new(%options) Creates a new bpm engine. $engine = BPM::Engine->new( connect_info => { dsn => $dsn, user => $user, password => $pass, %dbi_attributes, %extra_attributes, }); Possible options are: "schema => $schema // BpmEngineStore" BPM::Engine::Store connected schema object. If not provided, one will be created using the "connect_info" option. Either "schema" or "connect_info" is required on object construction. "connect_info => $dsn // ConnectInfo" DBIx::Class::Schema connection arguments that get passed to the "connect()" call to BPM::Engine::Store, as specified by the "ConnectInfo" type in BPM::Engine::Types::Internal. Usually a single hashref with dsn/user/password and attributes. This attribute is only used to build the "schema" attribute if not provided already. "logger => $logger // BpmEngineLogger" A logger object that implements the MooseX::LogDispatch::Interface role, defaults to a BPM::Engine::Logger instance constructed with "log_dispatch_conf". "log_dispatch_conf => $file | $hashref" Optional constructor argument for BPM::Engine::Logger to build the default "logger", if a logger was not provided. "callback => \&cb" Optional callback *&cb* which is called on all process instance events. This option is passed to any "BPM::Engine::ProcessRunner" constructor. "runner_traits => [qw/TraitA TraitB/] // []" Optional traits to be supplied to all "BPM::Engine::ProcessRunner" objects used. BPM::Engine->new_with_config(%options) $engine = BPM::Engine->new_with_config( configfile => "/etc/bpmengine/engine.conf" ); Provided by the base role MooseX::SimpleConfig. Acts just like regular "new()", but also accepts an argument "configfile" to specify the configfile from which to load other attributes. "configfile => $file // $ENV{HOME}/bpmengine/engine.conf" A file that, when passed to "new_with_config", is parsed using Config::Any to support any of a variety of different config formats, detected by the file extension. See Config::Any for more details about supported formats. Explicit arguments to "new_with_config" will override anything loaded from the configfile. BPM::Engine->new_with_traits(%options) Just like "new()", but also accepts a "traits" argument with a list of trait names to apply to the engine object. $engine = BPM::Engine->new_with_traits( traits => [qw/Foo Bar/], schema => $schema ); Options, in addition to those to "new()": "traits => \@traitnames // []" Traits live under the "BPM::Engine::Trait" namespace by default, prefix full class names with a "+". BPM::Engine->with_traits(@traits)->new(%options) You can use the "with_traits" class method to use traits in combination with a configuration file. Example: $engine = BPM::Engine->with_traits(qw/Foo Bar/)->new_with_config( configfile => '/home/user/bpmengine.conf' ); PROCESS DEFINITION METHODS get_packages $rs = $engine->get_packages(); * Arguments: $cond?, \%attrs? * Returns: $resultset Get a DBIx::Class::ResultSet of BPM::Engine::Store::Result::Package rows. Takes the same arguments as the DBIx::Class::ResultSet "search()" method. get_package $package = $engine->get_package($package_uuid); * Arguments: \%columns_values | $uuid, \%attrs? * Returns: PackageRow Takes a package UUID or a hashref and optional standard DBIC resultset attributes and returns the BPM::Engine::Store::Result::Package row. Delegates to DBIx::Class::ResultSet's "find()" method. Throws an exception if the package is not found. create_package $package = $engine->create_package($file); * Arguments: $xpdl_file | \$string | IO::Handle * Returns: PackageRow Takes XPDL xml input and returns a newly created Package row. Input can be a file path, URL, reference to a string or io stream. Throws an exception if inconsistencies were found in the xml. delete_package $deleted_package = $engine->delete_package($package_uuid); * Arguments: \%columns_values | $uuid * Returns: PackageRow Delete a package from the data store. Warning: this will also delete all processes and process instances related to the package. An exception is thrown if the package is not in the database. get_process_definitions $rs = $engine->get_process_definitions(); * Arguments: $cond?, \%attrs? * Returns: $resultset Get a DBIx::Class::ResultSet of BPM::Engine::Store::Result::Process rows. Takes the same arguments as the DBIx::Class::ResultSet "search()" method. get_process_definition $process = $engine->get_process_definition($uuid); * Arguments: \%columns_values | $uuid, \%attrs? * Returns: ProcessRow Takes a package UUID or a hashref and optional standard DBIC resultset attributes and returns the corresponding BPM::Engine::Store::Result::Process row. Delegates to DBIx::Class::ResultSet's "find()" method. Throws an exception if the process is not found. PROCESS INSTANCE METHODS get_process_instances $rs = $engine->get_process_instances(); * Arguments: $cond?, \%attrs? * Returns: $resultset Get a DBIx::Class::ResultSet of BPM::Engine::Store::Result::ProcessInstance rows. Takes the same arguments as the DBIx::Class::ResultSet "search()" method. get_process_instance $process_instance = $engine->get_process_instance($pi_id); * Arguments: \%columns_values | $uuid, \%attrs? * Returns: ProcessInstanceRow Takes a package UUID or a hashref and optional standard DBIC resultset attributes and returns the corresponding BPM::Engine::Store::Result::ProcessInstance row. Delegates to DBIx::Class::ResultSet's "find()" method. create_process_instance $process_instance = $engine->create_process_instance($process_id); * Arguments: $uuid | ProcessRow, \%attrs? * Returns: ProcessInstanceRow Creates a new process instance, given a process id or BPM::Engine::Store::Result::Process row object and an optional hash of process instance properties. Of these process instance properties, "instance_name" is useful to specify a name for the instance. A name will be auto-generated if not specified. Returns the BPM::Engine::Store::Result::ProcessInstance that was created. start_process_instance $engine->start_process_instance($pi_id); * Arguments: $process_instance_id | ProcessInstanceRow, \%attrs? * Returns: void Starts to run a process instance given a process instance object or id, and an optional hash of process instance attributes. delete_process_instance $engine->delete_process_instance($pi_id); * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values * Returns: ProcessInstanceRow Takes a process instance id or a process instance object, and deletes the process instance from the data store. An exception is thrown if the process instance is not found in the data store. process_instance_attribute $attr = $engine->process_instance_attribute($pi_id, 'some_var'); $attr = $engine->process_instance_attribute($pi_id, 'some_var', 'new_value'); * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values, $attribute_name, $attribute_value? * Returns: ProcessInstanceAttributeRow Gets or sets a process instance attribute. change_process_instance_state $engine->change_process_instance_state($pi_id, 'abort'); * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values, $state_transition * Returns: ProcessInstanceRow Sets the new state of the process instance given a process instance id or a process instance object and a state transition name. The following state transitions are possible: start Changes the process instance state from "open.not_running.ready" to "open.running". suspend Changes the process instance state from "open.running" to "open.not_running.suspended". resume Changes the process instance state from "open.not_running.suspended" to "open.running". terminate Changes the process instance state from "open.not_running.ready", "open.running" or "open.not_running.suspended" to "closed.cancelled.terminated". This is an end state (no more state transitions possible). abort Changes the process instance state from "open.not_running.ready", "open.running" or "open.not_running.suspended" to "closed.cancelled.aborted". This is an end state (no more state transitions possible). finish Changes the process instance state from "open.running" to "closed.completed". This is an end state (no more state transitions possible). An exception will be thrown for invalid state transitions, for example when the process instance is not in the right state to allow the transition. ACTIVITY INSTANCE METHODS get_activity_instances $rs = $engine->get_activity_instances(); * Arguments: $cond?, \%attrs? * Returns: $resultset Get a DBIx::Class::ResultSet of BPM::Engine::Store::Result::ActivityInstance rows. Takes the same arguments as the DBIx::Class::ResultSet "search()" method. get_activity_instance $ai = $engine->get_activity_instance($aid); * Arguments: \%columns_values | $activity_instance_id, \%attrs? * Returns: ActivityInstanceRow Takes an activity instance id or a hashref and optional standard DBIC resultset attributes and returns the corresponding BPM::Engine::Store::Result::ActivityInstance row. Delegates to DBIx::Class::ResultSet's "find()" method. change_activity_instance_state $engine->change_activity_instance_state($aid, 'finish'); * Arguments: $activity_instance_id | ActivityInstanceRow | \%columns_values, $state_transition * Returns: ActivityInstanceRow Sets the new state of the activity instance given a activity instance id or a activity instance object and a state transition name. The following state transitions are possible: start Changes the activity instance state from "open.not_running.ready" to "open.running.not_assigned". assign Changes the activity instance state from "open.not_running.ready" or "open.running.not_assigned" to "open.running.assigned". reassign Valid state transition when the activity instance state is "open.running.assigned". Does not actually change the state. unassign Changes the activity instance state from "open.running.assigned" to "open.running.not_assigned". suspend Changes the activity instance state from "open.running.assigned" to "open.not_running.suspended". resume Changes the activity instance state from "open.not_running.suspended" to "open.running.assigned". abort Changes the activity instance state from "open.not_running.ready" or "open.running.assigned" to "closed.cancelled.aborted". This is an end state (no more state transitions possible). finish Changes the activity instance state from "open.not_running.ready" or "open.running.assigned" to "closed.completed". This is an end state (no more state transitions possible). activity_instance_attribute $attr = $engine->activity_instance_attribute($ai_id, 'some_var'); $attr = $engine->activity_instance_attribute($ai_id, 'some_var', 'new_value'); * Arguments: $activity_instance_id | ActivityInstanceRow | \%columns_values, $attribute_name, $attribute_value? * Returns: ActivityInstanceAttributeRow Gets or sets an activity instance attribute, and returns the corresponding ActivityInstanceAttribute row. LOGGING METHODS $engine->debug('Some thing did a thing'); The following methods of the attached logger object are available to the engine: log, debug, info, notice, warning, error, critical, alert, emergency INTERNAL METHODS runner $runner = $engine->runner($process_instance); Returns a new BPM::Engine::ProcessRunner instance with the "runner_traits" and "callback" attribute applied for the specified process instance. Internal method, used by "start_process_instance()" and "change_activity_instance_state()" to advance a process instance. DIAGNOSTICS Exception Handling When "BPM::Engine" encounters an API error, it throws a "BPM::Engine::Exception" object. You can catch and process these exceptions, see BPM::Engine::Exception for more information. CONFIGURATION AND ENVIRONMENT BPM::Engine may optionally be configured with a configuration file when constructed using the "new_with_config" method. See etc/engine.yaml for an example. MAJOR DEPENDENCIES * Moose * Class::Workflow * BPM::XPDL * DBIx::Class * Template Toolkit * Text::Xslate * XML::LibXML * Graph See the included Makefile.PL for a list of all dependencies. INCOMPATIBILITIES None reported. AUTHOR Peter de Vos, "" SOURCE You can contribute or fork this project via GitHub: git clone git://github.com/sitetechie/BPM-Engine.git BUGS Probably. Along with error conditions not being handled gracefully etc. They will be fixed in due course as I start using this more seriously, however in the meantime, patches are welcome :) SUPPORT You can find documentation for this module with the perldoc command. perldoc BPM::Engine You can also look for information at: * Homepage * Github Repository COPYRIGHT AND LICENSE Copyright (c) 2010, 2011 Peter de Vos. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. DISCLAIMER OF WARRANTY BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.