As software developers explore and customize ubiquitous ERPs like Workday, as well as content management systems which are designed to output the same content in multiple forms, (such as PDFs and web pages) they will find that these systems rely heavily on Extensible Stylesheet Language Transformation (XSLT) technology for such endeavors.
While a developer can use the XSLT functionality within these applications for development and testing purposes, that developer will discover very quickly that this is not ideal. Depending on the system, it can take many minutes for an XSLT process to run. While this is perfectly suited for background or on-demand production tasks, it definitely is not suited for software development, as waiting 10 minutes to discover that there exists a “simple” syntax error in an XSLT page can get annoying and frustrating very easily.
This frustration can be compounded when far too many online resources or developer tools only provide a limited subset of XSLT processing, and none of these under any circumstances are suitable for working with confidential information that can be stored in these systems.
Given the generally steep learning curve associated with mastering XSL, it may not be obvious to developers that effective tools do exist to help mitigate these problems. Additionally, the cost of professional-grade XML/XSL development tools may be “a bridge too far” for some smaller coding shops.
Read: XML Processing in Java EE
Enter Saxon: An XSLT Tool
Saxonica is a company which produces Saxon, which in part provides a robust cross-platform XSLT solution. One of their offerings is an open-source implementation which can provide a significant amount of the functionality needed to debug and hasten development of XSLT pages that are used in other applications. The offering that is the focus of this article is the HE (Home Edition) version, which is the previously mentioned open-source implementation.
Saxon is “the real deal” with regards to XSLT, so much so that most commercial XML/XSL editing software, as well as other software which leverages XSLT internally, use Saxon as part of their applications.
Important note: Saxon also offers commercial software products, and as such, it is crucial to investigate and resolve any licensing questions regarding its use within any such software solution.
Software Requirements for Saxon
As it is the Java version of the Saxon library that is the most robust, it is imperative to have the most up to date version of the Java Runtime Environment (JRE) installed. For Windows, this can be downloaded from Oracle directly. For MacOS, Java is included in Xcode. For Linux, Java is best installed and updated via a given distribution’s preferred package manager.
A text editor, code editor, or integrated development environment (IDE) is also required. A decent option for Windows is Notepad++.
Read: The Top Java IDEs
How Do I Install Saxonica?
The HE version of Saxon is hosted on SourceForge and it doesn’t include an installer. At the time of this writing, the most current version of Saxon HE for Java is 10.6 and it is distributed as a ZIP archive. As a best practice, the best place to copy this software is a common directory that is accessible by all users:
For Windows, this could be:
“C:\Program Files\Saxon”
For MacOSX or Linux, this could be:
“/usr/local/lib/Saxon”
Copy the entire contents of the .ZIP archive into whatever directory is appropriate. Per the license agreement, no part of the software is supposed to be separated from the package; however, the only file from the package that will be accessed is the saxon-he-10.6.jar file.
Application-Specific Saxon and XSLT Examples
A few important notes before we begin:
- It is presumed that the reader has some Workday Integration development experience.
- Data files generated within Workday, and often do, contain sensitive information such as Social Security Numbers, bank account numbers and other kinds of PII. Make sure that all security precautions are observed when working with such files, and securely delete these once the work is done.
- It is presumed that the reader has some Workday Integration development experience.
Data files generated within Workday, and often do, contain sensitive information such as Social Security Numbers, bank account numbers and other kinds of PII. Make sure that all security precautions are observed when working with such files, and securely delete these once the work is done. - The examples below can be repeated as many times as needed until the software development process is complete and the outputs are acceptable. The XSL pages can then be reinserted into the original application and then be run “normally” as per that application dictates.
Workday Enterprise Integration Builder (EIBs) Example
A typical Workday Enterprise Integration Builder consists of a Workday Report whose output is then plugged into a “Custom Transformation” which most often takes the form of an XSL page. When these EIBs are run, the entire process is consolidated into a single action and if it is successful, the final output is generated and possibly transferred to another location. Workday EIBs can also make use of Data Transformations (DTs) to accomplish the same task, but using a different process within Workday.
Fortunately, both types of translations can be easily mapped to an invocation of the Saxon library from the command line.
How to Get the Source XML from the Workday Report
In order to access the XML of a specific instance of a Workday Report, it is necessary for the Report to be Web Service enabled. This can be configured when the report is created, or under the “Advanced” tab in the Report screen, with the “Enable as Web Service” option checked.
With the Report properly configured, the easiest way to obtain the XML that is being used by an existing EIB is to invoke an instance of that EIB with the desired Integration System Prompt values. The XML that is generated by the underlying report will then be included in the output files.
Important note: Depending on the Integration System’s document retention settings, it may not be possible to get the source XML file.
Important Note: If the Integration System must be re-run, ensure that the Delivery Settings are properly configured so that output files are not inadvertently transferred to an external system.
Also note the following:
- Depending on the Integration System’s document retention settings, it may not be possible to get the source XML file.
- If the Integration System must be re-run, ensure that the Delivery Settings are properly configured so that output files are not inadvertently transferred to an external system.
It is also possible to invoke a specific instance of the report itself by browsing to the REST Workday URL and specifying values for the Prompts in this manner, but this divorces the invocation of the Report from the Integration, and it may cause confusion or other problems during the Integration development process.
Once both the XML and XSL files are in hand, the latter can be edited on the local computer and Saxonica invoked as follows, with the assumption that the JRE is accessible via the System Path, and that the XML and XSL files are in the same directory together.
For Windows:
C:\Users\philh>java -jar "c:\program files\Saxon\saxon-he-10.6.jar" -s:workday-source.xml -xsl:developer-provided.xsl -o:output-file.csv
For Mac OSX or Linux:
$ java -jar /usr/local/lib/Saxon/saxon-he-10.6.jar -s:workday-source.xml -xsl:developer-provided.xsl -o:output-file.csv
Note that the output file of course will not always be a CSV file and the paths to the files may need to be properly escaped as well.
The process can be repeated for as often is needed in order to complete the software development process.
Read: Working with XML Files in Go
Workday Benefits Connectors
Functionally, while Reports normally are not used for Benefits Connectors, these process XSLT no differently than EIBs, except for the possibility of there being more than one transformation as part of their respective Business Processes. It is critical to replicate all of these transformations in order to properly mimic the complete transformation process. Additionally, the final transformation process may not necessarily be what creates the final output, meaning that a custom-developed XSL page may be needed to mimic the final process within Workday (for instance, if an XTT-formatted file is the second-to-last XSLT in the Benefit Connector’s Business Process, then an XSL which isn’t used by Workday may be needed to convert that file into a CSV file or other final data output).
Each Data Transformation will store its XSL page in its associated Integration Attachment Service. It will be necessary to grab all of the XSL files associated with each Data Transformation that is configured in the Business Process. The examples below assume that there is a single Data Transformation which will create an XTT-formatted file, and that a final xtt-to-csv XSL file will be used to transform that output into the final data format.
When working with Saxon, each transformation can be performed in a separate step:
C:\Users\philh>java -jar "c:\program files\Saxon\saxon-he-10.6.jar" -s:workday-source.xml -xsl:xsl-from-dt.xsl -o:output-file-1.xml C:\Users\philh>java -jar "c:\program files\Saxon\saxon-he-10.6.jar" -s:output-file-1.xml -xsl:xtt-to-csv.xsl -o:final-output-file-1.csv
Or, in Mac OSX or Linux:
$ java -jar /usr/local/lib/Saxon/saxon-he-10.6.jar -s:workday-source.xml -xsl:xsl-from-dt.xsl -o:output-file-1.xml $ java -jar /usr/local/lib/Saxon/saxon-he-10.6.jar -s:output-file-1.xml -xsl:xtt-to-csv.xsl -o:final-output-file-1.csv
Below is a sample listing of code which can convert XTT-formatted data into a CSV file:
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:bc="urn:com.workday/bc" exclude-result-prefixes="xs" version="2.0"> <xsl:strip-space elements="*"/> <!-- Removes extra whitespace from output. --> <xsl:output method="text" indent='no' /> <!-- Use the xsl:text attribute to prevent extra spaces/line breaks from being inserted. --> <xsl:variable name='single-quote' select="'"'" /> <xsl:variable name='double-quote' select="'""'" /> <!-- Within CSV files, any quotation mark within a column needs to be replaced with 2 quotation marks, as column values are delimited by single quotation mark. --> <xsl:template match='/bc:Sample-BO/OutRecord'> <xsl:value-of select="$single-quote"/> <xsl:value-of select="replace(First-Column, $single-quote, $double-quote)"/> <xsl:value-of select="$single-quote"/> <xsl:value-of select="','"/> <xsl:value-of select="$single-quote"/> <xsl:value-of select="replace(Second-Column, $single-quote, $double-quote)"/> <xsl:value-of select="$single-quote"/> <xsl:value-of select="','"/> <xsl:value-of select="$single-quote"/> <xsl:value-of select="replace(Third-Column, $single-quote, $double-quote)"/> <xsl:value-of select="$single-quote"/> <!-- <xsl:value-of select="','"/> <xsl:value-of select="$single-quote"/> Extra Columns Here <xsl:value-of select="$single-quote"/> --> <xsl:text>
</xsl:text> <!-- Newline. --> </xsl:template> </xsl:stylesheet>
XSL-driven Web Pages with Saxon
XSL-driven web pages are so common these days that it is possible to not remember a time when one could simply use the “View Source” functionality in a browser to actually see the rendered HTML. While every modern desktop browser these days has “Developer Tools” which can display the rendered HTML for a web page one node at a time, Saxon can show all of the rendered HTML in a single file. This can be useful if the page being debugged has multiple issues, or if one sees the dreaded “completely blank” page with no errors in the web console, which is indicative of a transformation failure for any reason.
Note, it is presumed that the reader has some XML/XSL to HTML development experience before trying to tackle the following sections.
The syntax, of course, remains the same:
For Windows:
C:\Users\philh>java -jar "c:\program files\Saxon\saxon-he-10.6.jar" -s:web-source.xml -xsl:developer-provided.xsl -o:output-file.html
For Mac OSX or Linux:
$ java -jar /usr/local/lib/Saxon/saxon-he-10.6.jar -s:web-source.xml -xsl:developer-provided.xsl -o:output-file.html
This can get very interesting if any sort of server-side scripting is used. Typically, the server-side scripting is done before the XSLT is performed, as the latter is done in the browser. If the server-side scripting fails and returns any text which breaks the XML that is coming to the browser, then that infamous “blank screen of doom” will appear.
As a best practice, it is best to comment out the server-side portions of the originating page. If the page renders, then each bit of the server side code can be uncommented out until the page goes blank again, and at that point is where the debugging can begin.
Conclusion to Saxon XSL Transformations Tutorial
XML/XSL development need not be relegated to the realm of expensive software. The Saxon library provides a “free” but very powerful, platform agnostic and robust tool for XSL development and debugging. It should be a part of every developer’s arsenal.
