Add Traceability to Your Workday Studio Assemblies

Have you ever had to support a Workday Studio integration that operated as a black box? You get the output, but you have no idea how this output was generated? What do you do when the integration output appears to be incorrect? How do you know whether it’s an issue in the source data, or in a transformation somewhere in the integration?

Is stepping through a Workday Studio integration with the debugger always your only option when there’s a bug or incorrect output and you’re trying to figure out why?

Are you building a Workday Studio integration that is eventually going to be supported by someone else?

If you answered “yes” to any of these questions (and if you are building a Studio integration, you definitely answered “yes” to that last one, even if that someone else is you months later), stay tuned. In this post, I’m going to discuss three tips for adding traceability to your Workday Studio integrations, so that you can follow the data from source to destination, making it easier to debug:

1. Use a document retention policy
2. Show your work
3. Leave breadcrumbs

Use a document retention policy

When you store a document in Workday from a Studio assembly, by default the document will expire in 7 days. In many cases, this is not long enough. How long is long enough? It depends!

You’ll notice that all Workday Core Connectors provide a document retention policy attribute that allows you to configure how long to store the documents generated by the integration within Workday. Your Studio integrations should do this too.

Add a document retention policy integration attribute to your Studio’s workday-in components, and then use that attribute value for setting the Expires In property of any store components.

When I setup a document retention policy attribute on a Studio integration, I tend to accept a number representing the number of days, and then the formula for the Expires In property is fairly simple: @{'P' + props['DocRetentionPolicyDays'] + 'D'}.

With the document retention policy attribute in place, each Studio integration can be set with a policy that’s appropriate for its run frequency.

Show your work

This is the real game changer. This is what transforms your black box integration into something you can inspect after it has run to understand what happened, because what you’re going to do is show your work.

And the trick is to stash intermediate data into an audit zip which your integration will store in Workday before it exits.

About to make a REST or SOAP request to a server? Store the request in the audit zip. Now you have a copy of the exact request that was submitted by the integration, and you can submit that request again yourself without having to reconstruct it first. In some cases, you may even want to store the endpoint or URL you’re sending the request to, especially if it is generated, conditional, or environment-dependent.

Just got a response from a REST or SOAP request? Store the response in the audit zip. Now you might not even need to submit that request again.

About to perform an XSLT transformation on the mediation message? Store a copy of the message both before and after the transformation in the audit zip. Of course, if you’ve just stored a SOAP response, and you’re about to transform that, there’s no need to store it again, but do stash the result of the transformation.

Do you see the pattern here? Stash all the things that change from run to run in the audit zip.

With these intermediate forms of the integration data at hand, you can start to figure out what happened to the data as it went through the integration pipeline, and how the integration ended up with the output, without having to reach for the debugger.

Let’s pretend you’ve found a bug in an XSLT. You now have the input to the XSLT on hand that you can feed in. You can quickly make the change to the XSLT, validate the fix, and compare the result to the result generated during the integration run, without having to re-run the whole integration.

Here are some implementation tips:

• Build the audit zip using an aggregator with the zip-file-collater
• Make two sub-assemblies: one for adding a document to the audit zip, and one for storing the audit zip to Workday. Put these sub-assemblies in their own project so you can re-use this across Studio integrations
• Make sure you store the audit zip before the integration terminates either successfully or due to an error, and don’t forget to have your global error handler store the zip before exiting
• When you store the audit zip on Workday, use a document retention policy

Caveats:

• Mind Workday’s memory and document size limitations — if you’re working with large data sets, you may need to roll your audit zip file to keep the size under control

Leave breadcrumbs

Are you assembling, aggregating, or combining data from different sources into a single document?

Do you have conditional logic that generates data via different branches?

Now that you are showing your work, leave yourself some breadcrumbs by recording the source of the data. A simple @source attribute on an XML node can go a long way.

For example, let’s say you’ve got an XSLT that needs to detect whether a worker was terminated during the current period, and you might detect this in one of two ways:

1. You find a termination event that becomes effective in the current period
2. You find a retro-active termination event that was entered in the current period, but is effective prior to the current period

If you have two if branches, separate when conditions, or separate templates to handle these two cases, leave a breadcrumb in the output that tells you which branch was chosen.

For example, instead of outputting:

<Terminated>
    <Reason>Voluntary</Reason>
    <Effective>2018-08-14</Effective>
</Terminated>

Do this instead:

<Terminated source="retro">
    <Reason>Voluntary</Reason>
    <Effective>2018-08-14</Effective>
</Terminated>

And now you know which branch the XSLT ended up in without having to step through the conditions in your head while looking at the source data, saving time during debugging. The more branches you have, the more useful this tip is.

Need More Help?

If you’re struggling with custom Workday Studio integrations that are difficult to debug or troubleshoot, hopefully these suggestions have given you ideas on how you can improve the traceability of those integrations.