NAME

Liz::TrackSet - Track emails sent with Liz::Mail and Liz::BulkMail


SYNOPSIS

 use Liz::TrackSet;

 $file = new Liz::TrackSet;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::TrackSet;


DESCRIPTION

The Liz::TrackSet package allows for very simple storage of sets of records related to sending and returning of email.


Incorporate into Client Module

The Liz::TrackSet module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.

Take for example the TrackSet method of HN.pm module:

 sub TrackSet {

 # Obtain the parameters
 # Start the file using the $hn handle as the database handle
 # Return the finished object

 my( $hn,$token ) = @_;
 my( $trackset ) = Liz::TrackSet->new( $token,$hn );
 $trackset;
 }

Because of the above code in HN.pm, it is now possible to write the following code:

 $hn = new HN;
 $trackset = $hn->TrackSet( 'technology' );

Note that the database connection of the file is hidden in the creation of the $hn object.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::TrackSet->method().


tracksets

Return list of file identification names of all tracksets in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 wildcard specification to match
   (default: all)
Output Parameters

 1 reference to list of identification names in the current database
 2 reference to hash with full names
Example

 $hn = new HN;
 ($id,$name) = $hn->TrackSets;
 $tracksets = @{$id};
 print "All $tracksets tracksets in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " TrackSet '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub TrackSets { Liz::TrackSet->tracksets( @_ ) }


new

Create a new Liz::TrackSet object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 identification name of file set
   (default: default file set for database)
Output Parameters

 1 instantiated object
 2 flag whether TrackSet was just created
Example

 $hn = new HN;
 $trackset = $hn->TrackSet( 'technology' );

In HN.pm:

 sub TrackSet { Liz::TrackSet->new( @_ ) }


reset

Delete all tables of the TrackSet object. Please use this with caution, as it will destroy any information that is stored for this TrackSet. If called in a void context, no tables exist for this TrackSet anymore, and any references in the NextID table are also removed. Otherwise, the tables will be re-created automatically and a new object will be returned, just as if the new method was called.

Output Parameters

 1 newly created TrackSet object, current object will not work anymore
Example

 $trackset->reset;
Example

 $trackset = $trackset->reset;


CONTENT METHODS

The following methods allow changes to information that is associated with an entire trackset.


EncryptionKey

Specify or return the non-standard encryption key of the trackset object. The encryption key can be any string. It is used to encrypt tracking information into the email header, so that it is less obvious to receivers what the information actually is.

If there is no encryption key known for the TrackSet, a default encryption key will be used.

Input Parameters

 1 new encryption key of trackset
   (default: no change)
Output Parameters

 1 current/old encryption key of trackset
Example

 $xxlink = new xxLINK;
 $trackset = $xxlink->TrackSet( 'eurest' );
 $trackset->EncryptionKey( 'secret' );
Note

Please note that the encryption key used must remain the same for the lifetime of a TrackSet. A change in the EncryptionKey will make all emails sent before the change untrackable.


ExpireAfter

Specify or return the number of minutes after which a record in the trackset should expire. Records that expire will be removed from the trackset without any further ado.

If there is no expiration time known, a default of one week (7*24*60 = 10080 minutes) will be assumed.

Input Parameters

 1 new number of minutes to expire after
   (default: no change)
Output Parameters

 1 current/old number of minutes to expire after
Example

 $xxlink = new xxLINK;
 $trackset = $xxlink->TrackSet( 'eurest' );
 $trackset->ExpireAfter( 14*24*60 );


Name

Specify or return the current name of the trackset object. The name can be anything to further identify the goal of the trackset.

Input Parameters

 1 new name of trackset
   (default: no change)
Output Parameters

 1 current/old name of trackset
Example

 $xxlink = new xxLINK;
 $trackset = $xxlink->TrackSet( 'eurest' );
 $trackset->Name( 'Eurestjes' );


TRACK METHODS

The following methods allow changes to a single record in a TrackSet.


delete

Delete a specific Liz::TrackSet::Record object from the database.

Input Parameters

 1..N identifiers of the Liz::TrackSet::Record to be deleted
Output Parameters

 1    flag: whether action was successful
Example

 $record->delete;


Record

Create a new Liz::TrackSet::Record object, either from existing information or for a new entry. For more documentation, see the Liz::TrackSet::Record object itself.

Input Parameters

 1 identifying string to create Record object with
   (default: none = new record)
Output Parameters

 1 instantiated Record object
Example

 $hn = new HN;
 $trackset = $hn->TrackSet( 'technology' );

 $record = $trackset->Record;
 $record = $trackset->Record( $identifier );


List

Return an SQL statement handle for a list of records.

The following fields may be specified with the 2nd parameter:

 identifier
 The unique identifier of the record

 created
 Timestamp value when this record was created

 updated
 Timestamp when the record was last updated

 expired
 Timestamp when the record is to be expired

 externalID
 ID to which this record is associated

 options
 Options associated with the record
Input Parameters

 1 fields to return (comma delimited)
   (default: 'identifier,created,updated,expired,externalID,options' );
 2 fieldname on which to order the result
   (default: 'created')
 3 extra condition to be applied
   (default: none)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


MAIL METHODS

The following methods are associated with the Liz::Mail and Liz::BulkMail packages for sending and receiving mail.


Track

Send an email from a Liz::Mail object, or a whole batch of emails from a Liz::BulkMail object. Add identifying parameters to each email sent, so that returned emails can be tracked and dealt with.

Input Parameters

 1    Liz::(Bulk)Mail object to send email(s) of
 2    options to apply to all TrackSet records made this time
      (default: none)
 3    method to be executed on the object
      (default: 'send')
 4..N parameters to be passed to the method
Output Parameters

 1..N output parameters from Liz::(Bulk)Mail->$method
Example

 $trackset->Track( $mail );
 $trackset->Track( $bulkmail,'O','sendbg' );


receive

Receive an email either as a Liz::Mail object, or from STDIN. Look for information that would indicate it is a bounced mail, or a reply to a mail previously sent and tracked with this module. Return the identifier of the Liz::TrackSet::Record object to which the mail is associated if possible. Optionally return the Liz::Mail object that was possibly created also.

Can be called as a either a class method or as an object method. When called as a class method, the second input parameter must be specified with the value of the EncryptionKey if a non-standard encryption key was used.

Input Parameters

 1 email to be processed (as a Liz::Mail object or as text)
   (default: everything that can be read from STDIN)
 2 encryption key to be used
   (default: Trackset's encryption key, must be specified if called as class method)
Output Parameters

 1 Liz::Mail object that was possibly created (otherwise same as input parameter)
 2 identifier of the Liz::TrackSet::Record object found in subject
 3 identifier of the Liz::TrackSet::Record object in header
 4 external ID found in identifier
 5 Liz::TrackSet token found in identifier
 6 client module found in identifier
Example

 $client = new Client;
 $trackset = $client->TrackSet;
 ($mail,$identifier) = $trackset->receive;


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.12, 3 December 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method receive.

Version 0.11, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Record.

Version 0.10, 30 September 1999

First version of this true Perl module. Copied from the Liz::EventSet module, which is less specific than this.