Creating Your Own Parser

If you want to store your configuration in a different format you can create your own parser. All you need to do is:

1.

subclass Workflow::Config

2.

implement the required methods (listed below)

3.

register your parser with Workflow::Config.

For instance, if you wanted to use YAML for configuration files you would do something like:

 # just a convention, you can use any namespace you want
 package Workflow::Config::YAML;
 use strict;
 # Requirement 1: Subclass Workflow::Config
 use parent qw( Workflow::Config );
 # Requirement 2: Implement required methods
 sub parse { ... }

The third requirement is registration, which just tells Workflow::Config which parser to use for a particular type. To do this you have two options.

Registration option one

Register yourself in your own class, adding the following call anywhere the end:

 # Option 1: Register ourselves by name
 Workflow::Config->register_factory_type( yaml => 'Workflow::Config::YAML' );

Now you just need to include the configuration class in your workflow invocation script:

 use strict;
 use Workflow::Factory qw( FACTORY );
 use Workflow::Config::YAML; # <-- brings in the registration

Registration option two

You can also just explicitly add the registration from your workflow invocation script:

 use strict;
 use Workflow::Factory qw( FACTORY );
 use Workflow::Config;
 # Option 2: explicitly register your configuration parser
 Workflow::Config->register_factory_type( yaml => 'Workflow::Config::YAML' );

Whichever one you choose you can now parse (in this example) YAML files alongside the built-in parsers for XML and Perl files:

 FACTORY->add_config_from_file(
     workflow  => 'workflow.yaml',
     action    => [ 'my_actions.yaml', 'other_actions.xml' ],
     validator => 'validators.yaml',
     condition => [ 'my_conditions.yaml', 'other_conditions.xml' ]
     persister => 'persister.perl',
 );

Inherited Methods

new( $parser_type )

Instantiates an object of the correct type -- see Class::Factory for how this is implemented:

 # Parser of type 'Workflow::Config::XML'
 my $xml_parser  = Workflow::Config->new( 'xml' );
 # Parser of type 'Workflow::Config::Perl
 my $perl_parser = Workflow::Config->new( 'perl' );

is_valid_config_type( $config_type )

Returns true if $config_type is a valid configuration type, false if not. Valid configuration types are: 'action', 'condition', 'validator', 'workflow'.

get_valid_config_types()

Returns list of strings representing the valid configuration types.

get_config_type_tag( $class, $type )

Returns string representing a valid configuration type, looking up the type parameter in a lookuptable defined in Workflow::Config class.

Required Object Methods

parse( $workflow_config_type, @items )

Parse each item in @items to a hash reference based on the configuration type $config_type which must pass the is_valid_config_type() test. An 'item' is either a filename or a scalar reference with the contents of a file. (You can mix and match as seen in the SYNOPSIS.)

Should throw an exception if:

• You pass an invalid workflow configuration type. Valid workflow configuration types are registered in Workflow::Config and are available from get_valid_config_types(); you can check whether a particular type is valid with is_valid_config_type(). (See above for descriptions.)
• You pass in a file that cannot be read or parsed because of permissions, malformed XML, incorrect Perl data structure, etc. It does not do a validation check (e.g., to ensure that every 'action' within a workflow state has a 'resulting_state' key).

Returns: one hash reference for each member of @items

workflow

   workflow
      class         $
      type          $
      description   $
      persister     $
      initial_state $
      observer    \@
          sub           $
          class         $
      state       \@
          name          $
          description   $
          action        \@
              name            $
              resulting_state $
              condition       \@
                  name              $

• the 'class', 'type' and 'description' keys are at the top level
• 'persister' key holds a string declaring the name of a persister as declared in the array of persisters
• 'initial_state' key holds a string declaring the name of the initial state. by default, this value is 'INIITAL'.
• 'state' key holds array of one or more 'state' declarations; one of them must be 'INITIAL' (or the value of initial_state, if it's defined)
• each 'state' declaration holds 'description' and 'name' keys and multiple 'action' declarations
• each 'action' declaration holds 'name' and 'resulting_state' keys and may hold a 'condition' key with one or more named conditions
• each 'observer' names either a "sub" or a "class". The "sub" should have a package prefix ("Package::subname"). When a "class" name is given, the "update" sub is called as a class method in the given "class".

condition

 conditions:
     type      $
     condition \@
        name  $
        class $
        param \@
            name  $
            value $

•

array of one or more hashrefs with 'name' and 'class' keys

validator

 validators:
     validator \@
        name  $
        class $
        param \@
            name  $
            value $

•

array of one or more hashrefs with 'name' and 'class' keys, plus possibly one or more 'param' hashrefs each with 'name' and 'value' keys

action

 actions:
    type   $
    action \@
       name        $
       class       $
       description $
       field      \@
          name         $
          is_required  yes|no
          type         $
          source_list  \@ of $
          source_class $
          param        \@
              name  $
              value $
       validator \@
           name $
           arg  \@
               value $

• array of one or more action hashrefs with 'name', 'class' and 'description' keys
• each 'action' may specify a 'type' (default value: 'default'); in case a workflow specifies a 'type', actions specifying the same 'type' will be preferred over actions with the 'default' type when multiple actions by the same name exist.
• each 'action' may have zero or more values used to fill it; each value has a 'name', 'description' and 'necessity' ('required' or 'optional')
• each 'action' may have any number of 'param' hashrefs, each with 'name' and 'value'
• each 'action' may have any number of 'validator' hashrefs, each with a 'name' key and array of 'arg' declarations

persister

 persister:
   name           $        # all persister classes
   class          $        # all persister classes
   use_random     yes|no   # all persister classes
   use_uuid       yes|no   # all persister classes
   driver         $   # DBI persisters
   options        \@  # DBI persisters
      name        $   # DBI persisters
      value       $   # DBI persisters
   dsn            $   # DBI persisters
   user           $   # DBI persisters
   password       $   # DBI persisters
   workflow_table $   # DBI persisters
   history_table  $   # DBI persisters
   autocommit     $   # DBI persisters
   date_format    $   # DBI persisters
   table          $   # DBI/ExtraData persisters
   data_field     $   # DBI/ExtraData persisters
   context_key    $   # DBI/ExtraData persisters
   path           $   # File persisters

• 'name' key holds a string declaring the name by which workflows may refer to this persister configuration
• 'class' key names a Perl class name to use when instantiating the persister
• 'use_random' key holds a string declaring (through 'yes'/'no' value) to use random values for the workflow identifier
• 'use_uuid' key holds a string declaring (through 'yes'/'no' value) to use UUID (universally unique ID) values for the workflow identifier; UUIDs take preference over random IDs

For documentation of the other keys, please refer to the respective classes.

observer

 observers:
   observer \@
     name       $
     type       $
     sub        $
     class      $

• "name" specifies the name of the observer for debugging purposes.
• "type" names the type of workflow to apply the observer to. The default value is "default".
• The "sub" and "class" values have the same specification as given for the workflow observer keys.