view release on metacpan or  search on metacpan

lib/BPM/Engine.pm  view on Meta::CPAN

=back

Starts to run a process instance given a process instance object or id, and an 
optional hash of process instance attributes.

=head3 delete_process_instance

    $engine->delete_process_instance($pi_id);

=over 4

=item * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values

=item * Returns: ProcessInstanceRow

=back

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.

=head3 process_instance_attribute

    $attr = $engine->process_instance_attribute($pi_id, 'some_var');
    $attr = $engine->process_instance_attribute($pi_id, 'some_var', 'new_value');

=over 4

=item * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values,
$attribute_name, $attribute_value?

=item * Returns: ProcessInstanceAttributeRow

=back

Gets or sets a process instance attribute.

=head3 change_process_instance_state

    $engine->change_process_instance_state($pi_id, 'abort');

=over 4

=item * Arguments: $process_instance_id | ProcessInstanceRow | \%columns_values,
$state_transition

=item * Returns: ProcessInstanceRow

=back

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:

=over 4

=item start

Changes the process instance state from C<open.not_running.ready> to 
C<open.running>.

=item suspend

Changes the process instance state from C<open.running> to 
C<open.not_running.suspended>.

=item resume

Changes the process instance state from C<open.not_running.suspended> to 
C<open.running>.

=item terminate

Changes the process instance state from C<open.not_running.ready>, 
C<open.running> or C<open.not_running.suspended> to 
C<closed.cancelled.terminated>. This is an end state (no more state transitions
possible).

=item abort

Changes the process instance state from C<open.not_running.ready>,
C<open.running> or C<open.not_running.suspended> to
C<closed.cancelled.aborted>. This is an end state (no more state transitions 
possible).

=item finish

Changes the process instance state from C<open.running> to C<closed.completed>. 
This is an end state (no more state transitions possible).

=back

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.

=head2 ACTIVITY INSTANCE METHODS

=head3 get_activity_instances

    $rs = $engine->get_activity_instances();

=over 4

=item * Arguments: $cond?, \%attrs?

=item * Returns: $resultset

=back

Get a L<DBIx::Class::ResultSet|DBIx::Class::ResultSet> of
L<BPM::Engine::Store::Result::ActivityInstance|BPM::Engine::Store::Result::ActivityInstance>
rows. Takes the same arguments as the L<DBIx::Class::ResultSet> C<search()>
method.

=head3 get_activity_instance
    
    $ai = $engine->get_activity_instance($aid);

=over 4

=item * Arguments: \%columns_values | $activity_instance_id, \%attrs?

=item * Returns: ActivityInstanceRow

Takes an activity instance id or a hashref and optional standard
L<DBIC resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES> and returns the
corresponding L<BPM::Engine::Store::Result::ActivityInstance> row. Delegates to
L<DBIx::Class::ResultSet>'s C<find()> method.

=back

=head3 change_activity_instance_state

    $engine->change_activity_instance_state($aid, 'finish');

=over 4

=item * Arguments: $activity_instance_id | ActivityInstanceRow | \%columns_values,
$state_transition

=item * Returns: ActivityInstanceRow

=back

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:

=over 4

=item start

Changes the activity instance state from C<open.not_running.ready> to
C<open.running.not_assigned>.

=item assign

Changes the activity instance state from C<open.not_running.ready> or 
C<open.running.not_assigned> to C<open.running.assigned>.

=item reassign

Valid state transition when the activity instance state is 
C<open.running.assigned>. Does not actually change the state.

=item unassign

Changes the activity instance state from C<open.running.assigned> to 
C<open.running.not_assigned>.

=item suspend

Changes the activity instance state from C<open.running.assigned> to
C<open.not_running.suspended>.

=item resume

Changes the activity instance state from C<open.not_running.suspended> to
C<open.running.assigned>.

=item abort

Changes the activity instance state from C<open.not_running.ready> or
C<open.running.assigned> to C<closed.cancelled.aborted>. This is an end state 
(no more state transitions possible).

=item finish

Changes the activity instance state from C<open.not_running.ready> or 
C<open.running.assigned> to C<closed.completed>. This is an end state (no more 
state transitions possible).

=back

=head3 activity_instance_attribute

    $attr = $engine->activity_instance_attribute($ai_id, 'some_var');
    $attr = $engine->activity_instance_attribute($ai_id, 'some_var', 'new_value');

=over 4

=item * Arguments: $activity_instance_id | ActivityInstanceRow | \%columns_values,
$attribute_name, $attribute_value?

=item * Returns: ActivityInstanceAttributeRow

=back

Gets or sets an activity instance attribute, and returns the corresponding 
L<ActivityInstanceAttribute|BPM::Engine::Store::Result::ActivityInstanceAttribute>
row.

=head2 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

=head2 INTERNAL METHODS

=head3 runner

    $runner = $engine->runner($process_instance);

Returns a new L<BPM::Engine::ProcessRunner> instance with the C<runner_traits>
and C<callback> attribute applied for the specified process instance.
Internal method, used by C<start_process_instance()> and
C<change_activity_instance_state()> to advance a process instance.

=head1 DIAGNOSTICS

=head2 Exception Handling

When C<BPM::Engine> encounters an API error, it throws a
C<BPM::Engine::Exception> object.  You can catch and process these exceptions,
see L<BPM::Engine::Exception> for more information.

=head1 CONFIGURATION AND ENVIRONMENT

BPM::Engine may optionally be configured with a configuration file when
constructed using the C<new_with_config> method. See F<etc/engine.yaml> for an
example.

=head1 MAJOR DEPENDENCIES

=over 4

=item * Moose