Balisage Paper: ACS Publications — Ensuring XML Quality

Introduction to ACS

ACS is a professional membership organization, chartered by the U.S. Congress in 1876, representing over 164,000 professionals at all degree levels and in all fields of chemistry and sciences that involve chemistry. Primary ACS divisions include Membership and Programs; Chemical Abstracts Service, a secondary publisher of chemical-related data, information abstracts, and databases; and the Publications Division (“ACS Pubs”).

The ACS Manuscript Workflow

The Journal and Book publishing units of ACS Pubs produces over forty STM peer-reviewed journals focused on various disciplines of chemistry. In 2012, ACS Pubs expects to publish about 325,000 pages in approximately 40,000 articles (manuscripts).

Chemists from around the world document their research results and submit manuscripts to ACS of their findings for peer review and publication. Once a manuscript has been reviewed and accepted for publication, ACS receives it in the document format submitted by the author (Microsoft Word or LaTeX, for example). ACS has standardized on XML as the internal manuscript format and uses an “XML-first” approach to facilitate the production and publication processes. Therefore, before any processing occurs, the author’s original document is sent to a vendor for conversion into XML, using a DTD that is a customized version of the NLM article DTD. (See ACS Tagsets.)

After the manuscript is converted to XML, ACS staff that have Chemistry or related scientific degrees (“Technical Editors”) prepare it for publication, editing the paper for clarity and technical content (see ACS Style Guide) and ensuring proper markup of content. A proof version of the manuscript is sent to the author (in PDF format) for their review and the author’s corrections are applied before it is published on the ACS Publications web site and also in print. The composition process of journal manuscripts (proof, web, and print PDFs) has recently been automated (see ACS Automated Composition), with great success. The high-level of quality of the XML input to the composition engine is critical to the successful composition results.

This is a simplified narrative of our workflow (see Figure 1). The actual workflow is, of course, much more involved.

Figure 1: ACS XML Workflow Overview

High-level overview of the ACS manuscript workflow.

Why XML Quality is Critical

All of the processing that takes place on the text of each manuscript is performed after its conversion into XML. Technical Editors use a customized XML editor when they edit the manuscript, and all of the tools which automate the processing of manuscripts expect and require XML input. The quality of this XML is critical to the successful completion of each of these tools. A manuscript in XML format must be properly tagged so that it can be parsed. This is easily checked using the DTD. If all required document elements are present in the XML, and the contents of each of the document elements are valid within their context, then a manuscript has an acceptable quality level for our automation tools. As an example, our tools cannot understand a Publication Year with a value of “next year or maybe the year after”. Documents with invalid tagging or content require manual intervention to be processed for publication. Given the sheer quantity of XML processed daily at ACS, manual intervention must be a very tiny exception to keep production costs down and time-to-publication intervals competitive.

To enhance the quality of the XML tagging and contents of each manuscript, validation tools and tools that perform automatic content and tagging changes (“edits”) were developed internally by ACS staff. The validation tools are run before the initial version of the XML content is accepted from the vendor, and again between most workflow stages. The automatic content and tagging edits are performed before and after the Technical Editors edit the manuscript.

Validations (Quality Enforced)

There are hundreds of custom validations that are performed on each manuscript. Validations are typically executed as a manuscript transitions from one workflow stage to the next. Individual validation checks are collected in logical groups, and those logical groups of validations are executed by controllers that focus on the workflow stage of the manuscript.

Some validation requests occur independently of workflow transitions. The vendor who converts the manuscript from the author’s original document format into XML executes some of our content validations before sending us the converted manuscript. Technical Editors may execute our validations directly within their XML editor (Arbortext) to check the validity of a manuscript before they attempt to promote it. Because validation requests come from a variety of sources, a web service was developed as a common entry point for execution of validations (Figure 2).

Figure 2: ACS Manuscript XML Validation Architecture

Validations may be called “on demand” by individual users or by workflow tools. The particular Validation Controller is specified as a parameter to the web service request.

Validation violations, which indicate invalid XML tagging or invalid content, are categorized into three severities: warnings, errors, and fatal errors. Severe validation violations may prevent a manuscript from proceeding to the next workflow stage, which would require manual intervention. This is dependent on the particular stage, however. Violations that would halt processing at one point might be tolerated at a different point, particularly if a following stage of processing will involve staff interaction with the manuscript.

When a violation is detected, details are enclosed in a “processing-comment” element that contains a custom message for the violation. See the example: Violation Message. That element is inserted into the manuscript XML. If possible, it is inserted close to the location where the violation occurred. If the violation is not location-specific within the XML, the message element is placed close to the top of the XML document. Validation violation messages are interpreted by staff who take the appropriate corrective action. Violation messages are removed automatically when a manuscript “passes” validations and moves along in the workflow.

If a severe violation exists in the new converted manuscript XML that is sent from the vendor, it is automatically rejected back to the vendor. Both the vendor and ACS receive notifications of the rejections so that we can track any chronic issues and also ensure that the violations are corrected and the manuscript is resent.

ACS utilizes Documentum, a content management system, to store and process manuscripts. Documentum includes a Java API for custom application integration. ACS content validations are implemented using a few different technologies, including Java and Groovy. Implementing validations in Java and Groovy allow for validation of the manuscript content against data stored in the Documentum database, and the behavior of some validations change in subtle ways depending on manuscript attributes that are stored in the Documentum database. Validations written in Groovy may be developed quickly and deployed into production without incurring down-time.

The framework and validations that were implemented using Groovy were inspired by some of the main concepts of Schematron, such as the use of XPath expressions and assertion style programming. Individual validations that had no dependency on information stored in the content management system could have been implemented using Schematron. However, many validations did have that dependency, and there was a desire for a consistent approach in validation code.

xmlTestXPath(vid: 'journal-id',
        desc:'Journal Id must be present and be 2 characters long',
        context:’//journal-meta/journal-id’, 
        condition:'string-length(.)=2',
        messageId:'exact-string-length',
        severity:ACSPubsMessage.FATAL[…]
                

<tep-common:processing-comment category="Validation" error-code="exact-string-length"
type="fatal">Journal Id must be 2 characters long.</tep-common:processing-comment>

Automatic Edits (“Hands-Free” Quality)

At two different times during the processing of a manuscript, content and tagging changes are automatically applied to the XML document. The first time (“pre-edit”) occurs between the stages when the manuscript is converted into XML and when the Technical Editor edits it.

Pre-edits are commonly applied content corrections and tagging enhancements. For example, commonly misspelled (mispelled?) words are automatically corrected. Another simple example is that <title-group> elements are added if they are missing.

The goal of these automatic edits is twofold: to reduce the amount of time Technical Editors spend manually making common changes, and to increase quality by lowering the chances that instances of errors slip through the manual editing process. (Humans won’t catch every mispelled word!)

Automatic edits are also applied after the Technical Editors complete the manual editing process. These edits (“post-edits”) do not typically alter the element contents, but target the element tagging. Tagging is normalized (extraneous attributes removed, etc.) and the manuscript is prepared for future stages, such as web and print publication.

The automatic edit process itself is complex, and is accomplished using a combination of technologies. Many edits are implemented in Java after the XML document has been parsed. Some edits are implemented using XSL templates. We have developed thousands of individual edits, and continue to add them to our collection.

<label><bold>Label 1</bold></label>

<label>Label 1</label>

/**
 * Add a processing comment to the document to let the TechEd know what
 * the current DOTS page count is for the document.
 * 
 * @param doc ACS Journal DOM Document
 */
public void addPageCountProcessingComment(Document doc)
{
    try {

        String mscNo =
            acsJournalUtil.xpathFindString(doc, ACSJournalUtil.XPATH_DOCUMENT_ID_OLD_9);

        String pageCount =
            dotsMetaDataService.getAttribute(mscNo, DOTSMetaDataService.PAGECNT_TAG);

        int pageCountNum = Integer.parseInt(pageCount);

        if (pageCountNum == 0) {
            acsJournalUtil.addProcessingComment(doc, null,
                TEPMessageService.getInstance().
                    getMessageForId(STANDARD_EDITS_PAGE_COUNT_ZERO, pageCount));
        } else {
            acsJournalUtil.addProcessingComment(doc, null,
                TEPMessageService.getInstance().
                    getMessageForId(STANDARD_EDITS_PAGE_COUNT, pageCount));
        }
    } catch (Exception e) {
        logger.warn("Unable to determine DOTS page count.", e);
        acsJournalUtil.addProcessingComment(doc, null,
            TEPMessageService.getInstance().
                getMessageForId(STANDARD_EDITS_PAGE_COUNT_UNAVAIL));
    }
}
            

Vendor XML Quality

ACS outsourced the conversion and composition of its journals approximately five years ago, creating the need for someone to manage vendor relations. Initially, the job position didn’t include quality metrics experience but over time, metrics experience proved necessary. Ensuring vendor quality ultimately was implemented in three ways: vendor scoring, vendor validations, and vendor manual rejections.

Conclusion

The steps taken by ACS to measure, auto-correct, and validate our XML have made a positive difference in all aspects of the workflow. Technology is evolving daily and to think that efforts to ensure XML quality are complete is to already be behind. For example, we have made over 30 changes to our validations and pre-edits alone since the beginning of the year. ACS is committed to continually monitoring and improving the processes we have put in place to ensure the quality of our XML.