Workflow::Persister::DBI(3pm)

1Workflow::Persister::DBUIs(e3r)Contributed Perl DocumentWaotrikofnlow::Persister::DBI(3)
2
3
4

NAME

6       Workflow::Persister::DBI - Persist workflow and history to DBI database
7

VERSION

9       This documentation describes version 1.61 of this package
10

SYNOPSIS

12        <persister name="MainDatabase"
13                   class="Workflow::Persister::DBI"
14                   dsn="DBI:mysql:database=workflows"
15                   user="wf"
16                   password="mypass"/>
17
18        <persister name="BackupDatabase"
19                   class="Workflow::Persister::DBI"
20                   dsn="DBI:Pg:dbname=workflows"
21                   user="wf"
22                   password="mypass"
23                   date_format="%Y-%m-%d %H:%M"
24                   autocommit="0"
25                   workflow_table="wf"
26                   workflow_sequence="wf_seq"
27                   history_table="wf_history"
28                   history_sequence="wf_history_seq"/>
29
30        <persister name="OtherDatabase"
31                   class="My::Persister::DBHFromElsewhere"
32                   driver="mysql"
33                   />
34

DESCRIPTION

36       Main persistence class for storing the workflow and workflow history
37       records to a DBI-accessible datasource.
38
39   Subclassing: Getting handle from elsewhere
40       A common need to create a subclass is to use a database handle created
41       with other means. For instance, OpenInteract has a central
42       configuration file for defining datasources, and the datasource will be
43       available in a predictable manner. So we can create a subclass to
44       provide the database handle on demand from the "CTX" object available
45       from everywhere. A sample implementation is below. (Note that in real
46       life we would just use SPOPS for this, but it is still a good example.)
47
48        package Workflow::Persister::DBI::OpenInteractHandle;
49
50        use strict;
51        use base qw( Workflow::Persister::DBI );
52        use OpenInteract2::Context qw( CTX );
53
54        my @FIELDS = qw( datasource_name );
55        __PACKAGE__->mk_accessors( @FIELDS );
56
57        # override parent method, assuming that we set the 'datasource'
58        # parameter in the persister declaration
59
60        sub init {
61           my ( $self, $params ) = @_;
62           $self->datasource_name( $params->{datasource} );
63           my $ds_config = CTX->lookup_datasource_config( $self->datasource_name );
64
65           # delegate the other assignment tasks to the parent class
66           $params->{driver} = $ds_config->{driver_name};
67           $self->SUPER::init( $params );
68        }
69
70        # suppress the parent from trying to connect to the database
71        sub create_handle { return undef; }
72
73        sub handle {
74            my ( $self ) = @_;
75            return CTX->datasource( $self->datasource_name );
76        }
77
78   Subclassing: Changing fieldnames
79       Earlier versions of Workflow used the field 'user' to record in the
80       history the user making a state change or comment. Unfortunately 'user'
81       is a reserved word in our favorite database, PostgreSQL. (Oops.) So in
82       addition to changing the field to an assuredly-unreserved word
83       (workflow_user), we made the fieldnames customizable by subclasses.
84
85       Just override either or both of the methods:
86
87       get_workflow_fields()
88
89       Return list of fields in this order:
90
91         workflow_id, type, state, last_update
92
93       get_history_fields()
94
95       Return list of fields in this order:
96
97         workflow_hist_id, workflow_id, action, description,
98         state, workflow_user, history_date
99
100       Note that we may cache the results, so don't try and do anything weird
101       like change the fieldnames based on the workflow user or something...
102

METHODS

104   Public Methods
105       All public methods are inherited from Workflow::Persister.
106
107   Private Methods
108       init( \%params )
109
110       Initializes the the instance by setting the connection parameters and
111       calling "create_handle". You are only required to provide 'dsn', which
112       is the full DBI DSN you normally use as the first argument to
113       connect().
114
115       You can set these parameters in your persister configuration file and
116       they will be passed to init.
117
118       You may also use:
119
120       user
121           Name of user to login with.
122
123       password
124           Password for "user" to login with.
125
126       date_format
127           Date format to use when working with the database. Accepts a format
128           string that can be processed by the DateTime module. See
129           <http://search.cpan.org/~drolsky/DateTime-0.39/lib/DateTime.pm#strftime_Specifiers>
130           for the format options.
131
132           The default is '%Y-%m-%d %H:%M' for backward compatibility.
133
134       autocommit
135           0 or 1 to turn autocommit off or on for the database handle.
136
137           Setting autocommit to off will run Workflow with transactions. If
138           there is a failure somewhere and the persister supports it,
139           Workflow will attempt to roll back all database activity in the
140           current transaction.
141
142           If you turn autocommit off, you must still commit transactions for
143           Workflow::Persister::DBI::ExtraData yourself. Also, if you are
144           sharing the database handle, you must be careful to not pass
145           control to the workflow engine with pending transactions as they
146           will be committed if the workflow actions are successful.
147
148           The default autocommit value for the database handle is on.
149
150       workflow_table
151           Table to use for persisting workflow. Default is 'workflow'.
152
153       history_table
154           Table to use for persisting workflow history. Default is
155           'workflow_history'.
156
157       You may also use parameters for the different types of ID generators.
158       See below under the "init_*_generator" for the necessary parameters for
159       your database.
160
161       In addition to creating a database handle we parse the "dsn" to see
162       what driver we are using to determine how to generate IDs. We have the
163       ability to use automatically generated IDs for PostgreSQL, MySQL, and
164       SQLite. If your database is not included a randomly generated ID will
165       be used. (Default length of 8 characters, which you can modify with a
166       "id_length" parameter.)
167
168       You can also create your own adapter for a different type of database.
169       Just check out the existing Workflow::Persister::DBI::AutoGeneratedId
170       and Workflow::Persister::DBI::SequenceId classes for examples.
171
172       assign_generators( $driver, \%params )
173
174       Given $driver and the persister parameters in "\%params", assign the
175       appropriate ID generators for both the workflow and history tables.
176
177       Returns: nothing, but assigns the object properties
178       "workflow_id_generator" and "history_id_generator".
179
180       assign_tables( \%params )
181
182       Assign the table names from "\%params" (using 'workflow_table' and
183       'history_table') or use the defaults 'workflow' and 'workflow_history'.
184
185       Returns: nothing, but assigns the object properties "workflow_table"
186       and "history_table".
187
188       init_postgres_generators( \%params )
189
190       Create ID generators for the workflow and history tables using
191       PostgreSQL sequences. You can specify the sequences used for the
192       workflow and history tables:
193
194       workflow_sequence
195           Sequence for the workflow table. Default: 'workflow_seq'
196
197       history_sequence
198           Sequence for the workflow history table. Default:
199           'workflow_history_seq'
200
201       init_mysql_generators( \%params )
202
203       Create ID generators for the workflow and history tables using the
204       MySQL 'auto_increment' type. No parameters are necessary.
205
206       init_sqlite_generators( \%params )
207
208       Create ID generators for the workflow and history tables using the
209       SQLite implicit increment. No parameters are necessary.
210
211       init_random_generators( \%params )
212
213       Create ID generators for the workflow and history tables using a random
214       set of characters. You can specify:
215
216       id_length
217           Length of character sequence to generate. Default: 8.
218
219       init_oracle_generators
220
221       Create ID generators for the workflow and history tables using the
222       Oracle sequences. No parameters are necessary.
223
224       create_handle
225
226       Creates a database connection using DBI's "connect" method and returns
227       the resulting database handle. Override this method if you want to set
228       different options than the hard-coded ones, or when you want to use a
229       handle from elsewhere.
230
231       The default implementation hard-codes these database handle settings:
232
233           $dbh->{RaiseError} = 1;
234           $dbh->{PrintError} = 0;
235           $dbh->{ChopBlanks} = 1;
236
237       create_workflow
238
239       Serializes a workflow into the persistance entity configured by our
240       workflow.
241
242       Takes a single parameter: a workflow object
243
244       Returns a single value, a id for unique identification of out
245       serialized workflow for possible deserialization.
246
247       fetch_workflow
248
249       Deserializes a workflow from the persistance entity configured by our
250       workflow.
251
252       Takes a single parameter: the unique id assigned to our workflow upon
253       serialization (see "create_workflow").
254
255       Returns a hashref consisting of two keys:
256
257       •   state, the workflows current state
258
259       •   last_update, date indicating last update
260
261       update_workflow
262
263       Updates a serialized workflow in the persistance entity configured by
264       our workflow.
265
266       Takes a single parameter: a workflow object
267
268       Returns: Nothing
269
270       create_history
271
272       Serializes history records associated with a workflow object
273
274       Takes two parameters: a workflow object and an array of workflow
275       history objects
276
277       Returns: provided array of workflow history objects upon success
278
279       fetch_history
280
281       Deserializes history records associated with a workflow object
282
283       Takes a single parameter: a workflow object
284
285       Returns an array of workflow history objects upon success
286
287       commit_transaction ( $wf )
288
289       Commit the transaction for a workflow if autocommit is not enabled.
290
291       Returns nothing
292
293       rollback_transaction
294
295       Rollsback the transaction for a workflow if autocommit is not enabled.
296
297       Returns nothing
298

COPYRIGHT

306       Copyright (c) 2003-2022 Chris Winters. All rights reserved.
307
308       This library is free software; you can redistribute it and/or modify it
309       under the same terms as Perl itself.
310
311       Please see the LICENSE
312

AUTHORS

314       Please see Workflow
315
316
317
318perl v5.36.0                      2023-01-20       Workflow::Persister::DBI(3)