Introduction to XML Applications

EMC White Paper Introduction to XML Applications Umair Nauman Abstract: This document provides an overview of XML Applications. This is not a comprehensive guide to XML Applications and is intended for an audience that has no previous knowledge of Documentum XML Applications. A basic understanding of XML is a prerequisite to this guide. Date 3/5/2008

Copyright 2005 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. EMC 2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners. XML Applications 2

What is XML? The following is the web definition for XML: XML (Extensible Markup Language) is a standard for creating markup languages which describe the structure of data. It is not a fixed set of elements like HTML, but rather, it is like SGML (Standard Generalized Markup Language) in that it is a meta-language, or a language for describing languages. XML enables authors to define their own tags. XML is a formal specification of the World Wide Web Consortium XML Defines content structure - how content is stored and categorized. Typically XML does not define formatting. One XML file might have a number of different formatting requirements, depending on where the content is needed. XML can be transformed into a number of desired formats like HTML, WML and News-ML. Transformation can be done using XSLT or software programs. XSLT stands for extensible Stylesheet Language Transformation. It is a language that allows Developers to take an XML source file and transform it into another text-based output format. CSS stands for Cascading Style Sheets. It can also be used to turn XML into HTML. Some common terms used with XML DTD: (Document Type Definition) A DTD is the formal definition of the elements, structures, and rules for marking up a given type of SGML document. You can store a DTD at the beginning of a document or externally in a separate file. DTD was the first means of specifying XML syntax. DTD is written in SGML which is a precursor to XML. DTD is still frequently used today. Schemas: A schema is a description of the structure and rules a document must satisfy for an XML document type. It also includes the formal declaration of the elements that make up a document. If and XML file does not obey the syntax of its associated DTD or Schema, it is not valid. XSLT: Extensible stylesheet language transformation (XSLT) is a language for transforming XML documents into other XML documents. XSLT is designed for use as part of XSL, which is a stylesheet language for XML. XPath: A language that describes a way to locate and process items in XML documents by using an addressing syntax based on a path through the document's logical structure or hierarchy DOM: Document Object Model (DOM) is a form of representation of structured documents as an objectoriented model. DOM is the official World Wide Web Consortium (W3C) standard for representing structured documents in a platform- and language-neutral manner. The DOM is also the basis for a wide range of application programming interfaces, some of which are standardized by the W3C. SAX: Simple API for XML. SAX is an Event-driven programmatic access to the XML file. It provides a simple Java interface useable by many Java parsers. SAX parsers and interfaces are included in the java API org.xml.sax.* What is a Documentum XML Application? An XML Application is a repository folder (dm_xml_application) containing the following: - XML ApplicationConfiguration File o XML File named MyXMLApp in System/Applications/MyXMLApp o Defines how XML documents are divided into smaller chunks upon import or checkin o Sets properties on those chunks (object type, location, other) XML Applications 3

o Defines how links and entity references are handled - Document Type Definition o Located in System/Applications/MyXMLApp o Used to calidate the XML files being imported or checked in - XSL style sheets o Located in System/Applications/MyXMLApp o Used for transforming the XML document - Application Support Documents o Contains supporting documents (E.g. Cascading Style Sheets used by XML Editors) o Located in a folder within System/Applications/MyXMLApp XML documents in the repository are managed through Documentum XML Application. A documentum XML Application contains the rules for validating an XML document and managing it during repository operation. You can also store style sheets and other supporting documents along with and XML application. XML applications are user-defined, to reflect the needs and rules of your enterprise. A repository can have multiple XML applications. An XML application folder contains and identifies through its properties the documents that define a particular XML application. XML application folders are a subtype of dm_folder. Properties defined for the application folders are used to determine which application is used to process a particular document. XML application folders are stored in the repository in System/Applications There are two main ways to validate XML documents: DTD or Schema. In Documentum, XML Applications are used to automate rules for importing, storing and organizing content. The simplest XML Application only needs to have a XML Configuration file (of type dm_xml_config) and a dtd file (of type dm_document). Both of these objects need to be in a XML Application folder (type dm_xml_application) in the \System\Applications folder. More complex XML Applications can have multiple dtd files, stylesheets, html files, and entity files. These will usually be stored in the Application Support Documents folder under the XML Application folder. These files are optional and are only used for viewing and checkout operations. They aren t necessary for proper validation. Until WebTop was introduced, DTC was the only client that supported XML processing. Documentum also integrates with two third party XML editing applications: Arbortext Epic and Corel (SoftQuad) XMetal. The integrations are maintained and supported by the third party vendors directly. You can download them from our Download Center, but the most recent versions are available directly from the third party vendors. An XML application can control how XML documents are stored, imported, checked in, exported, and checked out of the repository. It can set permissions, set a binding rule, or attach a lifecycle to the XML content. It can assign metadata to repository objects based on information extracted from the XML, external variables, or expressions set by custom Java code. This saves the user from doing these things manually. In a prototypical XML application that chunks XML content, the following is the behavior that a repository user might expect to see when checking documents in and out of a repository: After importing or checking in a single XML document, a user sees the document represented in the repository as a virtual document, with a treelike structure showing the XML container as the root and any objects that were chunked by the XML application as child components. When a user checks out this document, the document is reassembled into a single document in the user s checkout directory. Upon checkin, the document is once again chunked (accounting for any changes to the document) and appears again as a virtual document in the repository. XML Applications 4

If the DTD or W3C Schema is managed by the XML application, the user does not have to worry about associating a checked-out document with a DTD or W3C Schema, since it will download to the user s system along with the document, and the document s declaration will be patched to point to that location. Users can share XML content by viewing or checking out the chunks or linked files (such as a graphic) they want to share and copying them into their documents, or by using one of the Documentum integrations with Arbortext Epic or Corel XMetal. Upon import or checkin of the document, the content is automatically shared. Why should you use XML Applications? Following is a list of benefits of using Documentum XML Applications for Content Management: You want separate groups in the company to manage separate chunks of content, with different permissions assigned to each chunk. You want to share chunks of content with other authors or departments in a non-proprietary file format. You want to reuse chunks of content in more than one document or publish it to more than one location. You want to automate processing of XML content chunks using features available in the standard EMC Documentum content management system, such as source control, metadata, document lifecycles, workflows, and security. You use XML as a wrapper for non-xml documents in order to assign metadata to those documents in the repository. You want to create XML files that can be used to create folders, assign properties, and so on, without creating any content chunks. You want to construct Web pages dynamically with XML content chunks. Default XML Application The Default XML Application is a simple application that handles XML documents if there is not a matching XML Application. The Default XML Application is located in the folder System/Applications/Default XML Application and has only one rule: How to recognize and process externally parsed entities. You can modify the Default XML Application Configuration file for this default to add you own general processing rules. An XML Application Configuration file MUST include a DTD reference to config.dtd or config.5.x.dtd Defining a Chunk Two advantages of managing XML content in Documentum are the ability to retain XML content in configurable chunks for reuse and the enforcement of distinct business processes on specific parts of the XML content. Documentum XML applications can be configured to chunk on any element tag in the document. You can also define a context for the elements that will trigger a chunking rule: only in a particular hierarchical structure, only with a particular attribute value, or only when it is the nth occurrence of a parent element. The configuration file is used to determine which elements in the XML file will be defined as Chunks in the repository. If several chunks are created for a single XML document, each of those chunks will be repository objects organized as a Virtual Document. Properties, such as object type, location, lifecycle, permissions set and other metadata for the chunks are also defined in the Configuration file. Documentum creates a separate repository object for content within the opening and closing tag of any element designated in the configuration file as a chunking element. For example, suppose you want the XML application to chunk all <Head1> elements in an XML document. This means that all content in the document occurring within any matched set of opening and closing <Head1> tags (<Head1> - </Head1>) is XML Applications 5

saved in the repository as a single object. Chunks are nested in the virtual document just as they are nested in the original XML document. For example, if <sect2> elements are nested under <sect1> element in the XML document, and you chunk both <sect1> and <sect2> elements, then the <sect2> chunks will be nested under the <sect1> chunks in the virtual document in the repository. The appropriate level of chunking for a particular kind of XML document depends on your manageability and reuse requirements. Smaller chunks may increase the opportunity for reuse but will also lead to slower performance when working with documents. You can also decide not to create any chunks but use the XML application to perform other automated tasks, such as assigning repository properties to a document. Benefits of Virtual Documents XML applications store chunked XML documents as virtual documents in the repository, which offer the following advantages: Both the entire virtual document and each separate component can be handled as individual documents in the repository. With a client that displays virtual documents, users can view the structure of the virtual document in the repository, the location of a particular chunk, and the other documents in which that chunk is used. Users can check out either an entire XML document or individual virtual document components (corresponding to chunked XML objects). Individual components of virtual documents can be linked to other locations or shared by other virtual documents. Content updated once appears everywhere. Components in the same virtual document can have different permissions and metadata.. You can attach a document lifecycle to a virtual document or any of its components. An entire virtual document or any individual component can be inserted as a package in a workflow. If you do not want content of a component to be updated in a particular virtual document, you can set a binding rule, which controls the version of the component that is used within that virtual document. You can also assign meaningful version labels and set the view to fix the display of all components to that version. You can create an assembly of a virtual document, which is useful for creating a snapshot of the structure and content of the XML document at any point in time. These assemblies can be stored in the repository and retrieved at any time while the current document continues to be updated. When assemblies are created for XML documents, they are always created as frozen, since editing virtual document structure directly in the repository is not allowed for XML documents. All structural changes should be made by editing the document itself. XML Applications 6

XML Application Architecture A folder of object type dm_xml_application, which can be created in any location in a repository, but usually is installed into the System\Applications folder. (XML applications created by Documentum Application Builder are always installed to this folder.) A configuration file of type dm_xml_config. The functionality available through the XML application configuration file is controlled by the version of the Documentum configuration DTD that you use. A folder called Application Support Documents, which can contain any documents intended for download to local systems along with the DTD or W3C Schema. This can include files such as CSS, FOSI, and stylesheets. A folder called XML Sample Documents, which will open in the XML Configuration Editor that is supplied with Documentum Application Builder. Any other folders that you choose to create manually in order to store associated files that will not be downloaded to local system. How an XML Application is detected When a document is imported or checked in to the Repository, there is an algorithm used to determine which XML application to apply to the document. The XML Application is specified in the processing instruction in the prolog of the XML document of the following type: <?dctm xml_app="application_name"?> If only a single XML application matches, that application is used. If multiple applications match the user is presented with a dialog listing the choices. If the user fails to make a choice or if the choice is being made programmatically and no choice is specified in the application, the first match returned by the query is used. The following processing instruction will halt the algorithm: <?dctm xml_app="ignore"?> XML Applications 7

Add this line if you do not want XML processing to occur for a particular file. This effectively turns XML processing off. This is the only way currently to turn XML processing off. The dtd System ID, dtd Public ID and root element are obtained from the XML document itself. We query for XML applications that match. If none of the above apply, then the Default XML Application is used. Checklist for creating XML Applications through DAB Information or File XML application name XML application configuration file DTD file name (system identifier) Public identifier Supporting files DTD member files Schema file name Schema members Root element names XML sample documents Required or Optional Required Required Required if your DTD is managed by an XML application. Required if public identifier is used in XML documents and DTD is managed by XML application Required for DTD or schema members if managed by the XML application; otherwise optional Required if declared in the DTD and DTD is managed by XML application. Required if your schema is managed by XML application. Required if referenced from the schema Required to determine which XML applications will apply Optional Where to find Same name as XML application folder. Specified in <!DOCTYPE> declaration of XML documents to be processed by the application. Specified in <!DOCTYPE> declaration of XML documents to be processed by the application. External parameter entities or schema members for a managed DTD or schema (required); any other files such as CSS, FOSI, XSL stylesheets (optional) Declared in DTD as external parameter entities Name of W3C schema, if used in XML documents. Specified by the <import> element in the schema. All elements that can serve as the root element of the XML document. XML documents in the /System/Applications/ docapp_name/xml_app_name/ XML Sample Documents folder in the repository. docapp_name is the name of the DocApp in which the XML Applications 8

XML application resides and xml_app_name is the name of the XML application. Tasks to perform before creating an XML Application Before creating your XML application, perform these tasks so that you will have a valid XML application and all objects will be correctly installed into the target Repositories (if you create a DocApp archive to install on other Repositories). To make sure that your XML application is valid and all objects will be correctly installed into the target Repositories: 1. Insert all objects specified in the XML application configuration file into the DocApp. Performing this step makes your DocApp portable. 2. Make sure that all initial states specified in the XML application configuration file exist in the corresponding document lifecycles. 3. Make sure that no document lifecycles that are specified in the XML application configuration file with the same names exist in the same location. Performing this step ensures that the XML application uses the correct document lifecycle; otherwise, if you have duplicate document lifecycles, the XML application might not use the correct one. 4. You can also specify the object ID of the appropriate document lifecycle in the XML application configuration file, but when you install it to another Repository, you will need to change its object ID to the new one. 5. Make sure that the document lifecycles specified in the XML application configuration file are the originals or copies--do not link them (links might not be installed in target Repositories). 6. Make sure that the alias set name and the alias names specified in the XML application configuration file are the same names as those included in the DocApp; alias names are not validated. How to: Create an XML Application using DAB For D6, Documentum Composer has to be used for XML application. Please refer to the Composer documentation for details. You can create and XML Application using Documentum Application Builder or you can create it Manually using Documentum Desktop. Here is a list of steps you need to take to build an XML Application through DAB: 1) Open Documentum Application Builder and select a new DocApp. 2) Choose Insert XML Application. 3) In the Create XML Application dialog box s General tab, specify a name for the XML application in the Name field. The XML application name must be unique in the Repository. The name of the application must be the same as the XML application configuration and the value of the <name> element (which is a child of the <application> element) in the XML application configuration file. 4) Create an XML application configuration file for the XML application by selecting one of these options: Create a new configuration file from template Use an existing An XML application configuration file with minimal configuration information and based on the standard Documentum XML application configuration template will be created. The XML application configuration file name and value of the <name> element (which is a child of the <application> element) in the XML application configuration file must be the same as the XML application name. In the XML application configuration file you will need to develop the rules for processing your XML documents. Click the Browse button to find and select an XML application XML Applications 9

configuration file from the Repository Use an existing configuration file from the local file system configuration file in the Repository. The XML application configuration file will be copied into the DocApp folder and renamed to the name of the XML application. If you have not already done so, you must change the value of the <name> element (which is a child of the <application> element) in the XML application configuration file to the name of the XML application. In the XML application configuration file you might need to modify the rules for processing your XML documents. Click the Browse button to find and select an XML application configuration file on your local file system. The XML application configuration file will be checked in to the DocApp folder and renamed to the name of the XML application. If you have not already done so, you must change the value of the <name> element (which is a child of the application> element) in the XML application configuration file to the name of the XML application. In the XML application configuration file you might need to modify the rules for processing your XML documents. 5) Check or uncheck the Validate the DocApp before checking in the XML application option. Checking this option specifies that your XML application will be validated against its XML application configuration file before it is checked in; otherwise, it will not be validated before it is checked in. However, you can manually validate it at a later time by selecting the XML application and choosing Tools XML Application Validate. You might not want to check this option when you know that the XML application configuration file is invalid (for example, when you choose to use an existing configuration file and the <application><name> element is not the same name as the XML application) and you will be updating it later. 6) Specify values and select options on the Validation, XML App Detection, and Supporting Folder tabs. 7) To validate (if you chose to validate it) and check in the XML application, click OK. Tip: To make sure that you have entered a unique XML application name and selected an XML application configuration file before validating and checking in the XML application, click Apply. 8) Confirm your XML application specifications. Before creating the XML application, Application Builder displays a dialog box that describes the options you have specified for the XML application. To confirm the options and create the XML application files and folders, click OK. To cancel the creation of the XML application files and folders, click Cancel. For More details on Creating XML Applications through DAB Please refer to DAB User Guide. Cellphone XML Application In this section we will discuss the cell phone Sample XML application that is available for download from http://developer.emc.com. After installing the cell phone application we can review the directory structure in the Repository as demonstrated in the following screenshot: XML Applications 10

As you can see, all XML application are installed in the System Cabinet under the Applications folder. The Application Support Documents folder exists under a Folder with the same name as the XML application name. Here is what your XML content will look like after importing an XML document and chunking: In this case we have imported an XML document that contains descriptions of various cell phone models. The chunking rules have been set up to create a new object for each cell phone instance as you can see in the screenshot above. For complete source code of cell phone application, please refer to XML Application Developers Guide. For detailed steps for creating and XML Application using Documentum Application Builder, please refer to the Documentum Application Builder User Guide. It may be worth mentioning that you can use the IDfValidate Operation in DFC to validate and XML document against a DTD. It is also possible to explicitly specify the name of an XML application in a DFC Import operation using the following method call: IDfImportNode.setXMLApplicationName( "XML Application Name" ); You can turn off XML processing on the node and all its descendants by calling nodeimport.setxmlapplicationname("ignore"); XML Applications 11

For more details please refer to DFC Developers Guide. How To: Troubleshoot XML Applications Remember that you do not need to be an XML expert to troubleshoot XML apps. It certainly helps though. We don t write XML Config files or create XML Applications for customer. Refer to Consulting if they need assistance. XML Application problems usually happen during import or check in. Keep in mind that the DFC does almost all the work with XML Application processing. Following are some questions you should ask when troubleshooting XML Applications: What XML Application are being used? If it s a custom XML application, can the same content be imported against the Default XML Application? The Default XML Application: - Takes care of external parsed entities. - It does no chunking. - It creates no virtual document structure. - We do not support changing the Default XML Application. Make sure the correct types are used if the application was created manually. The folder needs to be of type dm_xml_application, not dm_folder. The XML config file needs to be of the type dm_xml_config. Is the XML application configuration file located in the XML application folder? Does it have the same name as the XML application folder? Can the XML be validated outside the Repository? For example, by opening it up in Internet Explorer. If you are using a DTD to validate against the XML document, does the DTD file appear in the XML application folder? Does the XML Application folder correctly reference the DTD file on the system_id attribute. Verify that the DTD file shows as filename.dtd in the Repository. This may be a likely cause of the problem if the file was created manually. Is the name of the XML application folder unique in the Repository? The most frequent problem is that the XML application has not been set up to manage the dtd correctly. Even if an XML application is not requiring that the XML document be valid, the dtd still needs to be accessible. In order to have the dtd file path patched in the exported/checked out document, the DTD system ID attribute must be set on the XML application folder. The object name of the DTD stored in the XML application folder must be the DTD file name. - <!DOCTYPE book SYSTEM book.dtd > - DTD object must be named book.dtd and the dtd system ID property on the XML application folder must be book.dtd Find out if it had ever worked in the past. If so, were any changes made to the XML config file or DTD recently? XML Spy is not a supported XML Editor. It s known to add hidden characters to the content of the file that we have problems with. You can assign an ACL to an object as part of XML processing. XML Applications support public and private ACL s. Most of the XML processing is done on the local client machine by the DFC. XML processing is very memory hungry, so make sure the machine has plenty of free memory.. Large XML documents can take over 30 minutes to import depending on the amount of processing/chunking the customer is doing. The only recommendation is to do less chunking. Useful Support Notes: Support Note 40220 - What can be the cause of XML docs not getting processed by XML applications? XML Applications 12

Support Note 13589 - Why does my xml not get chunked when I try to perform a checkin though DFC? Support Note 25403 - Is it possible in an XML application to restrict or to check the encoding of the XML document that is being imported? Support Note 13074 - How does Documentum determine which XML Application is applicable? Support Note 40316 - How can I check the xalan parser version used? Support Note 12670 - Why can I only import an XML document once without error? Support Note 11470 - Why do I get a hexadecimal value of text arguments when importing an xml file? Support Note 17354 - Does the XML Application feature use SAX, DOM or both? Support Note 9719 - What are the new classes in DFC for XML? Support Note 23917 - How can I import XML documents that are not well formed without receiving an error? Support Note 28501 - How do I install Default XML Application manually? Support Note 21453 - Why do I get an error saying that it cannot find my DTD file when I import an XML file against my custom XML Application? Questionnaire 1) What are some of the required components and properties of an XML Application 2) Describe some of the advantages of using XML Application 3) What is a DTD? What is a Schema? 4) Under which folder path in the Repository do XML Applications exist? References Definition of XML: www.acad.bg/beginner/gnrt/appendix/glossary.html XML Development Guide DAB User Guide DFC Advanced Training Guide XML Applications 13