Livelink ECM - Enterprise Server XML Import and Export Guide

Livelink ECM Enterprise Server XML Import and Export Guide
This guide describes and explains how to use Livelinks XML Export and XML Import features. LLESCOR090701-PGD-EN-1
Livelink ECM Enterprise Server XML Import and Export Guide LLESCOR090701-PGD-EN-1 Rev.: 2007-Dec-18
Open Text Corporation 275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1 Tel: +1-519-888-7111 Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440 Fax: +1-519-888-0677 E-mail: support@opentext.com FTP: ftp://ftp.opentext.com For more information, visit http://www.opentext.com
Copyright 2007 by Open Text Corporation

Open Text Corporation is the owner of the trademarks Open Text, The Content Experts, Great Minds Working Together, Livelink, Livelink ECM, Livelink ECM-eDOCS, Livelink MeetingZone, MeetingZone, B2BScene, B2BScene.com, Client/Surfer, Collaboration, Creative Desktop, Further Faster, Hyperinnovation, Internet Anywhere ,Livelink IRIMS, IRIMS, IXOS, Livelink OnTime, OnTime, Livelink Remote Cache, Microstar, MyLivelink, O & Design, Odesta, Odesta Helix, Odesta Livelinke, Open Text Intranet, Open Text Web Index, Personality +, Putting Knowledge To Work, Techlib, The Hyperlinked Organization, The Source For Business Knowledge, Worksmart, and World Of E among others. This list is not exhaustive. ACKNOWLEDGEMENTS SAP, R/3 and SAP ArchiveLink are registered trademarks of SAP AG. Adobe is a trademark of Adobe Systems Incorporated. Lotus and Lotus Notes are registered trademarks of Lotus Development Corporation. Domino is a trademark of Lotus Development Corporation. Microsoft and Microsoft SQL are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. Netscape and the Netscape N and Ship's Wheel logos are registered trademarks of Netscape Communications Corporation in the U.S. and other countries. Firefox is a registered trademark of the Mozilla Foundation Sentry Spelling-Checker Engine Copyright 2000 Wintertree Software Inc. WordNet 2.0 Copyright 2003 by Princeton University. All rights reserved. Outside In Viewing Technology 1992-2002 Stellent Chicago, Inc. All rights reserved. Outside In HTML Export 2002 Stellent Chicago, Inc. All rights reserved. Portions of eDOCS DM are copyrighted by DataDirect Technologies, 1991-2002. All other products or company names are used for identification purposes only, and are trademarks of their respective owners. All rights reserved.
Table of Contents
Preface 1
1.1 1.2
.................................................................................................... 5 Introduction ............................................................................... 9

Transforming Exported XML .................................................................... 9 About This Guide ................................................................................... 11
2
2.1 2.2
Using XML Export ................................................................... 13

XML Export Using a URL ....................................................................... 13 XML Export Using OScript ..................................................................... 16
3
3.1 3.2
Using XML Import.................................................................... 19

XML Import Using a URL ....................................................................... 19 XML Import Using OScript ..................................................................... 22
4
4.1 4.2 4.3 4.4
XML Import and Export for Developers ................................. 25

General Architecture .............................................................................. 25 XML Import Step by Step ....................................................................... 27 Creating a Database Connection........................................................... 30 Working with Generic Nodes ................................................................. 32
5
5.1 5.2 5.3 5.4
Customizing XML Import and Export ..................................... 39

XML Callback Handlers ......................................................................... 39 Custom Object Types and XML Nodes.................................................. 45 XML Built-Ins.......................................................................................... 55 Migrating to the New XML Implementation ............................................ 56
IX
Index......................................................................................... 59
LLESCOR090701-PGD-EN-1
Livelink ECM Enterprise Server
Preface
This preface explains the typographical conventions used in this guide and provides Open Text contact information.
Typographical Conventions Used in This Guide

All information in the following table is case-sensitive unless otherwise noted.
Item File names, directory names, folder names, path names, window names, dialog box names, Web page names, URLs, and e-mail addresses Convention These items appear in regular (normal) typeface. Some elements in italic indicate placeholders. Examples:
Run setup.exe to start the installation
program. Open the Livelink_home/config/opentext.ini file in a text editor. Note: The placeholder Livelink_home represents the Livelink root directory (directory where Livelink was installed).
Send an e-mail message to
support@opentext.com to contact Open Text Customer Support. In the Windows XP Control Panel, double-click the Services icon to open the Services dialog box. Names of user interface elements, such as buttons, links, menus, check boxes, radio buttons, lists, fields, and so on These items appear in bold typeface. Examples:
On the Tools menu, click Search. In the Services dialog box, click Livelink
Server: service_name, and then click the Start button. Click the items Functions icon, choose Properties, and then choose General. Click the Admin Home link.
Preface
Item Variable placeholders, references to other documents, new or special terminology, and emphasis
Convention These items appear in italic typeface. Examples:

For more information, see the Livelink
First-Time Installation Guide.
You can scan new documents for content
of interest by saving your search criteria in a query called a prospector.
In your Web browser, go to the default
Livelink start page at protocol://host:port/URL_prefix/livelink.e xe, where protocol is http or https, host is the DNS name of the HTTP server host, port is the port number on which the HTTP server is listening, and URL_prefix is the prefix mapped to the Livelink_home/cgi directory in the HTTP server.
References to chapters and sections of documents, and citations of messages displayed to users
These items appear in "quotation marks." Examples:

For more information, see Chapter Three,
"Projects," in the Livelink QuickStart for Users guide. For more information, see "Item Types" in Chapter Five, "Livelink Items." For more information, see "Item Types," page 150. If the import completes successfully, Oracle displays the message "Database import completed without errors." Operating system commands, code examples, feature names, method names, object names, and text typed by users These items appear in a monospaced font. Examples:
In the User Name field, type Admin.
At the operating system prompt, type start-llserver, and then press ENTER. When searching for users, you can set the
maximum number of users displayed per page by setting the value (default is 30) of the MaxUsersToListPerPage parameter in the [general] section of the opentext.ini file.
Preface
Item Key names
Convention Key names appear in ALL CAPS. Examples:

Press ENTER to start a new line when
typing in this field.
To select multiple items, hold down the
CTRL key while you click the items that you want to select.
Contact Information
Open Text Online is a single point of access for the product information provided by Open Text. Depending on your role, you have access to different scopes of information (see below for details). Furthermore, the following information and support sources can be accessed through Open Text Online: Knowledge Center Open Text's corporate extranet and primary site for technical support. It is the official source for:

Downloading Open Text products and modules. Downloading official documentation for Open Text products. Downloading official patches for Open Text products.
You can access the Knowledge Center at: https://knowledge.opentext.com.
Expert Service Center The Expert Service Center (ESC) is a source of up-to-date information continually maintained by Open Text employees, including technical hints, frequently asked questions, latest Release Notes and more. The following role-specific information is available: Partners

Information on the Open Text Partner Program Programs and support for registered partners
Business Users
Tips, help files, and further information from Open Text staff and other users in one of the Open Text online communities
Administrators/Developers
Downloads and patches
XML Import and Export Guide
Preface
Documentation Product information Discussions Product previews
You can access the Expert Service Center at: https://esc.ixos.com/. You can access Open Text Online at: http://online.opentext.com/. Also, you can reach the support sites at: http://support.opentext.com/
Feedback on documentation
If you have any comments, questions, or suggestions to improve our documentation, contact us by e-mail at documentation@opentext.com.
Chapter 1
Introduction
Livelink's XML Import and XML Export features let you exchange Livelink data with other XML-compliant systems. XML Export enables the information associated with a Livelink volume or node to be translated into XML code and exported as a file that can be used by another application, such as a data archive. XML Import does the reverseit enables you to add any object type to your Livelink system (whether it is a standard type or custom type that you created) simply by importing an XML file. The only restriction is that the object specified by the XML file must conform to Livelink's native XML schema.
Figure 1-1: Sample of XML Code Representing a Livelink Folder Object
1.1 Transforming Exported XML

When you export a Livelink node as XML, the XML Export function gives you significant control over the structure of the XML files that Livelink generates. It also gives you the option to transform the Livelink-native XML document structure into Web-friendly HTML. There are two ways to accomplish this:
Chapter 1 Introduction
On the client side, by using an XSL (Extensible Stylesheet Language) stylesheet and Livelink's built-in XSLT (Extensible Stylesheet Language Transformation) processor. This client-side transformation capability has been called XML Skins because it enables Livelink content to be presented with a different "look and feel" by transforming the Livelink structures into HTML pages. On the server side, by inserting a stylesheet reference into the document so that a client application, such as a Web browser, can perform the transformation.
Figure 1-2: Sample View of a Livelink Folder Using XML Skins
10
1.2
About This Guide
1.2 About This Guide

The goal of this guide is to explain Livelink's XML Export and XML Import functions to two audiences: (1) experienced Livelink users who need to use these features, and (2) developers who need to understand in detail how the XML Export and XML Import functions work and how to extend them. describes the chapters and appendixes in this guide. Table 1-1: Description of Chapters
Title Chapter 1, Introduction on page 9 Chapter 2, Using XML Export on page 13 Chapter 3, Chapter 4, XML Import and Export for Developers on page 25 Chapter 5, Customizing XML Import and Export on page 39 Description Describes the basic characteristics of XML Import and Export and of this guide. Explains how to export Livelink nodes as XML files. Teaches experienced Livelink users how to import XML files to create a new Livelink node. Describes in detail how XML Import and Export work, including enhancements made in Livelink 9.5.0. Explains how to extend XML Import and Export to support your customizations.
11
Chapter 2
Using XML Export

There are two ways to perform an XML Export:
URL method, in which you type a URL that includes a Livelink request. For more information, see XML Export Using a URL on page 19. Scripting language method, which performs the XML Export programmatically, using OScript. For more information, see XML Export Using OScript on page 22.
2.1 XML Export Using a URL

The XML Export function lets you export a Livelink volume or node and the data it contains as an XML file. You perform an XML export by typing a Livelink URL into a Web browser. A number of required and optional parameters contained in the URL control the content and format of the resulting file. Note: Any Livelink user can perform an XML Export. The only restriction is that the user must have the See permission for the volume or node to be exported and all subitems within the volume or node. Any subitems for which the user does not have the See permission are not exported. The base URL for performing an XML Export takes the following form:
func=ll&objAction=XMLExport&objId=<nnnn>
where <nnnn> is the Livelink ID of the node to be exported. To perform an XML Export: Open the following in a Web browser:
<Livelink_URL>?func=ll&objAction=XMLExport&objId=<nnnn>&<optional _parameters>
where <optional parameters> is any of the following parameters that you can use to tailor a particular XML export. These parameters are explained in Table 2-1:
13
Chapter 2 Using XML Export
Table 2-1: Optional XML Export Parameters

Parameter
scope
Description Determines child depth of export
Values
sub = export the objId and all child nodes one = export the objId node and its
immediate child nodes only

base = export only the objId node <n> (an integer greater than 0) = export
the node and its direct descendants up to <n> levels below the node: 1 for one level below, 2 for two levels below, and so on
nodeInfo
Determines whether DAPI node information is exported Determines whether categories and system attributes applied to the node are exported Determines whether Versions of the node are exported
If included, DAPI node information is exported, along with a list of exported nodes This must be specified to import the exported content. If included, Categories and attributes are exported
attributeInfo
versionInfo
all = export all Versions current =
export current Version only

<n> (an integer greater than 0) = export
the node and Version number <n> If no value is specified, all Versions are exported.
content
Determines whether the content of Versions is exported, and the encoding format
plain = export Version content as plain text base64 = export Version content as base64-encoded text cdata = export Version content as plain text wrapped in a cdata tag.
If no value is specified, base64 is used. This must be specified to import the exported Categories. The cdata or base64 attributes should be used when the content of a document is XML. The versioninfo parameter must be present with content or an error will occur.
14
2.1
XML Export Using a URL
Parameter
permissions
Description Determines if permissions are exported with the node Exports the name, user ID and domain of the creator, owner and group owner.
Values If included, permissions are exported. This parameter must be used with the nodeinfo parameter or it will be ignored. If included this information can be used by Import to restore the creator, owner and group owner when a node is created (if the export is imported into the system it was exported from). This parameter must be used with the nodeinfo parameter or it will be ignored. If included, a Livelink schema reference is exported If included, perform transform using the style sheet This parameter must be used with the transform parameter or an error will occur. If included, transform using the Xalan transform engine. transform=<my_value> performs transform using your own custom transform engine This parameter must be used with the stylesheet parameter or an error will occur.
extuserinfo
schema
Determines if a Livelink schema reference is exported Stores the path and filename of a style sheet to be applied to the XML Stores the name of the XML transform to apply.
stylesheet
transform
callbackhandlername
Name of the callback handler used to add to or alter the XML content of the export (for example, to orphan the handler to an ospace and give it a name. To use the handler in an export, add
CallbackHandlerName =<MyXmlCallback> to
Used = Name of the callback handler used Not Used = no callbacks used
the URL.
context
Determines whether the current context is exported
Used = true Not Used = false
15
Parameter
followaliases
Description Determines whether Aliases (now called Shortcuts) are replaced with the node they alias
Values Used = true Not Used = false
2.1.1 Configurable Settings

The [XML] section of the opentext.ini file has several parameters that can be configured to adjust the behavior of the XML Export function.
StyleSheetMimeType=text/xsl
Sets the value of the type attribute in the link to the stylesheet that is embedded in the XML export (for example, <?xml-stylesheet type="text/xsl" href="<url_string>"?>). Set this value to text/css for Cascading Style Sheet, or to text/xsl for Microsoft Internet Explorer version 5.0.

UnencodedMimetype_1=text/xml UnencodedMimetype_2=text/html
Indicates which MIME types can be exported unencoded, using either the &content=cdata or &content=plain parameters to the XMLExportrequest. The default MIME type must be indicated here or specified in the cdata and plain parameters of the URL used to initiate the export process.
2.2 XML Export Using OScript

XML Export can also be performed programmatically, using OScript, as the following code example shows:
// demonstrates using XmlUtil.Export to export // a node. also shows how XmlUtil.Export can be // used to perform an xsl transform of the xml // when debugging mark cleanup as false Boolean cleanup = false // set to true to perform an xsl transform Boolean xformIt = false // set output filename String filename = "D:\a3.xml" // set node to export Integer id = 2000 // setup to perform export Object db = $Xml.GenericDb.DbCreateObj( "Admin", "livelink" ) if ( IsDefined( db ) ) // get prg session and options Object prgCtx = db.GetPrgSession() Assoc options = Assoc.CreateAssoc() // set handler name
16
2.2
XML Export Using OScript
options.HandlerName = "XmlExport" // export options options.Scope = "sub" //options.NodeInfo = true //options.Content = "base64" //options.AttributeInfo = true //options.Permissions = true //options.VersionInfo = "all" options.Content = undefined options.AttributeInfo = undefined options.Permissions = undefined options.VersionInfo = undefined //options.FollowAliases = true //options.RequestContext = false options.Schema = true options.Namespace = "ll" //options.StyleSheet = "livelinkbrowse.xsl" /* options.XmlAllowedChildren = true options.XmlCrumbTrail = true */ if ( xformIt ) // xform options // if xform requested then the input file name // will be used to store the xsl result. if
the
// file does not exist it is created // only the xerces xform is working. // the external code is in place by not tested options.Transform = "Xerces" // note the stylesheet can be file, support path relative url or node id options.StyleSheet = "d:\showtypes.xsl" end // perform export Integer starttick = Date.Tick() Assoc result = $Xml.XmlUtil.Export( prgCtx, id, options, filename ) echo( "transform took:" + Str.String(Date.Tick() starttick)) if ( IsDefined( result.NodesExported ) ) echo ( "nodes exported: " + Str.ValueToString( result.NodesExported ) ) end if ( IsDefined( result.CategoriesExported ) ) echo ( "categories exported: " + Str.ValueToString( result.CategoriesExported ) ) end if ( IsDefined( result.UsersExported ) )
17
result.UsersExported )
echo ( "users exported: " + Str.ValueToString( ) DisplayUsers( prgCtx, result.UsersExported )
end echo ( "errors: " ) echo ( result.ErrMsg ) DisplayErrors( result.Errors ) // if cleanup then remove parser if ( cleanup ) db.Delete() end
end
function DisplayUsers ( Object prgSession, List users ) Assoc result Object xmlWriter if ( IsDefined( prgSession ) && IsDefined( users ) ) result = $Xml.XmlUtil.GetWriter() if ( result.Ok ) xmlWriter = result.Writer $Xml.Export.ExportUsersById( prgSession, xmlWriter, users, false ) echo( xmlWriter.GetBuffer() ) end end end function void DisplayErrors ( List errors ) String error if ( IsDefined( errors ) ) for error in errors echo( error ) end end end
18
Chapter 3
Using XML Import

XML Import was designed primarily for importing Livelink data structures that are created by the XML Export feature or manually. It is only able to import data that conforms to the Livelink schema. There are two ways to perform an XML Import:
URL method, in which you type a URL that includes a Livelink request. For more information, see XML Export Using a URL on page 19. Scripting language method, which performs the XML Import programmatically using OScript. For more information, see XML Export Using OScript on page 22. Note: Only the Livelink Administrator or users with the System administration rights privilege can perform an XML Import.
3.1 XML Import Using a URL

The following is an example of a URL that performs an XML Import:
<Livelink_URL>?func=admin.xmlimport&filename=<my.xml>&objid=<nnnn>
In the example, the request admin.xmlimport causes the XML file specified by the filename parameter to be imported. The numeric value <nnnn> is the node ID of the existing Livelink object (node or volume) that will contain the objects to be created. Note: The file to be imported must be on the server and must be referenced fully in the import URL. When you type a URL like this into a Web browser and specify a valid XML file, Livelink initiates the XML Import function. A status page displays, listing the location of the log file generated by the process, when the import was started, and whether the import has completed. A valid XML file is either one that has been created by Livelink's XML Export feature or a manually created one that conforms to the Livelink DTD. Note: If you manually create an XML file to import, any subsequent alterations to the Livelink schema will invalidate your file. Optional XML Import parameters are described in Table 3-1:
19
Chapter 3 Using XML Import
Table 3-1: Optional XML Import Parameters

Parameter
extuserinfo
Description Import the creator, owner and group owner using the exported creator, owner and group owner, if they exist. Nonexistent entities are ignored. If used with just the parameter name (i.e., no attribute), import uses the exported creator as the creator. The exported owner must exist in the system or it will not be used. If included with parameter <nnnn> (the ID of user in the system being imported into), import user <nnnn> as the creator. To use this feature, the export must have included the extuserinfo parameter.
Value Used = creator, owner, and group owner are imported.
creator
Used without value = uses the exported creator creator = <nnnn> (uses ID of the user in the system you are importing into)
owner
If used with just the parameter name (i.e., no attribute), import uses the exported owner as the owner. The exported owner must exist in the system or it will not be used. If included with parameter <nnnn> (the ID of user in the system being imported into), import uses <nnnn> as the owner. To use this feature the export must have included the extuserinfo parameter.
Used without value = uses the exported owner owner = <nnnn> (uses ID of the user in the system you are importing into)
20
3.1
XML Import Using a URL
Parameter
groupowner
Description If used with just the parameter name (i.e., no attribute), import uses the exported group owner as the group owner. The exported group owner must exist in the system or it will not be used. If included with parameter <nnnn>(the ID of user in the system being imported into), import uses <nnnn> as the group owner. To use this feature the export must have included the extuserinfo parameter.
Value Used without value = uses the exported group owner groupowner = <nnnn> (uses ID of the user in the system you are importing into)
inheritpermissions
Causes any nodes created by import to inherit permissions from their parent. For some parent node types that can force the inheriting of permissions (projects, for example) inheritpermissions will be ignored. Causes any permissions in the export file to not be imported. Name of the callback handler used to control some features of import. To use this parameter, orphan the xmlcallback handler to an ospace and give it a unique name. To use the handler in an import, add
CallbackHandlerName=< MyXmlCallback> to the
Used = created nodes inherit parent permissions Not Used = permissions not inherited
dontaddacls
Used = permissions not imported
callbackhandlername
Used = Name of the callback handler used Not Used = no callbacks used
URL.
In addition to the base parameters, there are user-defined import parameters, which are used to customize XML Import. These parameters are passed by the options Assoc to XML nodes and callback handlers. User-defined parameters must start with the characters "Xml". These parameters are intended for use by programmers who are developing callback handlers and for XML-node developers.
21
3.2 XML Import Using OScript

XML Import can also be performed programmatically, using OScript. Import is the base class for XML Import. It is used to import OScript data types and provides base methods that can be overridden in derived classes, so that import can be tailored. Objects that derive from Import must use a unique name that is stored in the fName field. This name is used to identify the import object in the XmlImportSubsystem. Each time an XML Import is initiated, Livelink generates an xmlimport.log file. If necessary, it also generates an xmlimporterrors.log file. These files are stored in the <Livelink_home>/logs directory.
3.2.1 Examples
The following examples demonstrate how to perform an XML import using OScript.
Import Using a Handler Name

Note: This example contains a parameter called cleanup. This parameter is necessary to enable the debugging of an import using Livelink Builder. Because of the way Builder works, breakpoints are not triggered in Builder until after the end of document has been received from a parser. However, when the end of document is received, all objects are deleted. In this case, if you try to debug, none of the objects are valid; therefore, the cleanup parameter, when set to false, keeps the objects used by the parser alive so that debugging can be performed.
// demonstrates getting import object using a handler name // and performing an xml import // when debugging mark cleanup as false Boolean cleanup = false // set the file to parse String filename = "D:\aaa2.xml // set parent id for import Integer id = 2003 // set callback handler String callbackHandler = "XmlAAA" // set import handler String importHandler = "XmlImport" // setup to perform export Object db = $Xml.GenericDb.DbCreateObj( "Admin", "livelink" ) if ( IsDefined( db ) ) // get prg session and options Object prgCtx = db.GetPrgSession() Assoc options = Assoc.CreateAssoc() // get default options for import $Xml.XmlUtil.GetImportDefaultOptions( importHandler, prgCtx, options ) // run the import
22
3.2
XML Import Using OScript
Assoc result = $Xml.XmlUtil.Import( prgCtx, filename, options, id, callbackHandler, cleanup ) // show objects create if ( IsDefined( result.NodeHandler ) ) if ( IsDefined ( result.NodeHandler.ObjectsCreated ) ) echo ( "nodes created by id: " + Str.ValueToString( result.NodeHandler.ObjectsCreated ) ) end if ( IsDefined ( result.NodeHandler.ObjectIdMap ) ) echo ( "node id map: " + Str.ValueToString( result.NodeHandler.ObjectIdMap ) ) end end // show timing if ( IsDefined( options.TotalImportTime ) ) echo( "Total Import Time: " + Str.String( options.TotalImportTime ) ) end if ( IsDefined( options.TotalIntraNodeProcessTime ) ) echo( "Total Intra Node Process Time: " + Str.String( options.TotalIntraNodeProcessTime ) ) end if ( IsDefined( options.TotalNodeProcessTime ) ) echo( "Total Node Process Time: " + Str.String( options.TotalNodeProcessTime ) ) end if ( IsDefined( options.TotalNodesProcessed ) ) echo( "Number of Nodes Processed: " + Str.String( options.TotalNodesProcessed ) ) end // show errors DisplayErrors( result.Errors ) // if cleanup then remove parser if ( cleanup ) db.Delete() end end function void DisplayErrors ( List errors ) String error if ( IsDefined( errors ) ) echo ( "" ) echo ( "errors: " ) echo ( "" ) for error in errors echo( error ) end end end
23
Importing Using the XmlUtil::Import Method

OScript data types can be imported using the XmlUtil::Import method, as shown in the example below:
Assoc result Dynamic var Assoc options = Assoc.CreateAssoc() Object xmlUtil = $Xml.XmlUtil // set options xmlUtil.GetExportDefaultOptions( "Default", options ) options.HandlerName = "Default" // create value to export Assoc exp = Assoc.CreateAssoc() exp.X = "This is it" exp.Y = 10 exp.Z = "The cow jumped over the fence" // perform export result = \ xmlUtil.Export( prgCtx, exp, options ) // get xml to use with import String xmlBuf = result.Buffer // set options xmlUtil.GetImportDefaultOptions( "Default", prgCtx, options ) options.HandlerName = "Default" // perform the import result = $Xml.XmlUtil.Import( prgCtx, xmlBuf, options ) if ( result.Ok ) if ( IsDefined( result.Value ) ) var = result.Value echo ( Str.ValueToString( var ) ) end end
In this example, XmlUtil::Import method is used, but a file name is not specified. This allows the XML to be obtained from a buffer stored in the return value. The buffer is passed to XmlUtil::Import. After import executes, the return Assoc will have a value member, which stores the imported OScript type.
24
Chapter 4
XML Import and Export for Developers

This chapter describes the following aspects of the XML Import function in detail and how the XML Export function must be extended when you add a new object type to your Livelink system. This chapter covers the following sections:

General Architecture on page 25 XML Import Step by Step on page 27 Creating a Database Connection on page 30 Working with Generic Nodes on page 32
4.1 General Architecture

Table 4-1 describes the XML import and export objects provided. Table 4-1: XML Import and Export Objects
Object Name
Export XmlExport XmlDependentsExport GenericNodeUtil Import XmlImport PreviewImport ImportHandler AppHandler
Description The base XML Export class; it provides the ability to export OScript types. Derived from XML Export, this object provides XML export for Livelink object types. Derived from Xml Export, this object exports objects and their dependents. Provides helper methods for working with generic nodes. The base XML Import class; it provides the ability to import OScript types. Derived from XML Import, this object provides XML Import for Livelink object types. Derived from XML Import, this object enables previewing an import without object creation. The base XML Import handler Derived from ImportHandler, this object provides the ability to handle an import by application.
25
Chapter 4 XML Import and Export for Developers
Object Name
TagHandler NodeHandler GenericNode XmlBuiltins
Description Derived from ImportHandler, this object provides the ability to handle individual tags during an application import. This object enables handling of node creation during Livelink import application. Derived from NamedValue, this object provides the ability to store parsed XML. The base class for all XML built-ins. Built-ins provide the ability to add generic XML information to all Livelink objects when they are exported. The base XML callback. Callbacks provide the ability to tailor XML Export and Import on a callback-handler basis. The base class for all exportable Livelink objects. The subtype field allows users to specify a Livelink object by type. The subtype field is a string. This allows for pseudo-object types that do not have a node subtype, such as the Project Overview page. The base class for all named XSL transform providers
XmlCallback XmlNode
XslTransform
Livelink's XML Import function was designed to use the least amount of memory possible and to create objects as quickly as possible. These criteria are met by:

The general design of the XML Using a SAX parser to parse the XML Using a GenericNode object to hold the parsed data Using a node stack to hold generic nodes
The SAX parser parses XML and returns its results through the DocumentHandler interface. Table 4-2 describes the parameters contained in the DocumentHandler interface. Table 4-2: DocumentHandler Interface
Method StartDocument EndDocument StartElement EndElement Characters Parameters None None String name Assoc attributes String name String chars Integer length Description Shows that document parsing has started Shows that document parsing has ended Shows that a new tag has been received Shows that a tag has ended Gets characters for a tag and shows how many there are
26
4.2
XML Import Step by Step
4.2 XML Import Step by Step

The following steps illustrate how the parsed XML is processed and stored: 1. 2. 3. When it begins parsing a document, the SAX parser calls through the DocumentHandler interface to the StartDocument method. The StartDocument method creates a node stack to hold the generic nodes. Each node will store a tag by name, along with its data and other attributes. When the parser encounters the start of an element, it passes the name of the tag and its attributes through the StartElement method to the DocumentHandler interface. At this point, a generic node is created and passed the element's name and its attributes. The generic node is put on top of the node stack. If there is data associated with the tag, the parser passes it through the Characters method to the handler. When received, the data returned is added to the generic node on top of the node stack. When the parser reaches an end tag, it calls the handler's EndElement method. When the parser finishes parsing the document, it calls the EndDocument method and the node stack is destroyed.
4.
5.
As this description shows, the XML Import process works by creating generic nodes. Each generic node contains the name of the tag it is associated with, the attributes of the tag, and any data associated with the tag. However, because the data being imported usually represents a hierarchical relationship, a generic node must be able to contain a list of children, which are also generic nodes. Therefore, to implement a generic node, a NamedValue object is created that contains a string name and a string value. Then, a GenericNode object is derived from NamedValue, which gives the node its name and value. The node's attributes are held in a list that stores NamedValue types. Finally, the node's children are held in a list. XML tags can have other XML tags as their children. This parent-child relationship must be preserved as the data is parsed. To accomplish this, the XML Import function reparents the nodes on top of the stack to the previous node on the stack when an element is reached.
4.2.1 Structure of Exported XML Data

When you export a node from a Livelink system, the resulting XML file contains three primary tags:

<Livelink>, the parent for all other tags <llvolume>, which represents either the Enterprise volume or a Personal or
Project Workspace
children. This relationship preserves the relationship between a parent DAPI node and its children.
<llnode> (contained within a <llvolume> tag), which represents a DAPI (document API) node. An <llnode> tag can contain other <llnode> tags as its
27
To understand how a generic <llnode> is transformed into a DAPI node in Livelink, examine what information an <llnode> holds. Table 4-3 shows a list of the tags that an <llnode> holds is shown and gives a brief description of each tag. Note the ordering of the tags. The data needed to create the node come first, followed by the children of the node. This ordering is intentionalit allows the parent node to be created without waiting for other information. Table 4-3: Child Elements of an <llnode>
Child node permission version category metadata Description Represents the DAPI node data used to create a DAPI node Holds the permissions for the node Stores Version information for the node The Categories that a node belongs to May not be present, depending on the node type. When present, they hold additional data used for that node types creation. The children of this node. These may or may not be present, depending on whether the node has children.
llnodes
4.2.2 Determining When to Create a DAPI Node

With an understanding of how the XML data is imported and how the information is stored in generic nodes on a node stack, the next thing to consider is how this information is used to create DAPI nodes. Table 4-4 outlines how exported data is rendered in XML. Note: Table 4-4 is intended for illustration purposes onlyit is not meant to be valid XML.
28
4.2
XML Import Step by Step
Table 4-4: Outline of Exported XML Data

DAPI Node With No Children
<llnode> <metadata<>data></metadata<>> <category><data></category> <node<attributes>> <permission> <acl><data></acl> </permission> <
DAPI Node With Two Children

<llnode> <special tag><data></special tag> <category><data></category> <node<attributes>><data></node> <permission> <acl><data></acl> </permission> <version><data></version> <llnode><data></llnode> <llnode><data></llnode> </llnode>
data>
</node> <version><data></version> </llnode>
Open Text recommends that you create the DAPI node as soon as possible, because doing so minimizes the number of generic nodes on the stack. Therefore, in cases where there are no children, the DocumentHandler method makes one check when it receives an <llnode> end element. In cases where there are one or more children, XML Import makes another check when it receives an <llnode> start element. This means that XML Import checks for the tag name <llnode> in both the StartElement and EndElement methods. If this condition is met, it tries to use the information stored in the generic node at the top of the node stack to create a DAPI node.
4.2.3 Re-creating the Parent-Child Relationship

The parent-child relationship must be preserved in the XML Import feature's generic node representation. To accomplish this, the XML Import feature reparents the current node on the top of the stack to the previous node on the stack when an <llnode> end element is reached. As an example, this section walks through the node stack of a hypothetical <llnode> with no children. Table 4-5 illustrates the reparenting process; square brackets around a name represent the generic node on the node stack.
29
Table 4-5: Reparenting Child Generic Nodes During Parsing

Tag <llnode> <node> <node> <permission> <permission> <version> <version> <llnode> Method Called
StartElement StartElement EndElement StartElment EndElement StartElement EndElement EndElement
Node Stack After Method [llnode] [llnode][node] [llnode[node]] [llnode[node]][permission] [llnode[node][permission]] [llnode[node][permission]][version] [llnode[node][permission] version]] At this point the node can be created
When the XML Import feature receives the start element for the <llnode>, it creates a generic node and puts it on top of the node stack. StartElement and EndElement are called for the tag. When it receives the EndElement, the generic node <node> is added as a child to the <llnode>. This also happens for the <permission> and <version> tags. When the EndElement method for <llnode> is called, there is a parent-child relationship with all the information needed to create the node. During import, the StartElement and EndElement methods both call the NodeHandler object's ProcessElement, ProcessStart and ProcessEnd methods. If one of these returns TRUE, the NodeHandler object's Process method is called to handle node creation.
4.2.4 Creation of DAPI Nodes During XML Import

The XmlImport object uses a reference to the NodeHandler object to handle node creation. Its Process method is passed a GenericNode object that holds all the information needed to create a DAPI node.
4.3 Creating a Database Connection

This section illustrates how a database connection can be made using the opentext.ini file, an existing PrgSession, or parameters.
4.3.1 Creating a Connection through the opentext.ini File

The GenericDb object is created, and then the connection to the database is made using the method DbCreate.
// create db object Object db = $LLIApi.GenericDb.New() // if not created if ( !IsDefined(db) ) return
30
4.3
Creating a Database Connection
end // connect to database with default INI file settings // the user name and password are required; the domain // is optional Boolean success = db.DbCreate( "Admin", "password" ) // release object if ( IsDefined(db) ) db.Delete() end
To make a named connection, use the method DbCreateNamed, passing in the name as a string.
// create db object Object db = $LLIApi.GenericDb.New() if ( !IsDefined(db) ) return end // connect to database with default INI settings // the user name and password are required; the domain // is optional Boolean success = db.DbCreateNamed( "livelink", "Admin", "password" )
4.3.2 Creating a Connection Using a PrgSession

An existing PrgSession can also be used to attach to existing connection, as shown in the following example. This example assume the PrgSession is already created.
// declare prg session and create Object prgCtx // create db object Object db = $LLIApi.GenericDb.New() // if not created if (!IsDefined(db) ) return end // connect to database with default INI file settings Boolean success = db.DbCreateUsingContext ( prgCtx ) // release object if ( IsDefined(db) ) db.Delete () end
31
4.3.3 Creating a Connection Using Parameters

In the following example, the script creates the database connection using the server name, the database vendor, the database name, the database user name and password, as well as the Livelink user and password.
// create db object Object db = $LLIApi.GenericDb.New() // if not created if (!IsDefined(db) ) return end // connect to database using parameters Boolean success = \ db.CreateUsingAll( "paris", "MSSQL", "tgross_record", "tgross_record",\ "tgross_record", "Admin", "livelink" ) // set to false when debugging Boolean cleanup = true if ( success ) // select import filename String filename = " alias.xml" // import the xml db.Import( filename, cleanup ) end // release object if ( IsDefined(dv) && cleanup ) db.Delete() end
4.4 Working with Generic Nodes

Generic nodes are used to hold the parsed XML. A generic node represents a parsed XML tag. Each generic node has attributes, which represent the attributes of an XML tag, and children, which represent XML tags contained within a parentXML tag. In most cases, you will use a generic node to get a tag's name, data value, and attributes. However, there are times when the parent-child relationship that can be represented by a generic node will also be useful. This section discusses the various methods of a generic node and how they can be used. Note: If there is no entry in the table the parameter or return type is void. A capital letter I at the end of a method name indicates that the method is not case sensitive.
32
4.4
Working with Generic Nodes
4.4.1 Generic Node Creation/Deletion Methods

The methods in Table 4-6 create and delete the generic nodes that are used to store parsed XML. Table 4-6: Generic Node Creation/Deletion Methods
Return Type Object Method Name
New Delete
Description Creates a generic node Deletes a generic node
4.4.2 Attribute Manipulation Methods

The methods in Table 4-7 allow attributes of a node to be added, moved, accessed, and removed. Table 4-7: Attribute Manipulation Methods
Return Type Boolean Method Name
HasAttributes AddAttribute AddAttributes AddAttributesByNames
Parameters None String name String value List attributes Assoc attributes String name String name String name None Object dstNode List names Assoc info
Description Checks if there are attributes Adds an attribute with name and value Adds a list of attributes Adds attributes from an Assoc Retrieves an attribute by name Retrieves attribute by name Retrieves an attribute by name (case insensitive) Retrieves attributes Moves attributes to a destination Puts attributes of a given name into an Assoc Removes all attributes
Object String
GetAttribute GetAttributeByName GetAttributeByNameI
List
GetAttributes MoveAttributes PutAttributesToAssoc RemoveAttributes
4.4.3 Child Manipulation Methods

The methods in Table 4-8 allow children of a node to be added, moved, accessed, and removed.
33
Table 4-8: Child Manipulation Methods

Return Type Boolean Method Name
HasChildren AddChild AddChildren
Parameters None Object child List children Integer index String name String name String name
Description Checks if there are child nodes Adds a child to a node Adds children to a node Retrieves a child by index Retrieves a child by name and removes it from child list Retrieves a child by name Retrieves a child by name (case insensitive) Retrieves node child list
Object
GetChild GetChildAndRemove GetChildByName GetChildByNameI
List
GetChildren GetChildrenByName MoveChildByName
String name String name Object dstNode Object dstNode Object child String name
Retrieves children of type name Moves children by name to a destination Moves children to a destination Removes a child from child list Removes first child with name Removes all children
List
MoveChildren RemoveChild RemoveChildByName RemoveChildren
4.4.4 DAPI Node Methods

The methods in Table 4-9 allow DAPI nodes to interact with system attributes. Table 4-9: DAPI Node Methods
Return Type String Method Name
GetAttributeNode
Parameters DAPI node String attribute DAPI node String attribute String value
Description Retrieves attribute of a given name and places it in a DAPI node Sets attribute of a given name and places it in a DAPI node
SetAttributeNode
SetAttributesNode
DAPI node Boolean preserveNodeId
Sets a DAPI node from attributes, and shows it if the node ID is left alone
34
4.4
4.4.5 DAPI Version Methods

The methods in Table 4-10 allow DAPI versions to interact with system attributes. Table 4-10: DAPI Version Methods
GetAttributeVersion
Parameters DAPIVERSION version String attribute
Description Retrieves attribute of a given name and places it in a DAPI version Sets attribute of a given name and places it in a DAPI version Sets DAPI version from attributes
SetAttributeVersion
DAPIVERSION versionString attributeString value DAPIVERSION version
SetAttributesVersion
4.4.6 Child-Level Methods

The child level of a node is the level of its XML tag from the root element. The methods in Table 4-11 allow the level to be retrieved and set. Table 4-11: Child-Level Methods
Return Type Integer Boolean Method Name
GetChildLevel IsTopLevelChild SetChildLevel
Parameters None None Integer level
Description Retrieves level of node from root Retrieves if the node is an immediate child of the root node Sets node child level
4.4.7 Node Value and Name Methods

A generic node has a name and a value associated with it. The name of the node is the name of the XML tag the node represents, and the value of the node is the data associated with that XML tag if there are no tags embedded in the primary tag. Table 4-12: Node Value and Name Methods
GetName
Parameters None
Description Retrieves the node name. This is the name of the XML tag.
35
Return Type
Method Name
GetValue Set SetName SetValue
Parameters None String name String value String name String value
Description Retrieves the node value. This is the value associated with the XML tag. Sets the node name and value. Sets the node name Sets the node value Retrieves the node value as a date Retrieves the node value as an integer
Date Integer
GetDateValue GetIntegerValue
4.4.8 Example Code

In the following code example, the script creates a node with the name Root. Then, it adds an attribute to the node. Finally, it adds a number of children to the node, and the node is displayed by echoing it to the terminal.
// define number of children to create Integer noChildren = 1 // now create a generic node to hold the new node Object root = $LLIApi.GenericNode.New(); if ( !IsDefined(root) ) return end // set node name root.SetName ( "Root" ) // set node attributes root.AddAttribute( "att1", "value" ) // create the child nodes Integer index for ( index = 0; index < noChildren; index +! ) Object child = $LLIApi.GenericNode.New(); if ( IsDefined(child) ) child.SetName( "Child " + Str.String(index) ) child,AddAttribute( "attr1", "value" ) root.AddChild( (child) ) end
36
4.4
end root.Display() root.Delete()
37
Chapter 5
Customizing XML Import and Export

This chapter covers the following topics:

XML Callback Handlers on page 39 Custom Object Types and XML Nodes on page 45 XML Built-Ins on page 55 Migrating to the New XML Implementation on page 56
5.1 XML Callback Handlers

Callback handlers are used to customize XML Import and Export. The callback functionality is defined by XmlCallback. To use callbacks, orphan the XmlCallback object to your Ospace and set the fName field to the name of your callback handler. For each object type, you will set the subtype to the type you are handling. For Livelink objects, this will be the subtype of the object. For pseudo-objects, this will be the name of the object (the name is case dependent). Note that this subtype is not an integer. The import callback methods are:

AddMetaDataTags AddRenditions AddSystemAttributes AddVersions CheckMetaData CheckObjectInfo ImportType PostCreate
The export callback methods are:

ExportAddVersions ExportCheckObjectInfo
39
Chapter 5 Customizing XML Import and Export
ExportType OrderChildList Write
5.1.1 Export Callback Methods

Export callbacks allow developers to modify the Versions exported, change the content exported, filter out certain object types, and add additional XML content. Table 5-1 describes the relevant methods. Table 5-1: Export Callback Methods
Method
ExportAddVersions
Description Called prior to exporting the Versions of an object. Allows users to control what Versions are exported.
Parameters node (DAPI node holding Version) versions (list of DAPI versions to add. Each element in the list is a DAPI version) options (any options used to control the export)
Returns Assoc OK (TRUE = success) Versions (list of Versions to add)
ExportCheckObjectInfo
Called prior to export of a DAPI node. Allows users to control attributes of a node. Be extremely careful when changing this information. Do not add or remove attributes. These attributes are used by XML Import to create a node. Called prior to export of a type. Allows users to filter out objects based on type.
node (DAPI node being exported) options (any options used to control the export)
Assoc OK (TRUE = success) ErrMsg (stores error message)
ExportType
handler (XML Export handler) options (any options used to control the export)
Assoc OK (TRUE = success) Export (TRUE = export the type) ErrMsg (stores error message)
40
5.1
XML Callback Handlers
Method
OrderChildList
Description Called during export to reorder the list of children, if needed.
Parameters node (the DAPI node of the node that was created) expChildren (list of children to export) options (any options used to control the export)
Returns List (ordered child list)
Write
Called after the object has been written and before the next object is added to the stream. Allows users to append additional output an to object.
Handler (XML Export handler) XMLWriter (where to output the export) obj (object being exported) options (any options used to control the export)
None
5.1.2 Import Callback Methods

Import callbacks allow developers to add metadata, modify the Versions imported, change the metadata, change the content, filter out certain object types, and add additional processing after a node is created. Table 5-2 describes these methods. Table 5-2: Import Callback Methods
Method
AddMetaDataTags
Description Called prior to

CheckMetaData call-
Parameters Handler (XML Export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById options (any options used to control the export)
Returns Assoc OK (TRUE = (import completed successfully) Tags (list of tags to add)
back. Allows users to control the add metadata sent to CheckMetaData. Note: Node tag or version tags may not be added to this list. Metadata tags are the immediate child tags that appear after llnode and before node.
41
Method
AddRenditions
Description Called prior to adding Renditions to a Version. Allows users to control what Renditions are imported.
Parameters handler (XML Export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById node (DAPI node holding Version) version (Version to add Renditions to) renditions (list of Renditions [DAPI versions] to add. Each element in the list is an Assoc with field names of a DAPI version. However, the "p" is removed from the DAPI version field name. options (any options used to control the export)
Returns Assoc OK (TRUE = (import completed successfully) Renditions (list of renditions to add)
AddSystemAttribute s
Called after an object is created. Allows the callback to add system attributes or modify those available from the import.
handler (XML export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById node (DAPI node to apply system attributes to) systemAttributes (system attributes to apply) options (any options used to control the export)
42
5.1
XML Callback Handlers
Method
AddVersions
Description Called prior to adding Versions to an object. Allows users to control what Versions are imported.
Parameters node (DAPI node holding Version) versions (list of DAPI versions to add). Each element in the list is an Assoc with field names of a DAPI version. However, the p is removed from the DAPI version field name. options (any options used to control the export)
Returns Assoc OK (TRUE = success) Versions (list of Versions to add)
CheckMetaData
Called to check or set metadata for an object. Allows users to control metadata of a node before it is created.
handler (XML Export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById dapiInfo (fields in Assoc are the fields of a DAPI node with "p" removed from field name) metaData (Assoc with name value metadata pairs for node type) childLevel (shows level of node in export; 0 is the top level, 1 is the next level, and so on) options (any options used to control the export)
Assoc OK (TRUE = success) ErrMsg (stores error message)
43
Method
CheckObjectInfo
Description Called prior to creation of the DAPI node representing the object. Allows users to control attributes of a node.
Parameters handler (XML Export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById dapiInfo (fields in Assoc are the fields of a DAPI node with "p" removed from field name) childLevel (shows level of node in export; 0 is the top level, 1 is the next level, and so on) options (any options used to control the export)
Returns Assoc OK (TRUE = success) ErrMsg (stores error message)
ImportType
Called prior to import of a type. Allows users to control if a type is imported.
handler (XML Export handler); to get prg session, use GetPrgSession; to get node by ID, use GetNodeById dapiInfo (fields in Assoc are the fields of a DAPI node with p removed from field name) options (any options used to control the export)
Assoc OK (TRUE = success) Import (TRUE = import the type) ErrMsg (stores error message)
PostCreate
Called after the node is created to allow post creation processing.
handler (XML Export handler) genericNode (generic node holding parsed XML) node (DAPI node that was created) options (any options used to control the export)
None
44
5.2
Custom Object Types and XML Nodes
5.2 Custom Object Types and XML Nodes

Custom object types allow Livelink developers to tailor Livelink to their needs. These types also may require XML Import and Export, which can require an XML node handler. The following sections outline how XML nodes can be used to handle XML processing for custom objects.
5.2.1 Getting an XML Node

In most cases, XML nodes are provided as part of a method call. However, in some cases you will need to get an XML node from the XmlNodeSubsytem directly. The example below illustrates how to do this:
// how to get the folder object type xml node Dynamic subtype = 0 Object xmlNode = $Xml.XmlNodeUtil.GetXmlNode( subtype ) Notice the subtype is dynamic. GetXmlNode supports integers and strings as the subtype. Strings are used to provide support for pseudo object types such as project overview.
5.2.2 XML Node Fields

Table 5-3 shows the fields of an XML node. Table 5-3: Fields of an XML Node
Field
fElementName fEnabled fPlainMimeType fUseVersionStream fSubtype
Description XML tag name used to export the node type Shows if the type is registered with the XML node subsystem Stores a list of MIME types that are base64 encoded Shows if a DAPI version stream is used to export the Version contents Type used to register the node
To add a new XML node to your Ospace, orphan the XmlNode object to your Ospace and set the fSubtype field. For Livelink objects, this will be the subtype of the object and for pseudo-objects the name of the object (the name is case dependent). Then set fEnabled to TRUE, run the Build Ospace function for your module, save all changes, and exit. In Table 5-3, the field fUseVersionStream is shown. This field controls how the content for a versionable object is exported. In almost all cases, NodeFetchVersion, from your types LLNode, should be used to get Version content. However, if your node requires a DAPI version stream, set fUseVersionStream to TRUE.
45
5.2.3 XML Node Methods

XML node methods can be placed into three categories:

Methods used during export Methods used during import Metadata methods
The following sections discuss these categories of methods and how they are used.
Export Methods
Export methods are used to perform an XML serialization of an object. There are two export methods: WriteMetaData and WriteVersionMetaData. Metadata is the data unique to an object type. For a Version, metadata is used to give additional details about the Version content. In most cases object metadata is the most important. Table 5-4, gives a description of the WriteMetaData method: Table 5-4: XML Node Export Methods
Method
WriteMetaData
Description Write any additional child tags (data) that are needed to create the object when it is imported. Metadata can best be described as the data used by your object during node creation. For example, an Alias (Shortcut) in an object that points to another object and its metadata is the IDS of the node it points to. If you create a node type that has an
LLNode::NodeCreatePre which
Parameters handler (XML Export handler) xmlWriter (used to output XML) node (DAPI node representing the object) options (any options used to control the export)
Returns Assoc OK (TRUE = metadata was written successfully) ErrMsg (text describing errors on failures)
validates creation information then the creation information should be your node type's metadata. The XmlWriter is used to write your metadata to the XML stream.
46
5.2
Method
WriteVersionMetaData
Description Called during export to allow the node to return a list of nodes it is dependent on. This method is used by XmlDependentsExport to return a list of nodes by ID that your node is dependent on. Using Alias (Shortcut) as an example, the dependents list would contain one element the ID of original node. As a rule of thumb, you should return the IDs of any nodes needed by your node if it were created on another system.
Parameters node (DAPI node of the node that was created) options (any options used to control the export)
Returns Assoc OK (TRUE = metadata was written successfully) ErrMsg (stores error message) Dependents (list of dependent nodes by ID)
Import Methods
Import methods are used during XML Import to create objects from the XML produced by an XML Export. As a developer, you will use these methods in some combination to create your node type. These methods can be separated into three types.
LLNode::NodeCreate:

Methods used to convert metadata into node creation information used by

CheckNode CheckNodeId GetCreateInfo
Methods used to finalize object creation:

CheckDependents PostCreate
Method used to add a new Version by LLNode::NodeAddVersion:
GetVersionInfo
47
XmlNode Metadata Methods

Metadata is the data that is required by your node type during creation (other data can be included at your discretion). Metadata is exported using the WriteMetaData method of XmlNode. The handling of export is straightforward, and there are several examples you can use from the XmlNodeSubsystem. During import, the metadata held in a GenericNode node needs to be converted to an Assoc. To do this, XmlImport uses the XmlNode method GetMetaData. This method takes a GenericNode, which stores the parsed XML in the parent-child relationship it was written in, and converts the metadata into an Assoc. There are two types of metadata: node metadata and Version metadata. Version metadata is rarely used, but it provides any additional information you might need when creating Versions. <Node metadata> is your node creation data. To get node metadata, XmlImport calls the method GetMetaDataTags, which returns a list with the names of your node metadata tags. To get Version metadata, XmlImport calls the XmlNode method GetVersionMetaDataTags, which returns a list with the names of your Version metadata tags. XmlImport then get the data from the GenericNode using the tag names. Table 5-5 describes the XmlNode metadata methods Table 5-5: XmlNode Metadata Methods
Method
GetMetaDataTags GetVersionMetaDataTags
Description Get a list of the metadata tags for this Version Get a list of the parent metadata tags for this object.
Parameters none none
Return List List (list of parent tag names for the object's Version metadata)
Export Ordering of Child Nodes

In some cases, your node type will have children. When XmlExport runs, it will write the children in the order returned by DapiNode.ListContents. If any of the children need to placed before any other children, you will need to order your export list. To do this, the XmlNode method OrderChildList is provided. It takes the list of children to be exported, and if you override the method you will be able to order the children to suit your needs. For example, XmlNode provides the base OrderChildList method, which orders by Categories, other children, and Shortcuts. This allow categories to be created before other nodes in the child list that might use the Category, and it allows any nodes that might be referenced by a Shortcut to be created before the Shortcut. Table 5-5 on page 48 describes the method OrderChildList
48
5.2
Table 5-6: OrderChildList Method

Metjhod
OrderChildList
Description Called during export to reorder the list of children, if needed, so that import processing is simpler.
Parameters node (DAPI node of the node that was created) expChildren (List of children [DAPInode] to export) options (any options used to control the export)
Return List (ordered child list)
Subclassing of Nodes
Your node could subclass another node type, or others can subclass your node's custom node type. To make subclassing easier, there are five import and export methods provided (their names all end in "Subclass"). Table 5-7 describes the methods provided for import. Table 5-7: Import Subclass Methods
Method
GetCreateInfoSubclass PostCreateSubclass
Description Provides for handling of create information for subclassing. Provides for post-creation handling for subclassing.
Table 5-8 describes the methods provided for export. Table 5-8: Export Subclass Methods
Method
OrderChildListSubclass WriteMetaDataSubclass
Description Provides the ability to order children for subclassed nodes. Provides the ability to write additional metadata tags for subclassing.
Table 5-9 describes the method provided for metadata handling. Table 5-9: GetMetaDataTagsSubclass Method
Name
GetMetaDataTagsSubclass
Description Provides the ability to add parent metadata tags for a subclassed node.
If you subclass a node type, your overridden Subclass methods will be called during export and import. If your node is subclassed, you must call these methods at the end of your non-subclassed method.
49
Handling Node Creation

If your custom object uses NodeCreateSubclassPre or NodeCreateSubclassPost, or overrides the NodeCreateSubclass of LLNode, you will need to override GetCreateInfo. This method is used to set your specialized creation information. It is called prior to LLNode::NodeCreate. It converts metadata to node-creation information. Table 5-10 describes the method and its parameters. Table 5-10: GetCreateInfo Methods
Method
GetCreateInfo
Description XML node descendants override this method to convert metadata to nodecreation information.
Parameters handler (XML Import handler) createInfo (Assoc passed into LLiApi
NodeCreate
Returns Boolean (TRUE = OK to proceed with create) ErrMsg (stores error message) Dependents (list of dependent nodes by ID)
method) genericNode (generic node holding parsed XML Import data) node (DAPI node being created) options (any options used to control the export)
The parameter handler that is passed to the method is derived from ImportHandler, which defines the base functionality needed by an XML Import handler. The handler provides methods for querying for nodes using GetNodeById. Remember, an XML file does not have to be imported into the same system it was exported from, so any node IDs referenced in the XML file are stored by the handler in a table that maps node IDs from the XML file to the node ID of the newly created node. The handler is also responsible for the XML import log, which is used to store debugging information. Any information that might be useful for debugging can be written to the log using the method DebugStr. The parameter createInfo holds node-creation information and is passed to LLNode:NodeCreate, so createInfo should have the keys and values expected by your node type. The parameter genericNode is a generic node that holds the parsed XML in the same parent-child relationship as represented in the XML export file. Generic nodes have methods to walk the XML tag tree and gather tag names and values. The values are stored in createInfo after being converted from strings to native values.
50
5.2
Examples of how GetCreateInfo is used are found in the object types derived from XmlNode. A simple reference is the Livelink object Alias (Shortcut).
Additional Node Create Methods
CheckNode and CheckNodeId
These are helper methods that allow developers a place to validate nodes by a node reference or ID. Their use is optional.
GetVersionInfo
This method is used during object creation to add a new Version to a node.
CheckDependents
This method is called after all the nodes in an import are processed. It can be used to check any external node dependencies or to make any fix-ups needed.
PostCreate
This method is called after a node is created. It can be used to check dependencies or make needed fix-ups. For example, when a Project is exported it includes the list of participants. When PostCreate is called for a Project, the participants in the export file are added to the Project.
Handling Versioned Nodes

If your custom object uses NodeAddVersionSubclassPre or NodeAddVersionSubclassPost, or if it overrides the NodeAddVersionSubclass of LLNode, you will need to override GetVersionInfo. It is called prior to LLNode::NodeAddVersion and is used to set your specialized add Version information into the add Version Assoc passed to LLiApi.LLNode.NodeAddVersion. Table 5-11 describes the GetVersionInfo method:
51
Table 5-11: GetVersion Info Method

Method
GetVersionInfo
Description XML node descendants override this method to get any specaliazed creation information they need during node import
Parameters handler (XML Import handler) node (node that will hold new Version) genericNode (holds parsed XML for node) addVerInfo (Assoc passed into
LLiApi::NodeAd Version method
Returns Boolean (TRUE = OK to proceed with create)
genNode (holds parsed XML for Version) options (any options used to control the export)
When import handles Versions, it uses temporary files to store Version content. These files are stored in the Livelink installation's temp directory. The name of the file stored is added as an attribute of the generic node. In most cases, extracting the file name and handling of adding the Version are performed by the method GetTmpFileContent. The XML node Document is a good example of how to handle adding new Versions.
Metadata Methods
Metadata methods are used to get, set, and change metadata, as well as write the metadata to an XML stream. Metadata is used to describe an object in more detail. Some object types store their metadata in the extended data field of the DAPI node; others use a SQL data table. In either case metadata tags should be used during export to describe the object data. Metadata tags make the export easier to understand, and allow XML skin developers direct access to information needed to display your object. Shown below is an export of an Alias (Shortcut). The node referenced by the alias is stored in the originalid metadata tag.
<llnode ... > <orignalid>4240</originalid> <llnode ... >
52
5.2
Export calls the method WriteMetaData to allow objects to write their metadata using an XML writer. Metadata should map directly to node-creation information; however, other information can be included. For example, the XML callback method AddMetaDataTags can be used by callback developers to add metadata. When XML Import runs, it stores the parsed XML in generic nodes. Generic nodes hold the parsed XML in the same parent-child relationship as represented in the XML Export file. Developers can walk the parent-child tree to extract the parsed XML. The parsed XML is converted to and from the callback format using GetMetaData and SetMetaData. GetMetaData converts the metadata to the callback format, and SetMetaData converts the metadata from the callback format. Both of these utility methods need to know which tags are metadata and which are not. They use the GetMetaDataTags to get a list of the parent metadata tags and walk each parent tag to convert any child tags. There is a wealth of metadata examples in the XmlNode subsystem.
Using Generic Nodes

Generic nodes store the parsed XML for XML tags and hold other generic nodes in the same parent-child tag. To retrieve the name of an XML tag, use GetName, and to get the value of an XML tag, use GetValue. Since XML tags can hold values or other child XML tags, generic nodes provide methods for getting child tags by list and name. Methods that are case insensitive have an I at the end of the method name. XML tags also have attributes, and methods are provided to get attributes by list and name. Attribute methods that are case insensitive have an I at the end of the method name. Remember that all XML tag and attribute values are strings. Therefore, they must be converted to native types, and verification code must be added to check if a value or attribute can be converted to a specific native type. As an example, look at the how an Alias is handled. Aliases store the ID of their original node as a string, which must be converted to an integer.
Object child String strSourceId Integer sourceId Object xmlCnsts = $Xml.XmlConstants // get source id of alias node child = genericNode.GetChildByName( xmlCnsts.ORIGINAL_NODE ) if ( IsDefined( child ) ) strSourceId = child.GetValue() if ( IsDefined( strSourceId ) ) sourceId = Str.StringToInteger( strSourceId ) end end
The method GetChildByName, of generic node, is used to get the child XML tag originalnode, and then the method GetValue is used to get the original node ID as
53
a string. The string is then converted to an integer and stored in the parameter createInfo. Note that the XML tag name is placed in an object that stores the XML tag name as a constant. This allows the tag name to be stored in one place and makes the code easier to read and modify later.
Using XmlWriter
XmlWriters come in several flavors. Each flavor supports a different output stream type. However, all the flavors use the same methods to write XML tags:

StartElement EndElement WriteElement
When writing an XML tag that has child tags, sandwich the child tags between StartElement and EndElement calls. Each child tag can be written using the WriteElement method if the child tags do not have children. Begin a new element with optional attributes. The element is added to the element stack and any attributes are written out. Table 5-12 describes the GetCreateInfo method and its parameters. Table 5-12: GetCreateInfo Methods
Parameter
StartElement
Description XML node descendants override this method to convert metadata to nodecreation information. Closes the currently open element. Writes out the contents of an XML tag element (all data, except CDATA sections are escaped).
Parameters tagname (name of XML tag) atts (attributes of XML tag) None tagname (name of XML tag) value (value associated with tag) atts (attributes for tag)
EndElement WriteElement
XmlWriters have an internal stack that keeps track of StartElement and EndElement calls, so when EndElement is called the top of the stack is popped to get the last written tag name. This is why EndElement does not require a tag name. XmlWriter has been updated to include support for case sensitivity. In the previous version, all tag names were converted to lowercase before being written to their XML stream. Now, tag names are written in a WYSIWYG fashion. For example, attributes to a tag will appear exactly as they were added to an Assoc:
Assoc result Assoc atts Object xmlWriter result = $Xml.XmlUtil.GetWriter() xmlWriter = result.Writer
54
5.3
XML Built-Ins
Atts.IsItAway = "Yes" Atts.isItAway = "Yes" Atts.isitaway = "Yes" xmlWriter.StartElement( "Away", atts ) xmlWriter.EndElement()
For example, if you write one XML tag Awaywith the attribute IsItAway, the output will look like the following:
Old Appearance
<away "isitaway"="yes" />
New Appearance
<Away "IsItAway"="Yes" />
The old XML output has all capitalization removed, while the new XML output preserves it. The example also demonstrates an important point; an OScript Assoc key is case sensitive when it is output to an XML stream. Developers can use the Assoc.Keys method to get a list of the keys for this Assoc and echo the list. To get an XmlWriter, use the method GetWriter of XmlUtil with the stream to write output to the GetVersionInfo method. Table 5-13 describes the GetVersionInfo method. Table 5-13: GetVersion Info Method
Method
GetWriter
Description Get an XML writer.
Parameters output (where output of writer is directed)
Returns Assoc OK (TRUE = success) ErrMsg (text describing errors on failures) Writer (XML writer)
The output parameter can be undefined. In this case, GetWriter returns an XmlStringWriter, and the method GetBuffer can be used to get the XML written to the writer.
5.3 XML Built-Ins

Built-ins allow users to extend the behavior of XML Export by adding named builtins to Livelink. For example, one of the XML built-ins allows a breadcrumb trail to be exported for any node. (A breadcrumb trail is the path to the node in the Livelink system.) To use a built-in for export, add the name of the built-in to the export URL. If you need to add an XML built-in to the system, orphan the XmlBuiltin to your Ospace.
LLESCOR090701-PGD-EN-1 XML Import and Export Guide 55
Set the fName field to the name of the built-in. The name must start with Xml. This allows URL parameters to be placed into the options Assoc, which is used to control XML Export.
5.4 Migrating to the New XML Implementation

This section describes the changes required to make to use the new XML Ospace.
5.4.1 URL Migration

For import users, no changes are required. However, export users must be aware of the permissions parameter, which controls the export of permissions on a node. If the parameter is not present in the URL, permissions will not be exported.
5.4.2 Script Migration

Script examples of Export and Import in Chapters 2 and 3, respectively. In all cases, you should be able to copy the relevant script example and then change the options for your application.
5.4.3 Custom XML Node Migration

This section describes changes to methods and parameters that may affect the migration of your custom XML nodes to the new implementation of XML Export and Import in Livelink.
GetCreateInfo
The method has its first parameter changed from importConfig to handler. The handler is the new XmlImportHandler. This object provides the familiar GetNodeById. If you were using the XML node method DebugStr for logging, change from .DebugStr to handler.DebugStr. Last the new options parameter is added to the call as the last parameter of the method call.
GetVersionInfo
Like GetCreateInfo, the first parameter has changed from importConfig. The parameters node (the DAPI node) and genericNode (holds the parsed XML for the node) have been added. The verGenericNode was the old genericNode; it holds the parsed XML for the DAPI version. The options parameter was added as the last parameter.
WriteNodeTypeInfo
The name of the WriteNodeTypeInfo method has been changed to WriteMetaData, and the first parameter changed from importConfig to handler. Handler, as mentioned previously, is the handler for XML Import.
56
5.4
Migrating to the New XML Implementation
Metadata Handling
Allowing callback handling of metadata requires adding the method GetMetaDataTags to tell XML Import what information must be passed to the callback. From this method, add code to return only the top-level tags of your metadata. This list gives XML Import the ability to extract the information from a generic node and pass it to the callback handler.
Import Handler Migration

If you have overridden either XmlImportConfig or XmlCreateNode from a previous version, migration will be slightly more difficult, because these objects have been combined into a new object named XmlImportHandler. The new import handler combines the previous configuration and node-creation handling into one object to simplify the process of XML Import. Open Text recommends that developers who overridd these objects consider using XML callbacks.
57
Index
$nopage\>Log files. See XML Import. 22 $nopage\>XML transforming into HTML. See XML Skins 9 < 22, 9 A About This Guide 11 C Callback handlers 39 Callback methods XML Export 40, 39 XML Import 39 Custom object types 45 D DAPI node 28, 27 F Feedback 8 G Generic nodes 27 methods for working with 32 M Metadata 57, 49, 47, 46, 41 Metadata methods 52 O Open Text Online 7 opentext.ini file 16 P Permissions 13, 14, 28 to perform an XML import 19 Permissions parameter 56 S SAX parser 26 Subclass methods 49 X XML Livelink-specific tags 27 transforming 9 XML DTD 9 XML Export 9 parameters 13 performing using a URL 13 performing using OScript 16 XML Import 9 DocumentHandler interface 26 general architecture 26 log files 22 parameters 19 performing using a URL 19 performing using OScript 22 XML Import and Export Objects 25 XML Skins 10 XmlCallback 39 XmlUtil\\ Import Method 24 XmlWriter 55, 54, 54 XMLWriter 41 XSL 10 XSLT 10
59

Livelink ECM - Enterprise Server XML Import and Export Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Livelink ECM - Enterprise Server XML Import and Export Guide

Uploaded by

Copyright:

Available Formats

Livelink ECM Enterprise Server XML Import and Export Guide

Copyright 2007 by Open Text Corporation

.................................................................................................... 5 Introduction ............................................................................... 9

Using XML Export ................................................................... 13

Using XML Import.................................................................... 19

XML Import and Export for Developers ................................. 25

Customizing XML Import and Export ..................................... 39

Livelink ECM Enterprise Server

Typographical Conventions Used in This Guide

Livelink ECM Enterprise Server

Convention These items appear in italic typeface. Examples:

First-Time Installation Guide.

You can scan new documents for content

of interest by saving your search criteria in a query called a prospector.

In your Web browser, go to the default

These items appear in "quotation marks." Examples:

Livelink ECM Enterprise Server

Item Key names

Convention Key names appear in ALL CAPS. Examples:

typing in this field.

To select multiple items, hold down the

You can access the Knowledge Center at: https://knowledge.opentext.com.

Downloads and patches

XML Import and Export Guide

Documentation Product information Discussions Product previews

Livelink ECM Enterprise Server

Figure 1-1: Sample of XML Code Representing a Livelink Folder Object

1.1 Transforming Exported XML

Livelink ECM Enterprise Server

Figure 1-2: Sample View of a Livelink Folder Using XML Skins

Livelink ECM Enterprise Server

About This Guide

1.2 About This Guide

XML Import and Export Guide

Using XML Export

2.1 XML Export Using a URL

Livelink ECM Enterprise Server

Chapter 2 Using XML Export

Table 2-1: Optional XML Export Parameters

Description Determines child depth of export

immediate child nodes only

all = export all Versions current =

export current Version only

Livelink ECM Enterprise Server

XML Export Using a URL

Determines whether the current context is exported

Used = true Not Used = false

XML Import and Export Guide

Chapter 2 Using XML Export

Values Used = true Not Used = false

2.1.1 Configurable Settings

2.2 XML Export Using OScript

Livelink ECM Enterprise Server

XML Export Using OScript

XML Import and Export Guide

Chapter 2 Using XML Export

echo ( "users exported: " + Str.ValueToString( ) DisplayUsers( prgCtx, result.UsersExported )

Livelink ECM Enterprise Server

Using XML Import

3.1 XML Import Using a URL

Livelink ECM Enterprise Server

Chapter 3 Using XML Import

Table 3-1: Optional XML Import Parameters