/ 
EAI-Wrap-0.9
River stage zero No dependents
/ EAI::Common

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
getSensInfo
setupConfigMerge
getOptions
extractConfigs
checkHash
setupEAIWrap
getLogFPathForMail
getLogFPath
MailFilter
setupLogging
setErrSubject $context
checkStartingCond $process
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 ($$)

get sensitive info from $config{sensitive}{$prefix}{$key}, arguments are $prefix and $key, depending on queried key being a ref to hash, get the environment lookup hash key value or the value directly

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 ($$$;@)

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 following parameter list @required (at least one is required).

checkHash ($$)

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

checkParam ($$)

check parameter key from second argument within first argument $subhash, returns 0 if not defined or not existing (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 internally and merges the hierarchy of configurations. Correctness of the configuration and starting conditions are also checked, preventing the task script's starting; finally all used parameters are written into the initial log line.

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

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 ($)

set context specific subject for ErrorMail

$context .. text for context of subject
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 + any additional defined interactive options, which are being passed to the script in an alphabetically sorted manner. So, a call of mytask.pl --process interactive_addinfo=add12 interactive_type=type3 interactive_zone=zone4 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.

checkStartingCond ($)

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

$task .. config information
sendGeneralMail ($$$$$$;$$$$)

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);

parameters for sendGeneralMail

$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')

COPYRIGHT

Copyright (c) 2023 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.