Event Script Walkthrough

This post is a deeper dive into the previous Event script for logging events and errors. The script produces Operation logs based on a $LOG.level value. Also, it provides for log value labels and categorizing your log entries. Finally, one can email individual logged events to configured recipients. When emailed, the mail content includes a boilerplate table showing Jitterbit details.
// Event is a utility script to log an event -- it wraps WriteToOperationLog() and a good // replacement for using WriteToOperationLog() directly. It provides parameters to control and // get alerts to “events” in the Operation Log. // In particular, it offers the following features: // o Allows use of "extensive logging" with controllable runtime verbosity using $LOG.level // o Optional alternative notification or logging // o Immediate email notification upon event // o Configurable fields to record categories like "type" and "category" // o Jitterbit File Target to write appendable logs to a file // o A standardized prefix on each logged event (Operation name, type and category) // Uses Script "Initialize LOG.severity to declare your own log level hierarchy // For example, using default $LOG.severity array (see Script Initialize Log.severity): // LOG.level Message Codes Seen // Debug [0..7] (ALL) // Informational [1..7] (All but "Debug") // Notice [2..7] (.. // Warning [3..7] // Error [4..7] // Critical [5..7] // Alert [6..7] ..) // Emergency 7 (See only Event messages with event code 7) // Note, arguments cannot be skipped; use "" for unused arguments "between used arguments". // That is, trailing empty arguments can be ignored and not provided _event_code = Int(_1); //[0..?] _event_type = _2; //anything really, typically the severity corresponding to the _event_code _event_msg = IfEmpty(_3, //optional IfEmpty(GetLastError(), // within On Failure Op or after a failed RunOperation() IfEmpty($jittrbit.operation.previous_error, "NO EVENT MESSAGE OR PREVIOUS VALUE/ERROR AVAILABLE") )); _send_event = Bool(IfEmpty(_4, false)); //optional, needs configuration below _event_category = _5; //optional, perhaps for future event sorting //file = IfEmpty(_6,$LOG.filename); //Target filename global variable name; configuration below //If(file && RegExMatch(file,"(^[0-9a-zA-Z\^\&\'\@\{\}\[\]\,\$\=\!\-\#\(\)\.\%\+\~\_ ]+$)")!=1, // RaiseError("Invalid filename value chosen for Event logging to file: "+Quote(file)); //); RunScript("<TAG>Scripts/Utilities/Initialize Log.severity Array</TAG>"); helperArr = Array(); i=0; While(i<Length($LOG.severity[_event_code]), Set(helperArr,i,-1); i++); $jitterbit.operation.name=IfEmpty($jitterbit.operation.name,"NO OPERATION NAME AVAILABLE"); severityLevel = FindValue($LOG.level, $LOG.severity[_event_code], helperArr); If(!IsNull(severityLevel), // level is within desired $LOG.level type = msg = $jitterbit.operation.name+": "+ _event_type + " :: "; // Event type msg += If(!IsNull(_event_category),_event_category+" :: "); // Event category msg += _event_msg + "\n"; // Operation message $EVENT.msg=msg; outcome=""; //initialize message and outcome $EVENT.env = GetEnvironmentName() +' '+ToUpper($LOG.severity[_event_code][Length($LOG.severity[_event_code])-severityLevel-1]); $Event.op = IfEmpty($Event.op,$jitterbit.operation.name); If(Bool($EMAIL.text)==True, If(_send_event && (outcome=SendEmailMessage("<TAG>Email Messages/TEXT Event</TAG>")) != "", $EVENT.bp = RunScript("<TAG>Scripts/Utilities/Log Environment</TAG>"); $EVENT.msg.email = $EVENT.msg +'\n'+ $%EVENT.host; outcome="Email Notification of EVENT/ERROR (" + type + ") failed: " + outcome + "\nEmail Message Body:\n"; ); , If(_send_event && (outcome=SendEmailMessage("<TAG>Email Messages/HTML Event</TAG>")) != "", $EVENT.bp = RunScript("<TAG>Scripts/Utilities/Build EVENT.bp</TAG>"); $EVENT.msg.email = RegExReplace($EVENT.msg,'\r?\n','<br>') +'<br><br>'+ $%EVENT.host; outcome="Email Notification of EVENT/ERROR (" + type + ") failed: " + outcome + "\nEmail Message Body:\n"; ); ); // If(!IsNull(file) && Length(file)>0, // WriteFile("<TAG>Targets/Job Logs/Event Log</TAG>", outcome+$EVENT.msg) // ); If(_send_event, WriteToOperationLog("Email sent/outcome..\n"+outcome+$EVENT.msg); , WriteToOperationLog($EVENT.msg) ); );
These are the possible parameters for the Event script.
_event_code = Int(_1); //[0..?] _event_type = _2; //anything really, typically the severity corresponding to the _event_code _event_msg = IfEmpty(_3, //optional IfEmpty(GetLastError(), // within On Failure Op or after a failed RunOperation() IfEmpty($jittrbit.operation.previous_error, "NO EVENT MESSAGE OR PREVIOUS VALUE/ERROR AVAILABLE") )); _send_event = Bool(IfEmpty(_4, false)); //optional, needs configuration below _event_category = _5; //optional, perhaps for future event sorting
_event_code: the numerical log severity level for this event. See the $Log.severity array configured in script “Initialize Log.severity Array” and initialized on line 34.
_event_type: a string value for the message inserted into the Operation log. As stated in the comment, this can be the corresponding string for the _event_code but is typically interpreted as a label for the _event_msg.
Appears as :: _event_type :: _event_msg
_event_msg: the desired message string to appear in the Operation Log (may also be included in email per _send_event)
_send_event: boolean to indicate whether to send email (default, false) in addition to the entry in the Operation log.
_event_category: an additional “category” that might provide further event detail or for event sorting.
Appears as :: _event_type :: _event_category :: _event_msg
The following commented lines are used to produce a cumulative Operation log file for an entire Operation execution. Useful if needing all Operation events in one file.
//file = IfEmpty(_6,$LOG.filename); //Target filename global variable name; configuration below //If(file && RegExMatch(file,"(^[0-9a-zA-Z\^\&\'\@\{\}\[\]\,\$\=\!\-\#\(\)\.\%\+\~\_ ]+$)")!=1, // RaiseError("Invalid filename value chosen for Event logging to file: "+Quote(file)); //);
Now initialize the $LOG.severity array below.
RunScript("<TAG>Scripts/Utilities/Initialize Log.severity Array</TAG>");
Define this array to your liking within the Initialize Log.severity Array script.
Define the helper array of use with FindValue() further below.
helperArr = Array(); i=0; While(i<Length($LOG.severity[_event_code]), Set(helperArr,i,-1); i++);
This allows searching arrays as shown in a previous post.
Declare default for $jitterbit.operation.name variable.
$jitterbit.operation.name=IfEmpty($jitterbit.operation.name,"NO OPERATION NAME AVAILABLE");
Only log a message if the _event_code value is at or below the $LOG.level project variable value.
severityLevel=FindValue($LOG.level, $LOG.severity[_event_code], helperArr); If(!IsNull(severityLevel),
Now construct the event message based on provided parameters or previous Jitterbit error.
type = msg = $jitterbit.operation.name+": "+ _event_type + " :: "; // Event type msg += If(!IsNull(_event_category),_event_category+" :: "); // Event category msg += _event_msg + "\n"; // Operation message $EVENT.msg=msg; outcome=""; //initialize message and outcome $EVENT.env = GetEnvironmentName() +' '+ToUpper($LOG.severity[_event_code][Length($LOG.severity[_event_code])-severityLevel-1]); $Event.op = IfEmpty($Event.op,$jitterbit.operation.name);
If a project variable named $EMAIL.text has a value of “True” (as recognized by Jitterbit –see Bool()), assume the email is only text-based.
If(Bool($EMAIL.text)==True,
Otherwise, assume email supports HTML content. If _send_event is true, email the event message using “HTML Event” email message component.
, If(_send_event && (outcome=SendEmailMessage("<TAG>Email Messages/HTML Event</TAG>")) != "", $EVENT.bp = RunScript("<TAG>Scripts/Utilities/Build EVENT.bp</TAG>"); $EVENT.msg.email = RegExReplace($EVENT.msg,'\r?\n','<br>') +'<br><br>'+ $%EVENT.host; outcome="Email Notification of EVENT/ERROR (" + type + ") failed: " + outcome + "\nEmail Message Body:\n"; );
Amends a boilerplate (Log Environment or Build EVENT.bp) containing environment details to the email body. See the HTML Email post for details on these scripts.
Notice, the outcome of SendEmailMessage() is tested in case the email fails. The outcome variable contains any emailing issue(s).
The following (if enabled/uncommented with lines 35-38) will append the content of the Job Logs/Event Log target.
// If(!IsNull(file) && Length(file)>0, // WriteFile("<TAG>Targets/Job Logs/Event Log</TAG>", outcome+$EVENT.msg) // );
This target could be an Email target and content provided as an attachment.
Finally, write the event message to the Operation log (including any email trouble).
If(_send_event, WriteToOperationLog("Email sent/outcome..\n"+outcome+$EVENT.msg); , WriteToOperationLog($EVENT.msg) );
Here’s the default “Initialize Log.severity Array” Script.
Initialize Log.severity Array
// By defining a LOG.severity array below and declaring a LOG.level (Jitterbit Project Variable!) value, // one can control the verbosity of the logging that occurs during pipeline execution. This way, // logging using the Event Script can be dynamically "controlled" at runtime while liberally calling // the Event Script throughout the implementation. This strategy permits the separation of the log // message "run-time generation" from the preferred logging requirements within the implementation. // For example, you may want to see many logged events during development --or during production // troubleshooting --but normal production execution may not require this level of logging. By leveraging // this strategy, one can dynamically control the amount of logging that occurs in the Operation logs; // using a LOG.level project variable or change the value for only certain portions of a data pipeline. //The following is an example array (of arrays) for confirming event log "generation" based upon $LOG.level $LOG.severity = {{"Debug","Informational","Notice","Warning","Error","Critical","Alert","Emergency"}, //code 0 {"Debug","Informational","Notice","Warning","Error","Critical","Alert"}, //code 1 {"Debug","Informational","Notice","Warning","Error","Critical"}, //code 2 {"Debug","Informational","Notice","Warning","Error"}, //code 3 {"Debug","Informational","Notice","Warning"}, //code 4 {"Debug","Informational","Notice"}, //code 5 {"Debug","Informational"}, //code 6 {"Debug"} //code 7 }; // In the above case, a LOG.level of "Debug" will log ALL message-type severities (it appears in all arrays) // while "Emergency" will only log messages declared as an "Emergency" message type (only appears once) // An example use for the above two LOG.level values might be: // RunScript("Scripts/Handlers/Event</TAG>",7,"Debug Type","Some runtime value to examine:"+$varName); // or // RunScript("<TAG>Scripts/Handlers/Event</TAG>",0,"Emergency Type",GetLastError()); // One can replace the above LOG.severity array with a more desirable array (perhaps with fewer levels) as needed // Below we initialize the LOG.level value to Emergency in case it's not declared in Project Variable or elsewhere. $LOG.level = IfEmpty($LOG.level, WriteToOperationLog("Using $LOG.level=Emergency"); "Emergency");
No Comments