Differentiating publishing services using document attribute conditioning in IBM SCORE

The publishing services in IBM® SCORE can be conditioned using document attributes to produce varying outputs with varying styles for different compound documents for submission to different regulatory agencies. Using simple examples, this article describes how you can combine and configure these elements to create desired outputs. This content is part of the IBM WebSphere Developer Technical Journal.

O. Michael Atogi (atogi@us.ibm.com), Industry Solutions Software, IBM

O. Michael Atogi is a software developer at the IBM Raleigh Lab in Durham, North Carolina. He has been with IBM for over seventeen years and holds an MS degree in computer science from Howard University, Washington, D.C. He currently works on IBM Solution for Compliance in a Regulated Environment (SCORE) development.



02 February 2011

Introduction

IBM Solution for Compliance in a Regulated Environment (SCORE) is a document management solution that provides end-to-end electronic document management in the Life Sciences and Healthcare industry sectors. As such, IBM SCORE supports many global industry standards, such as Electronic Common Technical Document (eCTD) for drug submissions into government regulatory agencies, Title 21 CFR Part 11, FDA guidelines on electronic records and electronic signatures, GxP, and so on.

One of the major functions provided by IBM SCORE is to combine simple documents within a compound document into a single read only PDF rendition during a workflow action. The task of generating the single PDF document from the component simple documents is called publishing. The workflow actions used to drive generation of the PDF rendition are send for review (SFR) and send for approval (SFA):

  • In an SFR workflow, the PDF generated is sent to reviewers for annotations.
  • In an SFA workflow, the PDF generated is sent to approvers who can either approve or reject the document and provide a reason and e-signature.

Starting with IBM SCORE V6.1.1.2, different document types can be published using either shallow aggregation or deep aggregation. Shallow aggregation uses first generation children of the compound document, while deep aggregation traverses the depth of the compound document structure and uses only simple documents for the aggregation. The IBM SCORE administrator can use the combination of the three publishing services described below in combination with the customizable style templates provided in IBM SCORE to generate aggregate document outputs that meet various regulatory agency requirements.

By way of simple examples, this article describes various style artifacts, how each publish services is unique, and how you can configure these publishing services using document attributes conditioning to create different desired outputs. This article assumes a basic familiarity of IBM SCORE functions and Adobe Document Descriptor XML (DDX) language.

IBM SCORE implementation

IBM SCORE is an IBM WebSphere® Portal application that is deployable to an IBM WebSphere Application Server that runs the IBM SCORE enterprise application and SCORE Web services. The SCORE enterprise application provides both a WAR module for interacting with users and EJB JAR files for database transactions. The SCORE Web services are used by remote clients to call into the SCORE application and execute actions and return the results to the caller via HTTP/SOAP requests and responses.

An IBM SCORE deployment always requires the installation of IBM WebSphere Process Server, used as the document workflow engine, IBM WebSphere Application Server Network Deployment, for administering the complex deployment environment employing different servers and services, and the WebSphere Application Server V7 Feature Pack for Web Services. IBM SCORE installation also requires a content server to securely persist and audit the voluminous data. Current implementations support IBM Content Manager, as well as EMC Documentum, each with its supporting relational databases. Other vendor Java™ EE applications are typically also deployed on various other WeSphere Application Servers to provide other miscellaneous functions to complete the solution.


Publishing services

IBM SCORE provides these publishing services, depending on the specific output required:

  • StructurePublishService produces an outline of the compound document hierarchy in the same way that Windows® Explorer displays folders and files. This publishing service is of the structure publish type.
  • AggregatePublishService produces an aggregate PDF rendition consisting of simple documents and nested compound documents that are all siblings of the parent compound document. This means that if there is a nested compound document that is a child of the parent, then, regardless of its depth, a PDF must be generated at the first level. If the nesting is n deep, then at each depth a nested compound document PDF must be generated, which becomes the n–i child (where i=n-1, n-2, and so on, and i <= n). The published document can also contain a table of contents, which if present starts as the first page of the aggregate PDF. If the content of a simple child document of a nested compound document changes after a nested compound document PDF has been generated, that content is not reflected in the aggregate rendition. For the content of the changed child simple document to be reflected in the nested compound document publish, a new nested compound document PDF must be regenerated using SRF, SFA, or by manual publish action. This publish service is of the aggregate publish type.
  • DeepAggregatePublishService produces an aggregate PDF rendition that consists of only the simple documents within the root compound document hierarchy. The simple document renditions are used to aggregate the compound document. If during publish time a simple document does not have a rendition, then a rendition for it is requested. When all the renditions of the compound document are available, then the root compound document publish proceeds. This publish service also understands the semantics for cover page support within the document hierarchy by looking for the presence of a document subtype of _ibm_score_toc_ within the compound document; if present, any document before its position is considered cover page content. The table of contents for the published compound document is placed following the cover page (or pages, if table of contents generation has been enabled through a configuration parameter). This publish service is of the aggregate publish type.

Publishing style

Publishing style refers to the decoration of the document in the areas of pagination, table of contents, and footer.

Pagination controls the style used in numbering the pages of the published PDF table of contents. It can use lower Roman, upper Roman, lower Alpha, upper Alpha, decimal numerals, or none. The font, font style (normal, italic, oblique), and font size can be controlled in the generated table of contents and on the page footers. The set of repetitious pattern of characters –- dashes, dots, lines or spaces -- that can be used to fill the space between bookmark titles and the referenced page numbers on the table of contents pages can also be customized. These customizable aspects of PDF publishing are separated into a set of templates. The templates are coded in Adobe Document Descriptor XML (DDX) language. The publishing service runs on an Adobe LiveCycle ES server, which is a DDX processor containing the Adobe Assembler service (see Resources).

IBM SCORE V6.1.1.2 ships with sample templates that contain default styles. For each default template, some of the DDX elements that can be customized are highlighted and examined. Before customizing any template, make a copy of the default template, rename it, make your updates, and then check-in the renamed copy into the repository so that it can be referenced as a configuration parameter to any of the publishing services. There are various publishing default templates but the three default templates shown below can be customized to create a different PDF appearance:

defaultTOCstyle2

The defaultTOCstyle2 template in Listing 1 controls the display of the PDF’s table of contents. The bold items shown in Listing 1 are elements that are typically customized in the template:

  • The maxBookmarkLevel attribute of the TableOfContents element is by default set to 3, meaning that the table of contents contains headings of level 3 or less. If you desire the table of contents to contain only up to bookmark heading level 2, then change 3 to 2.
  • The font and color attributes of the p element are used to set the font, font size and color of the text respectively. In the default template, the font name of MyriadPro, font size of 12pt, in black color is used for bookmark heading level 1 entries in the table of contents. For bookmark heading level 2, the same font and color is used but the font size is set to 10pt. If you wish, you can use alternate syntax for specifying font family, font style, and font size, for example:

    <p font-family="sans-serif" font-style="normal" font-size="12pt" color="black">

  • The leader-pattern attribute of the leader element is set to dotted by default. This means that the spaces between the bookmark title and the referenced page number on the table of contents are repetitiously filled with the dot character. If you prefer to leave those spaces blank, then replace dotted with space. Alternatively, you can specify either dashed or double-dashed for a dashed line.
  • The Center element is used to center the table of contents on the PDF page. If a left or right style alignment is preferred, then the Left or Right element can be used respectively.
Listing 1. Excerpt of defaultTOCstyle2 template with DDX elements
<SCORE_DDX_TOC_TEMPLATE>

<StyleProfile name="myTOCStyle">
 <TableOfContents maxBookmarkLevel="3" createLiveLinks="true" 

includeInTOC="false">
	<PageMargins right="1.5in" top="1.75in" left="1.5in" bottom="0.28in" />

<!-- ***************************************************************************
 This element controls the properties of the 'first' of potentially multiple 
 pages of TOC.
******************************************************************************** -->
    <TableOfContentsPagePattern pages="1">
	<Header styleReference="headerForTOCPage1Style"/>
    </TableOfContentsPagePattern>

<!-- ***************************************************************************
 This element controls the properties of the 'second to last' of potentially 
 multiple pages of the TOC.
******************************************************************************** -->
  <TableOfContentsPagePattern pages="2-last">
	<Header styleReference="headerForTOCPage2Style"/>	
  </TableOfContentsPagePattern>


<!-- use this style for bookmark level 1 -->
	 <TableOfContentsEntryPattern applicableLevel="1">
	       <StyledText>
	              <p font="MyriadPro,12pt" color="black">
	                 <_BookmarkTitle /> 
	                 <leader leader-pattern="dotted" /> 
	                 <_BookmarkPageCitation /> 
	             </p>
	        </StyledText>
	 </TableOfContentsEntryPattern>

<!-- use this style for bookmark level 2 -->
	 <TableOfContentsEntryPattern applicableLevel="2">
	        <StyledText text-indent="0.25in">
	               <p font="MyriadPro,10pt" color="black">
	                    <_BookmarkTitle /> 
	                    <leader leader-pattern="dotted" /> 
	                    <_BookmarkPageCitation /> 
	               </p>
	         </StyledText>
	 </TableOfContentsEntryPattern>

      </TableOfContents>
</StyleProfile>

<StyleProfile name="headerForTOCPage1Style">
	<Header>
	<Center>
		<StyledText><p>Table of Contents</p></StyledText>
	</Center>
	</Header>
</StyleProfile>

<StyleProfile name="headerForTOCPage2Style">
	<Header>
	    <Center>
		<StyledText><p>Table of Contents (CONTINUED)
			</p></StyledText>
	   </Center>
	</Header>
</StyleProfile>

<!-- ##### end of template #### -->
</SCORE_DDX_TOC_TEMPLATE>

Before committing any style change to the repository, experiment through publishing test documents and check the output to make sure that your alignment does not overlap with the existing document overlay attribute in the footer.

defaultPDFPageLabelStyle2

The defaultPDFPageLabelStyle2 template in Listing 2 controls the display of the PDF’s page number on the footer. For the most practical use of the published PDF, page numbering is necessary, and therefore the only style element that should be customized here is the page number alignment. By default, the page number is center aligned; if desired, you can leave it left or right aligned using the Left or Right element, respectively.

Listing 2. Excerpt of daultPDFPageLabelStyle2 template with DDX elements
<StyleProfile name="footerWithPageNumberStyle">
	<Footer>
	    <Center>
		<StyledText><p><_PageLabel/></p></StyledText>
	    </Center>
	</Footer>
</StyleProfile>

defaultSignPageLabelSyleBack

The defaultSignPageLabelStyeBack template in Listing 3 controls the display of the PDF’s electronic signature page number on the footer on the back of the published signed PDF. Again, page numbering on the PDF is necessary for practical usage, so the only style element that should be customized here is the page number alignment. The DDX elements, attributes, and values are documented in the DDX reference in Resources.

Listing 3. Excerpt of defaultSignPageLabelStyleBack template with DDX elements
<StyleProfile name="footerWithPageNumberStyle">
	<Footer>
	    <Center>
		<StyledText><p><_PageLabel/></p></StyledText>
	    </Center>
	</Footer>
</StyleProfile>

ActionConfig conditioning

IBM SCORE uses XML configurations to control various processing aspects including the execution of actions. The ActionConfig.xml configuration file contains the inputs required for an action, and the DocTypeConfig.xml file contains the attributes of a document type. An attribute in IBM SCORE is an XML element defined using the Attribute element. It is metadata that describes an IBM SCORE entity or action, and it has configurable rules and a value (or values if it is a repeating attribute). For example, Listing 4 shows ActionConfig.xml with the three publishing services described above defined:

Listing 4. Sample XML definition of the publish services in ActionConfig.xml
<AuxService name="structurePublishService" sessionType="current" type="publish">
	<Condition name="document_type" negated="true" operator="IN">
		<Value val="clinical_study"/>
	</Condition>
	<ServicePlugin name="StructurePublishService">
		<Parm encrypt="false" name="tocStyle" 
			value="/DDX Templates/defaultTOCstyle.ddx"/>
		<Parm encrypt="false" name="formatsToIgnore" value=""/>
	</ServicePlugin>
	<Function name="publish"/>
</AuxService>

<AuxService name="aggregatePublishService" sessionType="current" type="publish">
	<Condition name="document_type" negated="false" operator="IN">
		<Value val="clinical_study" />
	</Condition>
	<ServicePlugin name="AggregatePublishService">
		<Parm encrypt="false" name="tocStyle" 
			value="/DDX Templates/defaultTOCstyle.ddx"/>
		<Parm encrypt="false" name="formatsToIgnore" value=""/>
	</ServicePlugin>        
		<Function name="publish" />
</AuxService>

Notice that the third publish service, DeepAggregatePublishService, is missing from Listing 4. That is because prior to IBM SCORE V6.1.1.2, there were only two publishing services: StructurePublishService and AggregatePublishService. In IBM SCORE V6.1.1.2, DeepAggregatePublishService was introduced to provide functionality which the other two publishing services do not have (support for cover pages, only using simple documents rendition for the aggregation, and 1-N pagination, which was abstracted out into the style templates to make it available to the other publishing services). The full content of IBM SCORE V6.1.1.2 including a detail description of the DeepAggreatePublishService is contained in the readme document (see Resources). The presence of two publishing services that provide aggregate publishing but different characteristics requires that conditioning logic be employed to discriminate between the two services using document attributes.

In Listings 5, 6, and 7:

  • The bold elements within <Condition ... > </Condition> tags within each AuxService element are condition elements that utilize document attributes.
  • The bold elements within <Parm ... > </Parm> tags within the AuxService element are style-related configurations.

These parameters are inputs to the publishing service and are used to pass in the style templates [link to Publishing style section] , along with other parameters that enable or disable the option. While the parameter names are self explanatory, a complete set of parameter (Parm element) definitions are available in the IBM SCORE V6.1.1.2 readme.

Listing 5. Conditional publishing service: StructurePublishService
<AuxService name="structurePublishService" sessionType="current" type="publish">
	<Condition name="document_type" negated="true" operator="IN">
		<Value val="clinical_study"/>
		<Value val="pgp_doc"/>
	</Condition>
	<ServicePlugin name="StructurePublishService">
		<Parm encrypt="false" name="tocStyle" 
			value="/DDX Templates/defaultTOCstyle.ddx"/>
		<Parm encrypt="false" name="formatsToIgnore" value=""/>
	</ServicePlugin>
	<Function name="publish"/>
</AuxService>
Listing 6. Conditional publishing service: AggregatePublishService
<AuxService name="aggregatePublishService2" sessionType="current" type="publish">
	<Condition name="document_type" negated="false" operator="IN">
            <Value val="pgp_doc"/>
	</Condition>
	<Condition name="doc_subtype" negated="false" operator="IN">
		<Value val="Procedure"/>
		<Value val="Other"/>
	</Condition>
	<Condition name="document_type" negated="true" operator="IN">
		<Value val="appl_doc"/>
		<Value val="module"/>
		<Value val="submission"/>
	</Condition>
	<ServicePlugin name="AggregatePublishService">
		<Parm encrypt="false" name="formatsToIgnore" value=""/>
		<Parm encrypt="false" name="tocStyle" 
			value="/DDX Templates/defaultTOCstyle2"/>
		<Parm encrypt="false" name="includeTOC" value="true"/>
		<Parm encrypt="false" name="tocBookmarkTitle" value="_SourceTitle"/>
		<Parm encrypt="false" name="includePageLabelFooter" value="true"/>
		<Parm encrypt="false" name="pageLabelStyleLocation" 
			value="/DDX Templates/defaultPDFPageLabelStyle2"/>
	</ServicePlugin>
	<Function name="publish"/>
	<Function name="hasPendingPublishRequest"/>
</AuxService>
Listing 7. Conditional publishing service: DeepAggregatePublishService
<AuxService name="aggregatePublishService" sessionType="current" type="publish">
	<Condition negated="false" operator="OR">
		<Condition negated="false" operator="AND">
			<Condition name="document_type" negated="false" operator="IN">
				<Value val="pgp_doc"/>
			</Condition>
			<Condition name="doc_subtype" negated="false" operator="IN">
				<Value val="Policy"/>
				<Value val="Guideline"/>
			</Condition>
			<Condition name="document_type" negated="true" operator="IN">
				<Value val="appl_doc"/>
				<Value val="module"/>
				<Value val="submission"/>
			</Condition>
		</Condition>
		<Condition name="document_type" negated="false" operator="IN">
			<Value val="clinical_study"/>
		</Condition>
	</Condition>
	<ServicePlugin name="DeepAggregatePublishService">
            <Parm encrypt="false" name="formatsToIgnore" value=""/>
            <Parm encrypt="false" name="tocStyle" 
			value="/DDX Templates/defaultTOCstyle2"/>
            <Parm encrypt="false" name="includeTOC" value="true"/>
            <Parm encrypt="false" name="tocBookmarkTitle" value="_SourceTitle"/>
            <Parm encrypt="false" name="includePageLabelFooter" value="true"/>
            <Parm encrypt="false" name="pageLabelStyleLocation" 
			value="/DDX Templates/defaultPDFPageLabelStyle2"/>
	</ServicePlugin>
	<Function name="publish"/>
	<Function name="hasPendingPublishRequest"/>
</AuxService>

In Listing 5, the Condition element is used to create complex logical expressions as conditions can be nested. The complete schema description of a Condition element is in the IBM SCORE XML Configuration Schema Reference. Here, it is leveraged to build a discriminating logical expression. When an action is executed to initiate a publish, the IBM SCORE application evaluates the conditions within each AuxService element of type publish to determine the first match of publish service to invoke. Therefore, each conditional expression must be written such that it excludes false positives:

  • The conditions in Listing 5 say that if the compound document to be published is not of type clinical_study or pgp_doc, then use the StructurePublishService.
  • Listing 6 says that if the document_type is pgp_doc and the doc_subtype is either Procedure or Other, then use the AggregatePublishService to publish the document with the style parameters declared with the Parm elements.
  • Listing 7 says that if it is a clinical_study document or document_type is pgp_doc and its doc_subtype is Policy or Guideline, then use the DeepAggregatePublishService with the style parameters declared with the Parm elements.

Conclusion

Some of the publishing services and the styled elements used in IBM SCORE were described in this article. Each publishing service has unique characteristics, but the publishing styles are common and each publishing service can be configured to use any of the styled elements encapsulated in the templates to produce output that is desired (or required) by a regulatory agency. The default templates and the default configurations for each publishing service are designed to produce optimal output for that publishing service. For example, the DeepAggregatePublishService is configured to use the defaultTOCstyle2 and defaultSignPageLabelStyleBack templates by default so that they can generate 1-N pagination, including electronic signature pages. However, if any requirements for the output PDF changes, the styled elements can be customized to meet those needs. The availability of the three publishing services and the exposed styled elements through the various templates make generating various publishing outputs possible.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Information Management
ArticleID=620398
ArticleTitle=Differentiating publishing services using document attribute conditioning in IBM SCORE
publish-date=02022011