Beruflich Dokumente
Kultur Dokumente
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
Table of Contents
Preface 1
1.1 1.2
2
2.1 2.2
3
3.1 3.2
4
4.1 4.2 4.3 4.4
5
5.1 5.2 5.3 5.4
IX
Index......................................................................................... 59
LLESCOR090701-PGD-EN-1
Preface
This preface explains the typographical conventions used in this guide and provides Open Text contact information.
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.
LLESCOR090701-PGD-EN-1
Preface
Item Variable placeholders, references to other documents, new or special terminology, and emphasis
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
"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.
LLESCOR090701-PGD-EN-1
Preface
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.
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
LLESCOR090701-PGD-EN-1
Preface
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.
LLESCOR090701-PGD-EN-1
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.
LLESCOR090701-PGD-EN-1
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.
10
LLESCOR090701-PGD-EN-1
1.2
LLESCOR090701-PGD-EN-1
11
Chapter 2
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.
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:
LLESCOR090701-PGD-EN-1
13
Values
sub = export the objId and all child nodes one = export the objId node and its
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
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
LLESCOR090701-PGD-EN-1
2.1
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
LLESCOR090701-PGD-EN-1
15
Parameter
followaliases
Description Determines whether Aliases (now called Shortcuts) are replaced with the node they alias
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.
16
LLESCOR090701-PGD-EN-1
2.2
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 ) )
LLESCOR090701-PGD-EN-1
17
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
LLESCOR090701-PGD-EN-1
Chapter 3
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.
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:
LLESCOR090701-PGD-EN-1
19
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.
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
LLESCOR090701-PGD-EN-1
3.1
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
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.
LLESCOR090701-PGD-EN-1
21
3.2.1 Examples
The following examples demonstrate how to perform an XML import using OScript.
22
LLESCOR090701-PGD-EN-1
3.2
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
LLESCOR090701-PGD-EN-1
23
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
LLESCOR090701-PGD-EN-1
Chapter 4
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
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.
LLESCOR090701-PGD-EN-1
25
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
LLESCOR090701-PGD-EN-1
4.2
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.
<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
LLESCOR090701-PGD-EN-1
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
28
LLESCOR090701-PGD-EN-1
4.2
data>
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.
LLESCOR090701-PGD-EN-1
29
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.
30
LLESCOR090701-PGD-EN-1
4.3
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" )
LLESCOR090701-PGD-EN-1
31
32
LLESCOR090701-PGD-EN-1
4.4
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
List
LLESCOR090701-PGD-EN-1
33
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
List
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
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
Sets a DAPI node from attributes, and shows it if the node ID is left alone
34
LLESCOR090701-PGD-EN-1
4.4
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
SetAttributesVersion
Description Retrieves level of node from root Retrieves if the node is an immediate child of the root node Sets node child level
Parameters None
Description Retrieves the node name. This is the name of the XML tag.
LLESCOR090701-PGD-EN-1
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
36
LLESCOR090701-PGD-EN-1
4.4
LLESCOR090701-PGD-EN-1
37
Chapter 5
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
ExportAddVersions ExportCheckObjectInfo
LLESCOR090701-PGD-EN-1
39
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)
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)
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
LLESCOR090701-PGD-EN-1
5.1
Method
OrderChildList
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)
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
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.
LLESCOR090701-PGD-EN-1
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
LLESCOR090701-PGD-EN-1
5.1
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)
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)
LLESCOR090701-PGD-EN-1
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)
ImportType
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
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
LLESCOR090701-PGD-EN-1
5.2
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.
LLESCOR090701-PGD-EN-1
45
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
LLESCOR090701-PGD-EN-1
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:
CheckDependents PostCreate
GetVersionInfo
LLESCOR090701-PGD-EN-1
47
Description Get a list of the metadata tags for this Version Get a list of the parent metadata tags for this object.
Return List List (list of parent tag names for the object's Version metadata)
48
LLESCOR090701-PGD-EN-1
5.2
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)
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.
LLESCOR090701-PGD-EN-1
49
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
LLESCOR090701-PGD-EN-1
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).
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.
LLESCOR090701-PGD-EN-1
51
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
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
LLESCOR090701-PGD-EN-1
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.
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
LLESCOR090701-PGD-EN-1
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:
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
LLESCOR090701-PGD-EN-1
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
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.
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.
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
LLESCOR090701-PGD-EN-1
5.4
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.
LLESCOR090701-PGD-EN-1
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
LLESCOR090701-PGD-EN-1
59