livelink ecm - enterprise server xml import and export guide

8/2/2019 Livelink ECM - Enterprise Server XML Import and Export Guide

1/59

Livelink ECM Enterprise Server

XML Import and Export Guide

This guide describes and explains how to use Livelinks XMLExport and XML Import features.

LLESCOR090701-PGD-EN-1


2/59

Livelink ECM Enterprise ServerXML Import and Export GuideLLESCOR090701-PGD-EN-1Rev.: 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: [email protected]

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 own-

ers. All rights reserved.
mailto:[email protected]://ftp.opentext.com/ftp://ftp.opentext.com/http://www.opentext.com/http://www.opentext.com/mailto:[email protected]://ftp.opentext.com/http://www.opentext.com/


3/59

LLESCOR090701-PGD-EN-1 Livelink ECM Enterprise Server 3

Table of Contents

Preface .................................................................................................... 51 Introduction ............................................................................... 91.1 Transforming Exported XML ....................................................................91.2 About This Guide ................................................................................... 11 2 Using XML Export ................................................................... 132.1 XML Export Using a URL....................................................................... 132.2 XML Export Using OScript.....................................................................163 Using XML Import.................................................................... 193.1 XML Import Using a URL .......................................................................193.2 XML Import Using OScript .....................................................................224 XML Import and Export for Developers ................................. 254.1 General Architecture ..............................................................................254.2 XML Import Step by Step....................................................................... 274.3 Creating a Database Connection........................................................... 304.4 Working with Generic Nodes ................................................................. 325 Customizing XML Import and Export..................................... 395.1 XML Callback Handlers ......................................................................... 395.2 Custom Object Types and XML Nodes.................................................. 455.3 XML Built-Ins .......................................................................................... 555.4 Migrating to the New XML Implementation............................................ 56IX Index......................................................................................... 59


4/59


5/59


Preface

This preface explains the typographical conventions used in this guide and providesOpen Text contact information.

Typographical Conventions Used in This Guide

All information in the following table is case-sensitive unless otherwise noted.

Item Convention

File names, directory names, folder names,path names, window names, dialog boxnames, Web page names, URLs, and e-mailaddresses

These items appear in regular (normal)typeface. Some elements in italic indicateplaceholders.

Examples:

Run setup.exe to start the installationprogram.

Open theLivelink_home/config/opentext.ini file ina text editor.

Note: The placeholder Livelink_homerepresents the Livelink rootdirectory (directory where Livelinkwas installed).

Send an e-mail message [email protected] to contact OpenText Customer Support.

In the Windows XP Control Panel, dou-ble-click the Services icon to open theServices dialog box.

Names of user interface elements, such asbuttons, links, menus, check boxes, radiobuttons, 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 theStart button.

Click the items Functions icon, chooseProperties, and then choose General.

Click the Admin Home link.


6/59

Preface

6 Livelink ECM Enterprise Server LLESCOR090701-PGD-EN-1

Item Convention

Variable placeholders, references to otherdocuments, new or special terminology,

and emphasis

These items appear in italic typeface.

Examples:

For more information, see the LivelinkFirst-Time Installation Guide.

You can scan new documents for contentof interest by saving your search criteriain a query called aprospector.

In your Web browser, go to the defaultLivelink start page at

protocol://host:port/URL_prefix/livelink.exe, whereprotocol is http or https, host isthe DNS name of the HTTP server host,

port is the port number on which theHTTP server is listening, and URL_prefixis the prefix mapped to the

Livelink_home/cgi directory in the HTTPserver.

References to chapters and sections ofdocuments, and citations of messages dis-played to users

These items appear in "quotation marks."

Examples:

For more information, see Chapter Three,"Projects," in the Livelink QuickStart forUsers 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 "Databaseimport completed without errors."

Operating system commands, code exam-ples, feature names, method names, objectnames, and text typed by users

These items appear in a monospaced font.

Examples:

In the User Name field, typeAdmin.

At the operating system prompt, typestart-llserver , and then press ENTER.

When searching for users, you can set themaximum number of users displayed perpage by setting the value (default is 30)of the MaxUsersToListPerPage parameter in the [general] section ofthe opentext.ini file.


7/59

Preface

LLESCOR090701-PGD-EN-1 XML Import and Export Guide 7

Item Convention

Key names Key names appear in ALL CAPS.

Examples:

Press ENTER to start a new line whentyping in this field.

To select multiple items, hold down theCTRL key while you click the items thatyou want to select.

Contact Information

Open Text Online is a single point of access for the product information provided byOpen Text. Depending on your role, you have access to different scopes ofinformation (see below for details).

Furthermore, the following information and support sources can be accessedthrough Open Text Online:

Knowledge CenterOpen Text's corporate extranet and primary site for technical support. It is theofficial 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 CenterThe Expert Service Center (ESC) is a source of up-to-date informationcontinually 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 usersin one of the Open Text online communities

Administrators/Developers

Downloads and patches
https://knowledge.opentext.com/https://knowledge.opentext.com/


8/59

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 ourdocumentation, contact us by e-mail at [email protected].
https://esc.ixos.com/http://online.opentext.com/http://online.opentext.com/http://support.opentext.com/http://support.opentext.com/mailto:[email protected]://esc.ixos.com/http://online.opentext.com/http://support.opentext.com/mailto:[email protected]


9/59


Chapter 1

Introduction

Livelink's XML Import and XML Export features let you exchange Livelink datawith other XML-compliant systems. XML Export enables the information associatedwith a Livelink volume or node to be translated into XML code and exported as afile that can be used by another application, such as a data archive. XML Importdoes 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 importingan XML file. The only restriction is that the object specified by the XML file mustconform to Livelink's native XML schema.

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

1.1 Transforming Exported XMLWhen you export a Livelink node as XML, the XML Export function gives yousignificant control over the structure of the XML files that Livelink generates. It alsogives you the option to transform the Livelink-native XML document structure intoWeb-friendly HTML. There are two ways to accomplish this:


10/59

Chapter 1 Introduction


On the client side, by using an XSL (Extensible Stylesheet Language) stylesheetand Livelink's built-in XSLT(Extensible Stylesheet Language Transformation)processor. This client-side transformation capability has been called XML Skinsbecause 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 aclient application, such as a Web browser, can perform the transformation.

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


11/59

1.2 About This Guide


1.2 About This Guide

The goal of this guide is to explain Livelink's XML Export and XML Importfunctions to two audiences: (1) experienced Livelink users who need to use thesefeatures, and (2) developers who need to understand in detail how the XML Exportand XML Import functions work and how to extend them. describes the chaptersand appendixes in this guide.

Table 1-1: Description of Chapters

Title Description

Chapter 1,Introduction onpage 9

Describes the basic characteristics of XML Import and Export and ofthis guide.

Chapter 2, Using XMLExport on page 13

Explains how to export Livelink nodes as XML files.

Chapter 3, Teaches experienced Livelink users how to import XML files to createa new Livelink node.

Chapter 4, XML Im-port and Export for De-velopers on page 25

Describes in detail how XML Import and Export work, including en-hancements made in Livelink 9.5.0.

Chapter 5,Customizing XML Im-port and Export onpage 39

Explains how to extend XML Import and Export to support your cus-tomizations.


12/59


13/59


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. Formore 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 onpage 22.

2.1 XML Export Using a URL

The XML Export function lets you export a Livelink volume or node and the data itcontains as an XML file. You perform an XML export by typing a Livelink URL intoa Web browser. A number of required and optional parameters contained in theURL control the content and format of the resulting file.

Note: Any Livelink user can perform an XML Export. The only restriction isthat the user must have the See permission for the volume or node to beexported 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=

where is the Livelink ID of the node to be exported.

To perform an XML Export:

Open the following in a Web browser:

?func=ll&objAction=XMLExport&objId=&

where is any of the following parameters that you can useto tailor a particular XML export. These parameters are explained in Table 2-1:


14/59

Chapter 2 Using XML Export


Table 2-1: Optional XML Export Parameters

Parameter Description Values

scope Determines childdepth of export

sub = export the objId and all child nodesone = export the objId node and itsimmediate child nodes only

base = export only the objId node

(an integer greater than 0) = exportthe node and its direct descendants up to levels below the node: 1 for one levelbelow, 2 for two levels below, and so on

nodeInfo Determines whetherDAPI node informa-tion is exported

If included, DAPI node information isexported, along with a list of exportednodes This must be specified to importthe exported content.

attributeInfo Determines whethercategories and systemattributes applied tothe node are exported

If included, Categories and attributes areexported

versionInfo Determines whetherVersions of the nodeare exported

all = export all Versions current =export current Version only

(an integer greater than 0) = exportthe node and Version number

If no value is specified, all Versions areexported.

content Determines whetherthe content of Versionsis exported, and theencoding format

plain = export Version content as plaintext base64 = export Version content asbase64-encoded text

cdata = export Version content as plaintext wrapped in a cdata tag.

If no value is specified, base64 is used.

This must be specified to import theexported Categories.

The cdata or base64 attributes should beused when the content of a document isXML. The versioninfo parameter mustbe present with content or an error willoccur.


15/59

2.1 XML Export Using a URL



permissions Determines if permis-sions are exported

with the node

If included, permissions are exported.This parameter must be used with the

nodeinfo parameter or it will be ignored.extuserinfo Exports the name, user

ID and domain of thecreator, owner andgroup owner.

If included this information can be usedby Import to restore the creator, ownerand group owner when a node is created(if the export is imported into the systemit was exported from). This parametermust be used with the nodeinfo parame-ter or it will be ignored.

schema Determines if aLivelink schema refer-ence is exported

If included, a Livelink schema referenceis exported

stylesheet Stores the path and

filename of a stylesheet to be applied tothe XML

If included, perform transform using the

style sheet This parameter must be usedwith the transform parameter or an er-ror will occur.

transform Stores the name of theXML transform to ap-ply.

If included, transform using the Xalantransform engine.transform= performstransform using your own customtransform engine

This parameter must be used with thestylesheet parameter or an error willoccur.

callbackhandlername Name of the callbackhandler used to add toor alter the XML con-tent of the export (forexample, to orphan thehandler to an ospaceand give it a name. Touse the handler in anexport, addCallbackHandlerName

= tothe URL.

Used = Name of the callback handlerused Not Used = no callbacks used

context Determines whetherthe current context isexported

Used = true Not Used = false


16/59




followaliases Determines whetherAliases (now called

Shortcuts) are replacedwith the node theyalias

Used = true Not Used = false

2.1.1 Configurable Settings

The [XML] section of the opentext.ini file has several parameters that can beconfigured 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 embeddedin the XML export (for example, ). 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. Thedefault MIME type must be indicated here or specified in the cdata and plainparameters 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 thefollowing 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


17/59

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 ) )


18/59



echo ( "users exported: " + Str.ValueToString(

result.UsersExported ) )

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


19/59


Chapter 3

Using XML Import

XML Import was designed primarily for importing Livelink data structures that arecreated by the XML Export feature or manually. It is only able to import data thatconforms 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. Formore information, see XML Export Using a URL on page 19.

Scripting language method, which performs the XML Import programmaticallyusing OScript. For more information, see XML Export Using OScript onpage 22.

Note: Only the Livelink Administrator or users with the System administrationrights 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:

?func=admin.xmlimport&filename=&objid=

In the example, the request admin.xmlimport causes the XML file specified by thefilename parameter to be imported. The numeric value is the node ID ofthe existing Livelink object (node or volume) that will contain the objects to becreated.

Note: The file to be imported must be on the server and must be referencedfully 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 thelocation of the log file generated by the process, when the import was started, andwhether 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 conformsto the Livelink DTD.

Note: If you manually create an XML file to import, any subsequent alterationsto the Livelink schema will invalidate your file.

Optional XML Import parameters are described in Table 3-1:


20/59

Chapter 3 Using XML Import


Table 3-1: Optional XML Import Parameters

Parameter Description Value

extuserinfo Import the creator, ownerand group owner usingthe exported creator,owner and group owner,if they exist. Nonexistententities are ignored.

Used = creator, owner, and groupowner are imported.

creator If used with just theparameter name (i.e., noattribute), import uses theexported creator as thecreator. The exportedowner must exist in thesystem or it will not beused. If included with

parameter (the IDof user in the systembeing imported into),import user as thecreator. To use thisfeature, the export musthave included theextuserinfo parameter.

Used without value = uses the ex-ported creator creator = (uses ID of the user in the systemyou are importing into)

owner If used with just the pa-rameter name (i.e., no at-tribute), import uses theexported owner as theowner. The exportedowner must exist in thesystem or it will not beused. If included with pa-rameter (the ID ofuser in the system beingimported into), importuses as theowner. To use this featurethe export must have in-cluded the extuserinfoparameter.

Used without value = uses the ex-ported owner owner = (uses ID of the user in the systemyou are importing into)


21/59

3.1 XML Import Using a URL


Parameter Description Value

groupowner If used with just theparameter name (i.e., no

attribute), import uses theexported group owner asthe group owner. Theexported group ownermust exist in the systemor it will not be used. Ifincluded with parameter(the ID of user inthe system beingimported into), importuses as the groupowner. To use this featurethe export must haveincluded the extuserinfo

parameter.

Used without value = uses the ex-ported group owner groupowner =

(uses ID of the user in thesystem you are importing into)

inheritpermissions Causes any nodes createdby import to inherit per-missions from their par-ent. For some parent nodetypes that can force theinheriting of permissions(projects, for example)inheritpermissions willbe ignored.

Used = created nodes inherit par-ent permissions Not Used = per-missions not inherited

dontaddacls Causes any permissions

in the export file to not beimported.

Used = permissions not imported

callbackhandlername Name of the callbackhandler used to controlsome features of import.To use this parameter, or-phan the xmlcallbackhandler to an ospace andgive it a unique name. Touse the handler in an im-port, addCallbackHandlerName= to theURL.

Used = Name of the callback han-dler used Not Used = no callbacksused

In addition to the base parameters, there are user-defined import parameters, whichare used to customize XML Import. These parameters are passed by the optionsAssoc to XML nodes and callback handlers. User-defined parameters must startwith the characters "Xml". These parameters are intended for use by programmerswho are developing callback handlers and for XML-node developers.


22/59



3.2 XML Import Using OScript

XML Import can also be performed programmatically, using OScript. Import is thebase class for XML Import. It is used to import OScript data types and provides basemethods 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 fNamefield. 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. Ifnecessary, it also generates an xmlimporterrors.log file. These files are stored inthe /logs directory.

3.2.1 Examples

The following examples demonstrate how to perform an XML import using OScript.

Import Using a Handler NameNote: This example contains a parameter called cleanup. This parameter isnecessary to enable the debugging of an import using Livelink Builder. Becauseof the way Builder works, breakpoints are not triggered in Builder until afterthe end of document has been received from a parser. However, when the endof 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 tofalse, keeps the objects used by the parser alive so that debugging can beperformed.

// 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


23/59

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


24/59



Importing Using the XmlUtil::Import Method

OScript data types can be imported using the XmlUtil::Import method, as shownin 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 ) )

endend

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. Thebuffer is passed to XmlUtil::Import. After import executes, the return Assoc willhave a value member, which stores the imported OScript type.


25/59


Chapter 4

XML Import and Export for Developers

This chapter describes the following aspects of the XML Import function in detailand how the XML Export function must be extended when you add a new objecttype 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-1describes the XML import and export objects provided.

Table 4-1: XML Import and Export Objects

Object Name Description

Export The base XML Export class; it provides the ability to export OScripttypes.

XmlExport Derived from XML Export, this object provides XML export forLivelink object types.

XmlDependentsExport Derived from Xml Export, this object exports objects and their de-pendents.

GenericNodeUtil Provides helper methods for working with generic nodes.

Import The base XML Import class; it provides the ability to importOScript types.

XmlImport Derived from XML Import, this object provides XML Import forLivelink object types.

PreviewImport Derived from XML Import, this object enables previewing an im-port without object creation.

ImportHandler The base XML Import handler

AppHandler Derived from ImportHandler, this object provides the ability tohandle an import by application.


26/59

Chapter 4 XML Import and Export for Developers


Object Name Description

TagHandler Derived from ImportHandler, this object provides the ability tohandle individual tags during an application import.

NodeHandler This object enables handling of node creation during Livelink im-port application.

GenericNode Derived from NamedValue, this object provides the ability to storeparsed XML.

XmlBuiltins The base class for all XML built-ins. Built-ins provide the ability toadd generic XML information to all Livelink objects when they areexported.

XmlCallback The base XML callback. Callbacks provide the ability to tailor XMLExport and Import on a callback-handler basis.

XmlNode The base class for all exportable Livelink objects. The subtype fieldallows users to specify a Livelink object by type. The subtype field

is a string. This allows for pseudo-object types that do not have anode subtype, such as the Project Overview page.

XslTransform The base class for all named XSL transform providers

Livelink's XML Import function was designed to use the least amount of memorypossible 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 theDocumentHandlerinterface. Table 4-2describes the parameters contained in the DocumentHandlerinterface.

Table 4-2: DocumentHandler Interface

Method Parameters Description

StartDocument None Shows that document parsing has started

EndDocument None Shows that document parsing has ended

StartElement String name Assocattributes

Shows that a new tag has been received

EndElement String name Shows that a tag has ended

Characters String chars Inte-ger length

Gets characters for a tag and shows how manythere are


27/59

4.2 XML Import Step by Step



The following steps illustrate how the parsed XML is processed and stored:

1. When it begins parsing a document, the SAX parser calls through theDocumentHandler interface to the StartDocument method.

2. 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.

3. When the parser encounters the start of an element, it passes the name of the tagand its attributes through the StartElement method to the DocumentHandlerinterface. At this point, a generic node is created and passed the element's nameand its attributes. The generic node is put on top of the node stack.

4. If there is data associated with the tag, the parser passes it through theCharacters method to the handler. When received, the data returned is addedto the generic node on top of the node stack.

5. When the parser reaches an end tag, it calls the handler'sEndElement method.When the parser finishes parsing the document, it calls the EndDocumentmethod and the node stack is destroyed.

As this description shows, the XML Import process works by creatinggeneric nodes.Each generic node contains the name of the tag it is associated with, the attributes ofthe tag, and any data associated with the tag. However, because the data beingimported usually represents a hierarchical relationship, a generic node must be ableto contain a list of children, which are also generic nodes. Therefore, to implement ageneric node, a NamedValue object is created that contains a string name and a stringvalue. Then, a GenericNode object is derived from NamedValue, which gives thenode its name and value. The node's attributes are held in a list that storesNamedValue

types. Finally, the node's children are held in a list.XML tags can have other XML tags as their children. This parent-child relationshipmust be preserved as the data is parsed. To accomplish this, the XML Importfunction reparents the nodes on top of the stack to the previous node on the stackwhen 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 containsthree primary tags:

, the parent for all other tags

, which represents either the Enterprise volume or a Personal orProject Workspace

(contained within a tag), which represents a DAPI(document API) node. An tag can contain other tags as itschildren. This relationship preserves the relationship between a parent DAPInode and its children.


28/59



To understand how a generic is transformed into a DAPI node inLivelink, examine what information an holds. Table 4-3shows a list of thetags that an holds is shown and gives a brief description of each tag. Notethe 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 tobe created without waiting for other information.

Table 4-3: Child Elements of an

Child Description

node Represents the DAPI node data used to create a DAPInode

permission Holds the permissions for the node

version Stores Version information for the node

category The Categories that a node belongs to

metadata May not be present, depending on the node type. Whenpresent, they hold additional data used for that nodetypes creation.

llnodes The children of this node. These may or may not be pre-sent, depending on whether the node has children.

4.2.2 Determining When to Create a DAPI Node

With an understanding of how the XML data is imported and how the informationis stored in generic nodes on a node stack, the next thing to consider is how thisinformation is used to create DAPI nodes. Table 4-4outlines how exported data is

rendered in XML.Note: Table 4-4is intended for illustration purposes onlyit is not meant to bevalid XML.


29/59



Table 4-4: Outline of Exported XML Data

DAPI Node With No Children DAPI Node With Two Children

< data>

Open Text recommends that you create the DAPI node as soon as possible, becausedoing so minimizes the number of generic nodes on the stack. Therefore, in caseswhere there are no children, the DocumentHandler method makes one check whenit receives an end element. In cases where there are one or more children,XML Import makes another check when it receives an start element. Thismeans that XML Import checks for the tag name in both theStartElement and EndElement methods. If this condition is met, it tries to use theinformation stored in the generic node at the top of the node stack to create a DAPInode.

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 thecurrent node on the top of the stack to the previous node on the stack when an end element is reached.

As an example, this section walks through the node stack of a hypothetical with no children. Table 4-5illustrates the reparenting process; squarebrackets around a name represent the generic node on the node stack.


30/59



Table 4-5: Reparenting Child Generic Nodes During Parsing

Tag Method Called Node Stack After Method

StartElement [llnode]

StartElement [llnode][node]

EndElement [llnode[node]]

StartElment [llnode[node]][permission]

EndElement [llnode[node][permission]]

StartElement [llnode[node][permission]][version]

EndElement [llnode[node][permission] version]]

EndElement At this point the node can be created

When the XML Import feature receives the start element for the , it createsa generic node and puts it on top of the node stack. StartElement and EndElementare called for the tag. When it receives the EndElement, the generic node isadded as a child to the . This also happens for the and tags. When the EndElement method for is called, there is aparent-child relationship with all the information needed to create the node.

During import, the StartElement and EndElement methods both call theNodeHandler object's ProcessElement, ProcessStart and ProcessEnd methods. Ifone of these returns TRUE, the NodeHandler object's Process method is called tohandle node creation.

4.2.4 Creation of DAPI Nodes During XML Import

The XmlImport object uses a reference to the NodeHandler object to handle nodecreation. Its Process method is passed a GenericNode object that holds all theinformation needed to create a DAPI node.

4.3 Creating a Database Connection

This section illustrates how a database connection can be made using theopentext.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


31/59

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 optionalBoolean 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 nameas a string.

// create db object


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 inthe following example. This example assume the PrgSession is already created.

// declare prg session and create

Object prgCtx

// create db object


// 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


32/59



4.3.3 Creating a Connection Using Parameters

In the following example, the script creates the database connection using the servername, the database vendor, the database name, the database user name and

password, as well as the Livelink user and password.

// create db object


// 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 objectif ( 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 parsedXML tag. Each generic node has attributes, which represent the attributes of an XMLtag, 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, andattributes. 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 variousmethods 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. Acapital letter I at the end of a method name indicates that the method is notcase sensitive.


33/59



4.4.1 Generic Node Creation/Deletion Methods

The methods in Table 4-6create and delete the generic nodes that are used to storeparsed XML.

Table 4-6: Generic Node Creation/Deletion Methods

Return Type Method Name Description

Object New Creates a generic node

Delete Deletes a generic node

4.4.2 Attribute Manipulation Methods

The methods in Table 4-7allow attributes of a node to be added, moved, accessed,and removed.

Table 4-7: Attribute Manipulation Methods

ReturnType

Method Name Parameters Description

Boolean HasAttributes None Checks if there are attributes

AddAttribute String nameString value

Adds an attribute with name andvalue

AddAttributes List attributes Adds a list of attributes

AddAttributesByNames Assoc attributes Adds attributes from an Assoc

Object GetAttribute String name Retrieves an attribute by name

String GetAttributeByName String name Retrieves attribute by name

GetAttributeByNameI String name Retrieves an attribute by name(case insensitive)

List GetAttributes None Retrieves attributes

MoveAttributes Object dstNode Moves attributes to a destination

PutAttributesToAssoc List namesAssoc info

Puts attributes of a given nameinto an Assoc

RemoveAttributes Removes all attributes

4.4.3 Child Manipulation MethodsThe methods in Table 4-8allow children of a node to be added, moved, accessed,and removed.


34/59



Table 4-8: Child Manipulation Methods

ReturnType


Boolean HasChildren None Checks if there are child nodes

AddChild Object child Adds a child to a node

AddChildren List children Adds children to a node

Object GetChild Integer index Retrieves a child by index

GetChildAndRemove String name Retrieves a child by name and re-moves it from child list

GetChildByName String name Retrieves a child by name

GetChildByNameI String name Retrieves a child by name (case in-sensitive)

List GetChildren Retrieves node child listGetChildrenByName String name Retrieves children of type name

MoveChildByName String name Ob-ject dstNode

Moves children by name to a desti-nation

List MoveChildren Object dstNode Moves children to a destination

RemoveChild Object child Removes a child from child list

RemoveChildByName String name Removes first child with name

RemoveChildren Removes all children

4.4.4 DAPI Node Methods

The methods in Table 4-9allow DAPI nodes to interact with system attributes.

Table 4-9: DAPI Node Methods

Return Type Method Name Parameters Description

String GetAttributeNode DAPI node Stringattribute

Retrieves attribute of a givenname and places it in a DAPInode

SetAttributeNode DAPI node Stringattribute

String value

Sets attribute of a given nameand places it in a DAPI node

SetAttributesNode DAPI node Boo-lean preser-veNodeId

Sets a DAPI node from at-tributes, and shows it if thenode ID is left alone


35/59



4.4.5 DAPI Version Methods

The methods in Table 4-10allow DAPI versions to interact with system attributes.

Table 4-10: DAPI Version Methods

Return Type Method Name Parameters Description

String GetAttributeVersion DAPIVERSION versionString attribute

Retrieves attribute ofa given name andplaces it in a DAPIversion

SetAttributeVersion DAPIVERSION version-String attributeStringvalue

Sets attribute of agiven name andplaces it in a DAPIversion

SetAttributesVersion DAPIVERSION version Sets DAPI version

from attributes

4.4.6 Child-Level Methods

The child level of a node is the level of its XML tag from the root element. Themethods in Table 4-11allow the level to be retrieved and set.

Table 4-11: Child-Level Methods

ReturnType


Integer GetChildLevel None Retrieves level of node from root

Boolean IsTopLevelChild None Retrieves if the node is an immediate child ofthe root node

SetChildLevel Integer level 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 isthe name of the XML tag the node represents, and the value of the node is the dataassociated with that XML tag if there are no tags embedded in the primary tag.

Table 4-12: Node Value and Name Methods

ReturnType


String GetName None Retrieves the node name. This is the nameof the XML tag.


36/59



ReturnType


GetValue None Retrieves the node value. This is the value

associated with the XML tag.Set String name

String valueSets the node name and value.

SetName String name Sets the node name

SetValue String value Sets the node value

Date GetDateValue Retrieves the node value as a date

Integer GetIntegerValue Retrieves the node value as an integer

4.4.8 Example Code

In the following code example, the script creates a node with the name Root. Then, itadds an attribute to the node. Finally, it adds a number of children to the node, andthe 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 nameroot.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


37/59



end

root.Display()

root.Delete()


38/59


39/59


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 callbackfunctionality is defined by XmlCallback. To use callbacks, orphan the XmlCallbackobject 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. ForLivelink objects, this will be the subtype of the object. For pseudo-objects, this willbe the name of the object (the name is case dependent). Note that this subtype is notan integer.

The import callback methods are:

AddMetaDataTags

AddRenditions

AddSystemAttributes

AddVersions

CheckMetaData

CheckObjectInfo

ImportType

PostCreate

The export callback methods are:

ExportAddVersions

ExportCheckObjectInfo


40/59

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 thecontent exported, filter out certain object types, and add additional XML content.Table 5-1describes the relevant methods.

Table 5-1: Export Callback Methods

Method Description Parameters Returns

ExportAddVersions Called prior to export-ing the Versions of an

object. Allows users tocontrol what Versionsare exported.

node (DAPI nodeholding Version)

versions (list ofDAPI versions toadd. Each elementin the list is a DAPIversion)

options (anyoptions used tocontrol the export)

Assoc OK(TRUE =

success)

Versions (listof Versions toadd)

ExportCheckObjectInfo Called prior to export ofa DAPI node. Allows

users to control attrib-utes of a node. Be ex-tremely careful whenchanging this informa-tion. Do not add or re-move attributes. Theseattributes are used byXML Import to create anode.

node (DAPI nodebeing exported) op-

tions (any optionsused to control theexport)

Assoc OK(TRUE =

success)

ErrMsg (storeserror message)

ExportType Called prior to export ofa type. Allows users tofilter out objects basedon type.

handler (XML Ex-port handler) op-tions (any optionsused to control the

export)

Assoc OK(TRUE =success)

Export (TRUE= export thetype)

ErrMsg (storeserror message)


41/59




OrderChildList Called during export toreorder the list of chil-

dren, if needed.

node (the DAPInode of the node

that was created)expChildren (list ofchildren to export)

options (any op-tions used to con-trol the export)

List (orderedchild list)

Write Called after the objecthas been written andbefore the next object isadded to the stream. Al-lows users to appendadditional output an toobject.

Handler (XMLExport handler)XMLWriter (whereto output theexport)

obj (object being

exported)


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 addadditional processing after a node is created. Table 5-2describes these methods.

Table 5-2: Import Callback Methods


AddMetaDataTags Called prior toCheckMetaData call-back. Allows users tocontrol the add meta-data sent toCheckMetaData . Note:Node tag or versiontags may not beadded to this list.Metadata tags are the

immediate child tagsthat appear afterllnode and beforenode.

Handler (XML Exporthandler);to get prg session, useGetPrgSession; to getnode by ID, useGetNodeById options(any options used tocontrol the export)

Assoc OK (TRUE =(import completedsuccessfully)

Tags (list of tags toadd)


42/59




AddRenditions Called prior to addingRenditions to a Ver-

sion. Allows users tocontrol what Rendi-tions are imported.

handler (XML Exporthandler);

to get prg session, useGetPrgSession; to getnode by ID, useGetNodeById node(DAPI node holdingVersion)

version (Version toadd Renditions to)

renditions (list ofRenditions [DAPIversions] to add. Eachelement in the list is

an Assoc with fieldnames of a DAPIversion. However, the"p" is removed fromthe DAPI version fieldname.

options (any optionsused to control theexport)

Assoc OK (TRUE =(import completed

successfully)Renditions (list ofrenditions to add)

AddSystemAttribute

s

Called after an objectis created. Allows thecallback to add sys-tem attributes or mod-ify those availablefrom the import.

handler (XML exporthandler);to get prg session, useGetPrgSession; to getnode by ID, useGetNodeById node(DAPI node to applysystem attributes to)systemAttributes(system attributes toapply)



43/59




AddVersions Called prior to addingVersions to an object.

Allows users to con-trol what Versions areimported.

node (DAPI nodeholding Version)

versions (list of DAPIversions to add). Eachelement in the list isan Assoc with fieldnames of a DAPIversion. However, the

p is removed from theDAPI version fieldname.


Assoc OK (TRUE =success)

Versions (list of Ver-sions to add)

CheckMetaData Called to check or set

metadata for an ob-ject. Allows users tocontrol metadata of anode before it is cre-ated.

handler (XML Export

handler);to get prg session, useGetPrgSession; to getnode by ID, useGetNodeByIddapiInfo(fields in Assoc arethe fields of a DAPInode with "p"removed from fieldname)

metaData (Assoc withname value metadatapairs for node type)

childLevel (showslevel of node inexport; 0 is the toplevel, 1 is the nextlevel, and so on)


Assoc OK (TRUE =

success)

ErrMsg (stores errormessage)


44/59




CheckObjectInfo Called prior to crea-tion of the DAPI node

representing the ob-ject. Allows users tocontrol attributes of anode.

handler (XML Exporthandler);

to get prg session, useGetPrgSession; to getnode by ID, useGetNodeById dapiInfo(fields in Assoc arethe fields of a DAPInode with "p"removed from fieldname)

childLevel (showslevel of node inexport; 0 is the toplevel, 1 is the nextlevel, and so on)




ImportType Called prior to importof a type. Allows us-ers to control if a typeis imported.

handler (XML Exporthandler);to get prg session, useGetPrgSession; to getnode by ID, useGetNodeById dapiInfo(fields in Assoc arethe fields of a DAPI

node withp removedfrom field name)



Import (TRUE =import the type)


PostCreate Called after the nodeis created to allowpost creation process-ing.

handler (XML Exporthandler) genericNode(generic node holdingparsed XML)

node (DAPI node thatwas created)


None


45/59

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 XMLnode handler. The following sections outline how XML nodes can be used to handleXML 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 somecases you will need to get an XML node from the XmlNodeSubsytem directly. Theexample 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-3shows the fields of an XML node.

Table 5-3: Fields of an XML Node

Field Description

fElementName XML tag name used to export the node type

fEnabledShows if the type is registered with the XML node subsystem

fPlainMimeType Stores a list of MIME types that are base64 encoded

fUseVersionStream Shows if a DAPI version stream is used to export the Version con-tents

fSubtype Type used to register the node

To add a new XML node to your Ospace, orphan the XmlNode object to your Ospaceand set the fSubtype field. For Livelink objects, this will be the subtype of the objectand for pseudo-objects the name of the object (the name is case dependent). Then setfEnabled 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 thecontent for a versionable object is exported. In almost all cases, NodeFetchVersion,from your types LLNode, should be used to get Version content. However, if yournode requires a DAPI version stream, set fUseVersionStream to TRUE.


46/59



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 aretwo export methods:WriteMetaData andWriteVersionMetaData. Metadata is thedata unique to an object type. For a Version, metadata is used to give additionaldetails about the Version content. In most cases object metadata is the most

important. Table 5-4, gives a description of theWriteMetaData method:

Table 5-4: XML Node Export Methods


WriteMetaData Write any additionalchild tags (data) thatare needed to createthe object when it isimported. Metadatacan best bedescribed as the dataused by your object

during nodecreation. Forexample, an Alias(Shortcut) in anobject that points toanother object andits metadata is theIDS of the node itpoints to.

If you create a nodetype that has anLLNode::Node-

CreatePre which

validates creationinformation then thecreation informationshould be your nodetype's metadata. TheXmlWriter is used towrite your metadatato the XML stream.

handler (XMLExport handler)xmlWriter (usedto output XML)

node (DAPI noderepresenting theobject)


Assoc OK (TRUE =metadata was writtensuccessfully)

ErrMsg (text describ-ing errors on failures)


47/59




WriteVersionMetaData Called during exportto allow the node to

return a list of nodesit is dependent on.This method is usedby XmlDependents-Export to return alist of nodes by IDthat your node isdependent on. UsingAlias (Shortcut) asan example, thedependents listwould contain oneelement the ID oforiginal node.

As a rule of thumb,you should returnthe IDs of any nodesneeded by yournode if it were cre-ated on another sys-tem.

node (DAPI nodeof the node that

was created) op-tions (any op-tions used to con-trol the export)

Assoc OK (TRUE =metadata was written

successfully)ErrMsg (stores errormessage)

Dependents (list ofdependent nodes byID)

Import Methods

Import methods are used during XML Import to create objects from the XMLproduced by an XML Export. As a developer, you will use these methods in somecombination to create your node type. These methods can be separated into threetypes.

Methods used to convert metadata into node creation information used byLLNode::NodeCreate:

CheckNode

CheckNodeId

GetCreateInfo

Methods used to finalize object creation:

CheckDependents

PostCreate

Method used to add a new Version by LLNode::NodeAddVersion:

GetVersionInfo


48/59



XmlNode Metadata Methods

Metadata is the data that is required by your node type during creation (other datacan be included at your discretion). Metadata is exported using theWriteMetaData

method of XmlNode. The handling of export is straightforward, and there are severalexamples you can use from the XmlNodeSubsystem.

During import, the metadata held in a GenericNode node needs to be converted toan Assoc. To do this, XmlImport uses the XmlNode method GetMetaData. Thismethod takes a GenericNode, which stores the parsed XML in the parent-childrelationship it was written in, and converts the metadata into an Assoc. There aretwo types of metadata: node metadata and Version metadata. Version metadata israrely used, but it provides any additional information you might need whencreating Versions. is your node creation data. To get nodemetadata, XmlImport calls the method GetMetaDataTags, which returns a list withthe names of your node metadata tags. To get Version metadata, XmlImport callsthe XmlNode method GetVersionMetaDataTags, which returns a list with the names

of your Version metadata tags. XmlImport then get the data from the GenericNodeusing the tag names. Table 5-5describes the XmlNode metadata methods

Table 5-5: XmlNode Metadata Methods

Method Description Parameters Return

GetMetaDataTags Get a list of the metadata tagsfor this Version

none List

GetVersionMetaDataTags Get a list of the parent meta-data tags for this object.

none List (list ofparent tagnames forthe object's

Versionmetadata)

Export Ordering of Child Nodes

In some cases, your node type will have children. When XmlExport runs, it willwrite the children in the order returned by DapiNode.ListContents. If any of thechildren need to placed before any other children, you will need to order yourexport list. To do this, the XmlNode method OrderChildList is provided. It takesthe list of children to be exported, and if you override the method you will be able toorder the children to suit your needs. For example, XmlNode provides the baseOrderChildList method, which orders by Categories, other children, andShortcuts. 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 aShortcut to be created before the Shortcut.

Table 5-5 on page 48describes the method OrderChildList


49/59



Table 5-6: OrderChildList Method

Metjhod Description Parameters Return

OrderChildList Called during exportto reorder the list ofchildren, if needed,so that import proc-essing is simpler.

node (DAPI node of the nodethat was created) expChildren(List of children [DAPInode] toexport)

options (any options used tocontrol the export)

List (orderedchild 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 exportmethods provided (their names all end in "Subclass"). Table 5-7describes themethods provided for import.

Table 5-7: Import Subclass Methods

Method Description

GetCreateInfoSubclass Provides for handling of create information for subclassing.

PostCreateSubclass Provides for post-creation handling for subclassing.

Table 5-8describes the methods provided for export.

Table 5-8: Export Subclass Methods

Method Description

OrderChildListSubclass Provides the ability to order children for subclassed nodes.

WriteMetaDataSubclass Provides the ability to write additional metadata tags for sub-classing.

Table 5-9describes the method provided for metadata handling.

Table 5-9: GetMetaDataTagsSubclass Method

Name Description

GetMetaDataTagsSubclass Provides the ability to add parent metadata tags for a sub-classed node.

If you subclass a node type, your overridden Subclass methods will be calledduring export and import. If your node is subclassed, you must call these methodsat the end of your non-subclassed method.


50/59


51/59



Examples of how GetCreateInfo is used are found in the object types derived fromXmlNode. 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 anode 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 beused 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 checkdependencies or make needed fix-ups. For example, when a Project is exported itincludes the list of participants. When PostCreate is called for a Project, theparticipants in the export file are added to the Project.

Handling Versioned Nodes

If your custom object uses NodeAddVersionSubclassPre orNodeAddVersionSubclassPost, or if it overrides the NodeAddVersionSubclass ofLLNode, you will need to override GetVersionInfo. It is called prior toLLNode::NodeAddVersion and is used to set your specialized add Version

information into the add Version Assoc passed toLLiApi.LLNode.NodeAddVersion.

Table 5-11describes the GetVersionInfo method:


52/59



Table 5-11: GetVersion Info Method


GetVersionInfo XML node descendantsoverride this method to getany specaliazed creationinformation they need dur-ing node import

handler (XMLImport handler)node (node that willhold new Version)

genericNode (holdsparsed XML fornode)

addVerInfo (Assocpassed intoLLiApi::NodeAd

Version method

genNode (holdsparsed XML forVersion)


Boolean (TRUE =OK to proceed withcreate)

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 thefile stored is added as an attribute of the generic node. In most cases, extracting thefile name and handling of adding the Version are performed by the method

GetTmpFileContent. The XML node Document is a good example of how to handleadding new Versions.

Metadata Methods

Metadata methods are used to get, set, and change metadata, as well as write themetadata to an XML stream.

Metadata is used to describe an object in more detail. Some object types store theirmetadata 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 objectdata. Metadata tags make the export easier to understand, and allow XML skindevelopers direct access to information needed to display your object.

Shown below is an export of an Alias (Shortcut). The node referenced by the alias isstored in the originalid metadata tag.

4240


53/59



Export calls the methodWriteMetaData to allow objects to write their metadatausing an XML writer. Metadata should map directly to node-creation information;however, other information can be included. For example, the XML callback methodAddMetaDataTags can be used by callback developers to add metadata.

When XML Import runs, it stores the parsed XML in generic nodes. Generic nodeshold the parsed XML in the same parent-child relationship as represented in theXML Export file. Developers can walk the parent-child tree to extract the parsedXML.

The parsed XML is converted to and from the callback format using GetMetaDataand SetMetaData. GetMetaData converts the metadata to the callback format, andSetMetaData converts the metadata from the callback format. Both of these utilitymethods need to know which tags are metadata and which are not. They use theGetMetaDataTags to get a list of the parent metadata tags and walk each parent tagto 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 inthe same parent-child tag. To retrieve the name of an XML tag, use GetName, and toget the value of an XML tag, use GetValue. Since XML tags can hold values or otherchild XML tags, generic nodes provide methods for getting child tags by list andname. Methods that are case insensitive have an Iat the end of the method name.

XML tags also have attributes, and methods are provided to get attributes by listand name. Attribute methods that are case insensitive have an Iat the end of themethod name.

Remember that all XML tag and attribute values are strings. Therefore, they must beconverted to native types, and verification code must be added to check if a value orattribute can be converted to a specific native type. As an example, look at the howan Alias is handled. Aliases store the ID of their original node as a string, whichmust 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 tagoriginalnode, and then the method GetValue is used to get the original node ID as


54/59



a string. The string is then converted to an integer and stored in the parametercreateInfo. Note that the XML tag name is placed in an object that stores the XMLtag name as a constant. This allows the tag name to be stored in one place andmakes the code easier to read and modify later.

Using XmlWriter

XmlWriters come in several flavors. Each flavor supports a different outputstream 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 betweenStartElement and EndElement calls. Each child tag can be written using the

WriteElement method if the child tags do not have children. Begin a new elementwith optional attributes. The element is added to the element stack and anyattributes are written out.

Table 5-12describes the GetCreateInfo method and its parameters.

Table 5-12: GetCreateInfo Methods

Parameter Description Parameters

StartElement XML node descendants override thismethod to convert metadata to node-creation information.

tagname (name of XMLtag) atts (attributes of XMLtag)

EndElement Closes the currently open element. None

WriteElement Writes out the contents of an XML tagelement (all data, except CDATA sec-tions are escaped).

tagname (name of XMLtag) value (valueassociated with tag)

atts (attributes for tag)

XmlWriters have an internal stack that keeps track of StartElement andEndElement calls, so when EndElement is called the top of the stack is popped to getthe 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 previousversion, 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


55/59

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, theoutput will look like the following:

Old Appearance

New Appearance

The old XML output has all capitalization removed, while the new XML outputpreserves 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 theAssoc.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 writeoutput to the GetVersionInfo method. Table 5-13 describes the GetVersionInfomethod.

Table 5-13: GetVersion Info Method


GetWriter Get an XML writer. output (where out-put of writer is di-rected)


ErrMsg (textdescribing errors onfailures)

Writer (XMLwriter)

The output parameter can be undefined. In this case, GetWriter returns anXmlStringWriter, and the method GetBuffer can be used to get the XML writtento the writer.

5.3 XML Built-Ins

Built-ins allow users to extend the behavior of XML Export by adding named built-ins to Livelink. For example, one of the XML built-ins allows a breadcrumb trail to beexported for any node. (A breadcrumb trail is the path to the node in the Livelinksystem.)

To use a built-in for export, add the name of the built-in to the export URL. If youneed to add an XML built-in to the system, orphan the XmlBuiltin to your Ospace.


56/59



Set the fName field to the name of the built-in. The name must start with Xml. Thisallows URL parameters to be placed into the options Assoc, which is used tocontrol 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 ofthe permissions parameter, which controls the export of permissions on a node. Ifthe 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 optionsfor your application.

5.4.3 Custom XML Node Migration

This section describes changes to methods and parameters that may affect themigration of your custom XML nodes to the new implementation of XML Exportand Import in Livelink.

GetCreateInfo

The method has its first parameter changed from impor

livelink ecm - enterprise server xml import and export guide

Documents