NAME

EAI::Common - Common parts for the EAI::Wrap package

SYNOPSIS

 %config .. hash for global config (set in $EAI_WRAP_CONFIG_PATH/site.config, amended with $EAI_WRAP_CONFIG_PATH/additional/*.config)
 %common .. common load configs for the task script
 @loads .. list of hashes defining specific load processes
 %execute .. hash of parameters for current running task script

 readConfigFile ($configfilename)
 getKeyInfo ($prefix, $key, $area)
 setupConfigMerge ()
 getOptions ()
 extractConfigs ($contextSub, $arg, @required)
 checkHash ($hash, $hashName)
 checkParam ($subhash, $hashName)
 setupEAIWrap ()
 dumpFlat ($arg, $sortDump, $compressDump)
 getLogFPathForMail ()
 getLogFPath ()
 MailFilter ()
 setErrSubject ($context)
 setupLogging ()
 checkStartingCond ($task)
 sendGeneralMail ($From, $To, $Cc, $Bcc, $Subject, $Type, $Data, $Encoding, $AttachType, $AttachFile)

DESCRIPTION

EAI::Common contains common used functions for EAI::Wrap. This is for reading config files, setting up the config hierarchy, including commandline options, setting up logging, including callbacks for the log.config, setting the error subject for error mails, checking starting conditions and a generic Mail sending.

API

readConfigFile ($)

read given config file (eval perl code in site.config and related files)

getSensInfo ($$)

arguments are $prefix and $key

get sensitive info from $config{getSensInfo}{$prefix}{$key}, if queried key is a ref to hash, get the key value using the environment lookup hash ($config{sensitive}{$prefix}{$key}{$execute{env}}).

setupConfigMerge

setupConfigMerge creates cascading inheritance of config/DB/File/FTP/process/task settings (lower means more precedence (overriding previously set parameters)):

 %config <-- config options from command line
 - is merged into -->
 %common (common task parameters defined in script) <-- DB, FTP, File, task and process options from command line
 - is merged into -->
 $loads[] <-- DB, FTP, File and process options from command line

getOptions

get options for overriding configured settings, results are stored in globally available hash %opt and list @optloads

extractConfigs ($$$;@)

arguments are $contextSub, $arg and @required.

sets error subject to $contextSub (first argument) and extracts config hashes (DB,FTP,File,process,task) from ref to hash $arg (second argument) and return them as a list of hashes. The config hashes to be extracted are given as strings in the parameter list @required (at least one is required).

checkHash ($$)

arguments are $hash and $hashName

check keys of config subhash (named $hashName) being passed in $hash for validity against internal hash %hashCheck (valid key entries + their valid value types (examples) are defined there). returns 0 on error and exception $@ contains details, to allow for checkHash(..) or {handle exception}.

checkParam ($$)

arguments are $subhash and $hashName

check existence of parameter $hashName within first argument $subhash, returns 0 if not defined or empty (only non-numerics)

setupEAIWrap

Usually this is the first call after the configuration (assignments to %common and @loads) was defined. This sets up the configuration datastructure and merges the hierarchy of configurations. Correctness of the configuration and all conditions preventing the task script's actual starting are also checked; finally all used parameters are written into the initial log line, which is used by the logchecker (see checkLogExist.pl).

following three functions can be used in the central log.config as coderefs for callback.

dumpFlat ($;$$)

arguments are $arg: datastructure to be flat dumped, $sortDump: sort all keys in $arg and $compressDump: compress information in $arg

returns Data::Dumper dumped datastructure given in $arg flattened, sorted (if $sortDump given) and compressed (if $compressDump given)

getLogFPathForMail

for custom conversion specifiers: returns path of configured logfile resp logfile of previous day (as a file:// hyperlink)

getLogFPath

for file appender config, returns the path of current logfile.

MailFilter

for Mail appender config: used for filtering if further mails should be sent, contains throttling flag "alreadySent" for avoiding mail flooding when errors occur.

setErrSubject ($)

argument $context .. text for context of subject

set context specific subject for ErrorMail

setupLogging

set up logging from site.config information (potentially split up using additional configs) and the central log.config. Important configs for logging in the config hash are logRootPath (direct or environment lookup setting for the log root folder), errmailaddress (default address for sending mails in case of error), errmailsubject (subject for error mails, can be changed with setErrSubject), testerrmailaddress (default address for sending mails in case of error in non production environments), smtpServer (for error and other mail sending), smtpTimeout and checkLookup.

checkLookup is both used by checkLogExist.pl and setupLogging. The key is used to lookup the scriptname (inlcuding .pl) + any additionally defined suffix($execute{addToScriptName}) that can be set with $config{executeOnInit}. So, a call of mytask.pl --process interactive_addinfo=add12 interactive_type=type3 interactive_zone=zone4 and a definition $config{executeOnInit} = '$execute{addToScriptName} = $opt{process}{interactive_addinfo}.$opt{process}{interactive_type}.$opt{process}{interactive_zone};' would yield a lookup of mytask.pladd12type3zone4, which should have an existing key in checkLookup, like $config{checkLookup} = {"mytask.pladd12type3zone4" => {...}, ...}.

Each entry of the sub-hash defines defines the errmailaddress to receive error mails and the errmailsubject, the rest is used by checkLogExist.pl.

Explicitly enumerated lookups (1:scriptname.pl, 2:scriptname.pl, etc.) that are required for differentiated treatment in checkLogExist.pl are removed and replaced by one with key scriptname.pl.

checkStartingCond ($)

argument $task .. config information

check starting conditions from process config information and return 1 if met

sendGeneralMail ($$$$$$;$$$$)

arguments are

 $From .. sender
 $To .. recipient
 $Cc .. cc recipient (optional, but need arg)
 $Bcc .. mcc recipient  (optional, but need arg)
 $Subject .. mail subject
 $Data .. the mail body, either plain text or html.
 $Type .. mail mime type (eg text/plain, text/html oder 'multipart/related'), if 'multipart/related', then a ref to array to the filenames (path), that should be attached is expected to be set in $AttachFile. 
 In the above example a mail body ($Data) is being set as the first attachment and its type is text/html. The rest of the attachments from $AttachFile are encoded using base64 and all have mime type AttachType (see below).
 $Encoding .. encoding for mail body, optional (eg quoted-printable)
 $AttachType .. mime type for attachment(s) (eg text/csv or image/png), optional
 $AttachFile .. file name/path(s) for attachment(s), optional (hat to be ref to array, if $Type = 'multipart/related')

send general mail, either simple text or html mails, mails with an attachment or multipart mails for "in-body" attachments (eg pictures). In this case the mail body needs to be HTML, attachments are referred to inside the HTML code and are passed as a ref to array of paths in $AttachFile.

Example:

 # prepare body with refererring to attachments in a HTML table
 my $body='<style>table, th, td {border: 1px solid black;border-collapse: collapse;} th, td {padding: 5px;text-align: right;}}</style>';
 $body.='<table style="width:1600px; border:0; text-align:center;" cellpadding="0" cellspacing="0">
 <tr><td width="800px" height="800px"><img style="display:block;"  width="100%" height="100%" src="cid:relativePathToPic.png" alt="alternateDescriptionOfPic"/></td></tr>';
 # pass needed files to sendGeneralMail:
 my @filelist = glob("*.png");
 sendGeneralMail(undef,'address@somewhere.com',undef,undef,"subject for mail",$body,'multipart/related','quoted-printable','image/png',\@filelist);

COPYRIGHT

Copyright (c) 2024 Roland Kapl

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.