Workday® integration service has pre-built connectors, standardized integration toolkits, and a graphical integration builder designed for business users and analysts in its cloud integration platform. Error-handling in these services is pre-configured and cannot be changed by the user.
The platform also provides Workday® Studio, a graphical developer tool for building sophisticated data integrations and transformations. Workday® studio gives developers control over error-handling. The assembly components in the Studio graphical interface have builtin properties for error handling.
Use Readable Error Messages
One of the most frustrating things in the life of payroll manager, benefits administrator, or reports analyst is to get an error message that doesn’t tell them what went wrong. Give them all the information they need to understand it. In some cases, if the end user has enough information, they will not require support to rectify the problem. You could even tell them whether you want them to resubmit the process or resend only records with errors. Don’t write a novel, but be verbose enough to give them a clear idea of the issue.
Make error messages readable to an ordinary business user, with a clear description of the problem. Where appropriate, identify the data that caused the error. The ExtractRootCause component will help you create meaningful error messages. Be sure to provide the context for your messages so an ordinary business user can communicate with troubleshooters.
For the Workday® support team, set the overall Integration Event status to Failed. Uncaught exceptions automatically set the Integration Event status to Failed.
Catching Errors
In the Workday®-Out Transport, the failure-message property gives you the ability to augment the provided error message if the web service call fails. The original is appended to the failure message you provide.
When you set error handlers for asynchronous and synchronous mediations, use the Handle Downstream Errors property:
- Set the property to false to apply the handler to only the steps within the mediation.
- Set it to true to handle any errors thrown by any other downstream mediations or transports.
The handler will report it to the user in a PutIntegrationMessage and trap or rethrow the error, whichever is appropriate. Use the MVEL expression context.getError() to extract the details.
Global Error Handler
All Integrations should have a global error handler. Link the global error handler to a PutIntegrationMessage step, to post an Integration Message with a severity of “CRITICAL.” (Set the is.message.severity parameter to “CRITICAL.”)
Throwing Errors
MVEL Validations
Steps configured with one or more MVEL expressions that will cause the assembly to throw an error if they evaluate to false. Customize the Validation Message to provide a meaningful message.
XML Validation
Use XML Validation against an XSD schema, but avoid using it for large messages. For large messages, you should always use a splitter before you process your data, then aggregate it or invoke a paged web service. Configure XML validation message using the Failure Message and Replace Message properties.
XPath Validation
XPath can be used to validate a message by applying an XPath expression to it. XPath operations are limited to a 1MB message size. Use streaming for large files.
Manual Validation in Java or MVEL
You can use the context helper variable in Java or MVEL to throw an error:
context.setError(
Description of Error
, 20001);
Avoid Failing the Entire Integration
Do not fail integrations because of a single record error unless there is an explicit requirement. Report single-record issues as an error or warning and continue processing.
Error handling best practices
Validation Rules
Use the Validate Exp step to create readable error messages. These are useful as a way to validate parameters passed to a sub-assembly.
Inbound Integrations
For inbound integrations, there is a possibility that an integration event may not have been created. The error handler should check if an integration event exists and log the error message instead. Wherever possible, the integration should return an error message to the caller.
Alert the Workday® Environment Team
An integration that fails (catches and then rethrows and error) alerts the Environments team who will investigate the error. An error that can be resolved by an end user, the Environments team will let the user know. It may be sufficient to update the Integration Event with details of the error and to fail it.
Validation Steps
Use the XML Schema, MVEL and XPath Validation steps in assemblies to ensure that messages are valid and errors are reported as early as possible. Text Schema also validates messages as part of the transformation.
Summary
Following these practices will save you time and trouble. Your users will appreciate it, and your fellow developers will appreciate, too.
Pixentia is a full-service technology company dedicated to helping clients solve business problems, improve the capability of their people, and achieve better results.
+1 903-306-2430,