A common problem to be solved is how to alert users about integration issues as well as how to handle errors, and log data to aid in troubleshooting. Since these topics are tightly linked, we'll address them together.
The problem is that middleware is typically a behind-the-scenes process, and needs to be instrumented such that it self reports errors or critical data. Otherwise a user is in a reactive mode, usually after a problem occurs, and is caught unawares that there is an issue. Far preferable is for the middleware to be configured to alert a user or other system based on rules. The most common rule is to alert on an error, but that is not the only scenario. Alerts can be for thresholds reached, health checks, or business-critical information.
A common pattern is to identify expected error scenarios, send a short alert (usually email) and log information in greater detail.
Jitterbit's main alerting method is via email, and is configured using the Email Messages, similar to an Endpoint. Basically, Jitterbit is acting as an SMTP client and therefore must be connected to a host.
With a configured Email Message, there are several script functions that can be used to instrument alerting. Here, we use SendEmailMessage if NetSuite could not insert the record. See Email Functions for more detail.
If you want to send an attachment, a Send Email with Attachment plug-in is available.
There are integration scenarios where the number of error cases exceed the success cases, but it is reasonable to focus on the expected error scenarios during development, and add more error handling functionality as modifications after go-live.
Not all error cases require alerts, but generally do require the error to be captured and logged to aid in troubleshooting. Generally speaking, errors come in two varieties: Operation failures, and data-driven errors. The major distinction is based on the source: Operation failures are from Jitterbit itself, while data-driven errors are sourced from the endpoint and Jitterbit is simply passing it along.
Operation failure is straightforward and easy to implement, where an email message is attached to an operation and is sent if there is an operation-level failure from the Jitterbit Agent. An example is if an endpoint, like a database, is unreachable by the Agent, and a failure is returned.
Data Driven Errors
Typical data driven scenarios include:
- Messages or status indications from the endpoint.
- Custom data validation
Missing Data or schema mis-match
Related closely to Alerting is Logging. Jitterbit logs operation-level information automatically. In some cases, like SFDC wizard-built operations, Jitterbit writes failure messages to the log.
A common point of confusion is how to identify the source of the error message as well as the message itself.
For example, this error is from a database:
An example from NetSuite:
An example from Salesforce:
An example from Jitterbit itself:
Additional logging can be added to record key data as an aid to troubleshooting. Key data can be:
- The results of a lookup in another system
- New record IDs
- If using a condition to filter out certain records, you can write out the the input and output calculations
The main function to use is the WriteToOperationLog() function, as in
WriteToOperationLog("Error returned is: " + ...);.
Output Operation Log
Last updated: Oct 04, 2019