Automatic Page CopiesA publish trigger and web services

case study

Daniel Horwitz andDarren Schaumann,

ProHealth Care

Where’s Darren?

In Tahiti on a large boat sipping margaritas and loving life

OR

In labor and delivery waiting for my second child to be born.

Detailed Information

• Information on downloading the detailed speaker’s notes, Java code, style sheets and build configuration will be made available at the end of this presentation.

Introduction

• Our policies and procedures system was difficult to use, and even harder to maintain.

• Using a publish trigger and web services, we were able to simplify our system.

• Only one copy of each policy and procedure is updated.

Problem Statement

• Policies and procedures defined

• Current situation

• Challenge

Definition

• Policies and procedures are the documented processes and guidelines that the corporation and people are required to follow.

Definition

• Policies can apply to multiple entities within the ProHealth Care system.

Definition

• Each policy and procedure document should contain either a policy section, a procedure section or both.

Current Situation

• Users note that searching on the current site is difficult to use.

Current Situation

• Each entity has a directory structure to browse, but they all have different structures.

Current Situation

• Policies were written in Microsoft Word™ and then converted to PDF files.

• They have many different, and inconsistent, formats.

Challenge

• Simple search and site hierarchy for finding policies.

• Use content management for archiving and workflow.

• Single source policy applying to many places in the hierarchy.

• Have all the policies use the same format.

First Attempt

• Display document in multiple places using ‘references’.

• Unable to get navigation to be based on user’s current location in site. Need separate index block generation for each folder where the policy appears.

ProHealth Solution

• Build policies out of a series of HTML blocks.

• Allow content editors to edit only the source policies.

• Include entity and category information as metadata.

• When source policy is published, create or update copies of the policy at all the appropriate places in the site hierarchy, then publish the copies.

User View

• Organization

• Home page

• Search

• Left Navigation

• Right Navigation

• Policy Display

User View - Organization

• Policies are organized by entity and category.

Policies andProcedures

Entity:Lawrence Center

Entity:ProHealth Care

Entity:Waukesha Memorial

Hospital

Category:Administration

Category:Admitting

Category:Corporate

Compliance

UncategorizedPolicy

User View – Home Page

• Policies and procedures home page has left-hand navigation and search.

• Both dynamically display all entities.

User View - Search

• Using Google™ search appliance.• Finds policies under each applicable entity

and category.

User View – Left Navigation

• Left-hand navigation block allows users to browse for policies in the site hierarchy.

User View – Right Navigation

• Right navigation displays policies immediately under entity or policies within current category.

User View – Policy Display

• Displayed as series of HTML blocks.

Content Editors

• Content editors see only the source copy of the policy document.

• The different pieces of the document are all edited as blocks.

Content Editors

• Defining entities and categories to which the policy applies.

Content Editors

• Editor must enter policy, definitions and procedure into separate blocks.

Content Editors

• When the content editor publishes the source, all the copies are published.

• Content editors can publish the folders containing the copies.

• When creating a new policy, the creator selects a different page type for a policy only, a procedure only or a combined policy and procedure.

Site Administrators

• Only site administrators can see the copies.

• Site administrators set up entity and category selection blocks.

• Site administrators create folders and index pages for all the entity/category combinations.

Style Sheets

• The style sheets take advantage of copies of all the policies being in the correct place.

• For navigation, the “current” attribute is the key to locating the system folder which is the user’s current location in the site.

Style Sheets – Left Nav

• Left-hand navigation displays the user’s current location in the site.

• Style sheet called Left PandP Parent Children, because it displays both the parent (entity) information and the children (category) information.

Style Sheets – Left Nav

• If current is an entity, displays all the entities, highlights the current and displays the categories of the current entity.

• If current is a category, displays all the entities, highlights the current and displays just the current category.

• If no current, then displays all the entities, with no current entity highlighted.

Style Sheets - Search

• Search, on the right hand side on the home page, displays the search block.

• Style sheet is PandP Search.

• Handling of two columns loosely based on Home Left Navigation.

Style Sheets – Right Nav

• When user’s current location is an entity, display that entity’s policies that do not have a category.

• Style sheet called PandP Children because it displays an entity’s children.

Style Sheets – Right Nav

• When user’s current location is a category, display the category’s policies.

• Style sheet called PandP Grandchildren because it displays an entity’s grandchildren.

Style Sheets - Navigation

• The navigation style sheets use an index block as their source. Generating the XML for an index block takes some time. This seems to be the main bottleneck for publishing.

• Navigation must be rendered based on user’s current location so that all the links are correct.

Style Sheets - Policies

• The policy_procedure style sheet displays the selected policy.

• The policy is simply a list of blocks, which are displayed in order.

• The entities block is built from the “Site” dynamic-metadata element, which is a sibling of the system-data-structure element.

Publish Trigger

• Notes• Vocabulary• High-level Algorithm• Web service calls used• Publish trigger interface• Web services interface• WebservicesUtils• Building an Asset for a psuedo-policy• Build Notes

Publish Trigger - Notes

• In order to publish an asset, that asset must exist.

• When an asset is published by the user, or via the web service, it is placed on a queue.

• A single thread in the Cascade server takes an item from the queue and publishes it.

Publish Trigger - Vocabulary

• Actual policy: The source policy, which is edited by the content editors.

• Pseudo-policy: A copy of the source policy, which is used to publish copies of the actual policy.

High-level Algorithm - Notes

• Low-level details are in the Java code to be supplied later.

• Publish trigger is called for every destination of every document being published.

• Upon return from the trigger, the triggering document is published by Cascade to the specified destination.

High-level Algorithm

• I) Examine the entity type and entity path from the publish information. If not a policy, do nothing.

• II) Read the policy being published.

• III) Look at the metadata. If a pseudo-policy, do nothing.

High-level Algorithm - IV

• IV) Using the applicable entity and category lists from the metadata, loop through each pseudo-policy associated with the actual policy.

• A) Try to read the pseudo-policy.

High-level Algorithm - IV

• B) If the pseudo-policy doesn’t exist:

• 1) Create the pseudo-policy.

• 2) Remove non-administrator access to the page.

• 3) Publish the indices to its parent and grandparent folders.

High-level Algorithm - IV

• C) If the pseudo-policy exists but the actual policy has been updated later:

• 1) Update the pseudo-policy to reflect the actual policy’s content.

• 2) Remove non-administrator access to the page.

High-level Algorithm - IV

• D) Publish the pseudo-policy.

Web Service Calls Used

• Only assets being manipulated are pages.

• read()

• create()

• edit()

• editAccessRights()

• publish()

Publish Trigger Interface

• See “Publish Triggers” in the knowledge base for details.

Publish Trigger Interface

• SDK contained in CascadePublishTrigger.zip

• Use publishtrigger-5.5.jar

• Interface is part of Cascade installation. Don’t include interface classes in the publish trigger archives.

Web Services Interface

• See “Web Services Skeleton Project” in the knowledge base for details.

Web Services Interface

• Download axis 1.4 from http://ws.apache.org/axis.• Make the jar files in

axis-1_4/webapps/axis/WEB-INF/lib available.• Get a current copy of the wsdl file using a browser.

Cascade server must be running. URL is<server-base>/ws/services/AssetOperationService?wsdl.

• Build interface classes using org.apache.axis.tools.ant.wsdl.Wsdl2javaAntTask.

• Careful, AssetOperationService_address is based on how the wsdl file was addressed by the browser. Production interface must be built from production wsdl file.

WebservicesUtils

• Get com.cms.webservices.WebservicesUtils from Cascade+Webservices.zip.

• Pages contain a number of elements where an identifier or path must be supplied, but not both.

WebservicesUtils

• To set up a page for create() or edit(), read the page, call nullPageValues(), then perform application-specific editing.

• If you don’t use nullPageValues(), beware of dragons.

WebservicesUtils

• Since WebservicesUtils has been written, the web services have been updated.

• Before line 84, add:pConf[i].setId( null );

Building Asset for Pseudo-Policy

• An asset must be passed to create() or edit().

• Read actual policy page, run nullPageValues(), make an asset for the updated page and update the metadata fields.

Building Asset for Pseudo-Policy

• Update metadata by getting dynamic fields list from the page’s metadata and go through the fields.

• Each field has a name and a list of values.• If the name is “Actual”, set to single false

value.• If the name is “pathToActual”, set to single

string which is the path to the actual policy.• If any other name, leave alone.

Build Notes

• Use Java 1.5 JDK for compatibility with the Cascade server.

• Axis web service interface classes generate a lot of warnings.

• Copy publish trigger jar file to../tomcat/webapps/ROOT/WEB-INF/lib on each Cascade server.

Debugging

• Mostly done with Eclipse debugger.• Use Log4j to log messages to Cascade log.• Publish trigger interface for testing

implemented by class in Eclipse.• Information hard-coded in the method that

drives test.• Probable that org.apache.axis.utils.JavaUtils

will log warnings about DataHandler and MimeMultipart. The warnings can be ignored.

Debugging SOAP Messages

• Prudent to see the SOAP messages.• Hannon Hill often wants to see SOAP

messages.• Hannon Hill recommends tcpmon. Get it from

https://tcpmon.dev.java.net.• Web services interface code must explicitly

go through tcpmon. Update AssetOperationService_address in AssetOperationHandlerServiceLocator.java. Change protocol:host:port section to http://localhost:3333.

Debugging SOAP Messages

• Bring up tcpmon in a command window using “java –jar tcpmon.jar”.

• Create new TCP Monitor Connection: Local Port: 3333 Server Name: <Cascade-server-name> Server Port: <Cascade-server-port>

• Run the test. tcpmon will capture the SOAP traffic.

Cleaning up Orphaned Psuedo-policies

• Psuedo-policy with no associated actual policy is an orphan. Caused when policy no longer applies to entity or category.

• Orphaned policies appear in index blocks. This causes them to appear in navigation areas and allows them to be accessed by the users.

• Finding orphaned policies is slow because all the policy folders must be searched.

• Scheduled job runs weekly to clean up orphans.

High-level Algorithm - Clean up Orphans

• Starting at root of policies, recursively go through that folder and all its sub-folders.

• In each folder:• A) Read the folder asset using read()• B) Go through all the folder’s child assets:• 1) If asset’s path ends in /index or /_cms, ignore it.• 2) If asset is a folder, recursively process the folder.• 3) If asset is a page, process potentially orphaned

policy by:

High-level Algorithm – Clean up Orphans

• i) Read the potentially orphaned policy.

• ii) If not a pseudo-policy, ignore it.

• iii) Read associated actual policy. If the read fails, delete the pseudo-policy.

• iv) Look at entity and site in actual policy’s metadata. If no combinations match pseudo-policy, delete it.

Cleaning up Orphaned Psuedo-policies

• The application uses read() and delete() web service calls.

• Activation and mailapi_1_1_3 jar files must be made available to the application.

• Directory on the server contains jar file, batch file, jar files from Axis 1.4 library, and activation and mailapi_1_1_3 jars.

Eclipse Organization

• ProHealth uses Eclipse IDE and CVS.• Many ways to organize the Eclipse projects.• For reproducibility, copies of all third-party sources and libraries are in

CVS.• CascadePublishTriggerLib - publishtrigger-5.5.jar library from

CascadePublishTrigger.zip.• CascadeAxisLibs – Library jars for Axis 1-4.• CascadeWebServices – Java classes built here based on

AssetOperationService.wsdl from the Cascade server.• CascadePhcUtils – Project that builds the bulk of the publish trigger

and cleanup application.• CascadePublishTriggers – The publish trigger itself, ready for use on

the Cascade server.• CascadeCleanup – The application for deleting orphan pseudo-

policies.

Gotchas

• The publish() web service call currently does not allow target destinations to be defined - CSNEW-132 requests that destinations be supported by the publish() web service call.

• The generation of the index block, used for generating the navigation, is rather intense. This causes the publishing of policies to be rather slow.

Good to Know

• Hannon Hill has Professional Services that can write triggers and web service clients.

• Support model is very hands-on by Hannon Hill. The number of customers writing web service clients is small enough that customers are supported better by people than by extensive documentation that may or may not address the issue.

Lessons Learned

• Get technical portions working first and then announce it to users.

• Working with the web services is an iterative process. The detailed implementation can require changes to the user process.

Future Development

• Add workflow for policy updating.

Detailed Information

• Additional information may be downloaded from:www.hannonhill.com/new-kb/Users-Conference/index.

Email Addresses

• Daniel.Horwitz@phci.org

• Darren.Schaumann@phci.org

Summary

• Need multiple copies of documents to support location-specific navigation.

• Allow content editors to edit source documents and specify all display locations.

• Use publish trigger, that calls web services, to create, update and publish the copies.

Questions?