Adobe® Workflow Server
Version 6.2
Data Handling for Workflow Server
© 2003 Adobe Systems Incorporated. All rights reserved.
Adobe® Workflow Server 6.2 Data Handling for Workflow Server for Microsoft® Windows®
August 2003
As of April 12, 2002, Accelio Corporation (formerly JetForm Corporation) was purchased by Adobe Systems
Incorporated. As of that date, any reference to JetForm or Accelio shall be deemed to refer to Adobe Systems
Incorporated.
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software
described in it, is furnished under license and may be used or copied only in accordance with the terms of such license.
Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written
permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law
even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to change without notice, and should not be
construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or
liability for any errors or inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under
copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of
the copyright owner. Please be sure to obtain any permission required from the copyright owner.
Any references to company names in sample templates are for demonstration purposes only and are not intended to
refer to any actual organization.
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United
States and/or other countries.
Microsoft and Windows is either a registered trademark or a trademark of Microsoft Corporation in the United States
and/or other countries. All other trademarks are the property of their respective owners. All other trademarks are the
property of their respective owners.
This software is based in part on the work of the Independent JPEG group. Portions © 1995-1996 Access Softek Inc. All
rights reserved.
This software is based in part on the work of the FreeType team.
Software included in this program may contain an implementation of the LZW algorithm licensed under U.S. Patent
4,558,302.
Portions copyright 1992-1995 Summit Software Company.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is
defined at
Documentation,” as such terms are used in
C.F.R. §12.212 or
Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as
Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and
conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems
Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to
comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as
amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section
503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and
60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by
reference.
Contents
Introduction .............................................................................................................................. 6
About This Book....................................................................................................................................... 6
Other Workflow Server Documentation.................................................................................................. 6
1 Overview .................................................................................................................................... 7
Understanding Workflow Server Data ..................................................................................................... 7
Accessing the Data Model ......................................................................................................................... 8
Understanding the Model Structure......................................................................................................... 8
The Data Model and Form Server Forms .......................................................................................... 9
The Data Model and Form Client Forms........................................................................................... 9
2 Manipulating Work Item Data ..............................................................................................10
Retrieving the Data Model ...................................................................................................................... 10
Retrieving Field Data ............................................................................................................................... 11
Editing and Adding Data......................................................................................................................... 11
Changing Data Values ....................................................................................................................... 12
Removing Data ................................................................................................................................. 12
Adding Nodes ................................................................................................................................... 13
3 Working With XML Files .........................................................................................................14
Loading XML Files.................................................................................................................................. 14
Specifying XML to Ignore ................................................................................................................. 15
Exporting Data as XML........................................................................................................................... 16
Mapping XML to XFA............................................................................................................................ 16
Mapping Rules for XML Elements ................................................................................................... 17
Mapping XML Leaf-Elements .................................................................................................... 17
Mapping XML Elements with Element Content....................................................................... 17
Mapping XML Elements with Mixed Content .......................................................................... 18
Mapping XML Attributes to XFA............................................................................................... 19
Expressing Null Values...................................................................................................................... 19
4 Working with Nested Data ....................................................................................................20
XFA SOM Expressions............................................................................................................................ 20
Using Occurrence to Identify Nodes ................................................................................................ 21
Absolute Occurrence Numbers .................................................................................................. 21
Relative Occurrence Numbers.................................................................................................... 22
Referencing Descendent Nodes ........................................................................................................ 22
Using Shortcut Notation in SOM Expressions ................................................................................ 23
Understanding Node Resolution ............................................................................................................ 23
SOM Expressions That Resolve to Child Nodes .............................................................................. 24
SOM Expressions That Do Not Resolve to Child Nodes ................................................................ 24
Resolving Compound Names..................................................................................................... 26
Contents 4
5 XFA Data COM Object Reference..........................................................................................28
IXFADataGroup...................................................................................................................................... 29
IXFADataModel...................................................................................................................................... 29
Properties .......................................................................................................................................... 29
saveFormat.................................................................................................................................. 29
Methods ............................................................................................................................................ 30
saveAs.......................................................................................................................................... 30
IXFADataValue....................................................................................................................................... 30
Properties .......................................................................................................................................... 31
contains....................................................................................................................................... 31
contentType ............................................................................................................................... 31
match .......................................................................................................................................... 31
value ............................................................................................................................................ 31
IXFAModel.............................................................................................................................................. 31
Methods ............................................................................................................................................ 32
createNode.................................................................................................................................. 32
IXFAModelFactory ................................................................................................................................. 32
Properties .......................................................................................................................................... 32
rootName.................................................................................................................................... 32
IXFANode ............................................................................................................................................... 33
Properties .......................................................................................................................................... 33
all ................................................................................................................................................. 33
index............................................................................................................................................ 34
model .......................................................................................................................................... 34
name............................................................................................................................................ 34
nodes ........................................................................................................................................... 34
parent .......................................................................................................................................... 34
Methods ............................................................................................................................................ 34
applyXSL..................................................................................................................................... 34
clone ............................................................................................................................................ 35
loadXML ..................................................................................................................................... 35
resolveNode ................................................................................................................................ 35
resolveNodes............................................................................................................................... 36
saveXML ..................................................................................................................................... 36
IXFANodeList ......................................................................................................................................... 36
Properties .......................................................................................................................................... 37
item ............................................................................................................................................. 37
length .......................................................................................................................................... 37
namedItem.................................................................................................................................. 37
Methods ............................................................................................................................................ 37
append......................................................................................................................................... 37
insert............................................................................................................................................ 38
remove ........................................................................................................................................ 38
IXFAObject ............................................................................................................................................. 38
Properties .......................................................................................................................................... 38
className ................................................................................................................................... 38
Contents 5
5 XFA Data COM Object Reference (Continued)
IXFAStringList ........................................................................................................................................ 39
Properties .......................................................................................................................................... 39
item ............................................................................................................................................. 39
length .......................................................................................................................................... 39
XFADataModelFactory........................................................................................................................... 39
Properties .......................................................................................................................................... 40
attributesAreValues ..................................................................................................................... 40
rootName.................................................................................................................................... 40
XFAAppModel........................................................................................................................................ 40
Properties .......................................................................................................................................... 42
all ................................................................................................................................................. 42
className ................................................................................................................................... 42
context......................................................................................................................................... 42
index............................................................................................................................................ 42
model .......................................................................................................................................... 42
name............................................................................................................................................ 42
nodes ........................................................................................................................................... 42
parent .......................................................................................................................................... 43
Methods ............................................................................................................................................ 43
addFactory .................................................................................................................................. 43
applyXSL..................................................................................................................................... 43
clone ............................................................................................................................................ 43
createNode.................................................................................................................................. 44
loadFile........................................................................................................................................ 44
loadXML ..................................................................................................................................... 45
newDOM .................................................................................................................................... 45
resolveNode ................................................................................................................................ 45
resolveNodes............................................................................................................................... 45
saveXML ..................................................................................................................................... 45
Index........................................................................................................................................46
Introduction
Adobe® Workflow Server is an integrated business process automation development and deployment
system that enables you to create an application and provides the run-time environment to execute the
application. Each Workflow Server application consists of a set of elements that together implement the
application. These elements include:
• Forms to capture data.
• Process definitions that describe the automated process.
• Role definitions that describe a group of participants in abstract terms.
• Other custom built components such as Active Server Pages (ASP) or Web pages, as required.
ABOUT THIS BOOK
The Data Handling for Workflow Server guide provides information about manipulating the data of a
process or a work item. This book includes an overview of the Adobe XFA technology that is used to
model the data, and detailed information about using script to access the data.
This guide is for people who are developing Workflow Server applications, and want direct access to the
data of a process or work item. Use the information in this guide to manipulate work item data and to
process data using script from within a process definition or within a Web application.
OTHER WORKFLOW SERVER DOCUMENTATION
Other guides tailored to specific audiences are also available. Other guides that you might refer to while
using the Data Handling for Workflow Server guide are:
• Using Workflow Server Designer.
• Scripting for Workflow Agent with JScript.
• COM Object Library Reference.
To locate the complete suite of Workflow Server documentation, in Microsoft® Windows® click Start >
Programs > Adobe Workflow Server 6.2 > Online Documentation.
1 Overview
To develop automated business processes, you may need to access the data that processes collect and store.
For example, you may need to work with the data to:
• Select specific data from a work item to use in a calculation.
• Import data from an outside source, such as an XML file that a database created.
• Merge data with a form.
For introductory information about Workflow Server data and how to access the data model for
processes, see:
• “Understanding Workflow Server Data” on page 7.
• “Accessing the Data Model” on page 8.
• “Understanding the Model Structure” on page 8.
UNDERSTANDING WORKFLOW SERVER DATA
Workflow Server is a consumer of data. Most data that Workflow Server consumes originates from forms
that participants fill when they complete work items. Some data can originate from organizational
databases, or from XML documents that other software produces.
When handling data for Workflow Server, you typically perform the following tasks:
• Retrieve, change, or delete existing work item and process data. For information, see “Manipulating
Work Item Data” on page 10.
• Import XML data from other sources. For information, see “Loading XML Files” on page 14.
• Save work item data for sharing with other software. For more information, see “Exporting Data as
XML” on page 16.
Workflow Server uses data that conforms to the XML Forms Architecture (XFA) standard. XFA is an
XML-based technology for modelling electronic forms and form data. XFA consists of several
components that allow you to model forms for capturing and presenting information, and for processing
form data.
The XFA data DOM is the component of XFA that provides the model for representing form data. The
XFA data DOM uses a tree structure of objects to represent data. A library of COM interfaces exposes
these objects.
You can access the COM interfaces through the JScript extensions for Workflow Server, and the Workflow
Server Object Library. To see detailed information about the COM objects of the XFA data DOM, see
“XFA Data COM Object Reference” on page 28.
Overview Accessing the Data Model 8
ACCESSING THE DATA MODEL
Workflow Server provides several access points to the XFA data models of work items and process
instances. To access the data model from process definitions, you use the Microsoft JScript extensions for
Workflow Server:
• WorkItem::data returns the data model for the current work item.
• WorkItem::childData returns the data model for the child process of a subprocess task. This method is
available only to script associated with subprocess tasks.
• Process::data returns the data model for the current process instance.
To access the data model from Web applications, such as Web Access, you use the Object Library:
• XMLData::GetXFAModel and XMLData::SetXFAModel get and set the XFA data model.
For information about the JScript extensions for Workflow Server, see the Scripting with JScript for
Workflow Agent guide. For information about the Object Library, see the COM Object Library Reference
guide.
UNDERSTANDING THE MODEL STRUCTURE
To properly retrieve and manipulate work item data, you must understand how the data is organized in
the XFA data DOM.
The XFA data DOM uses a tree structure to represent data. The data model includes a root datasets node,
with a child data node. The descendent nodes of the data node represent form data.
If you want information about how an XML document maps to the XFA data DOM, see “Mapping XML
to XFA” on page 16.
For a work item, the node below the data node represents the form that is associated with the work item.
The name of the form node is the name of the form. The form node has no value. The nodes below the
form node represent the objects on the form:
• Each node corresponds with an object on the form.
• The names of the nodes are the object names.
• If the form objects have a value property, the value of the nodes are the values of the objects.
The data structure below the form node corresponds with the architecture of the form.
• Form Server 5.1, HTML, and PDF forms use a flat data structure. For information, see “The Data
Model and Form Server Forms” on page 9.
• Form Client forms can use a nested data structure. For information, see “The Data Model and Form
Client Forms” on page 9.
Overview Understanding the Model Structure 9
The Data Model and Form Server Forms
Form Server 5.1, HTML, and native PDF forms use a flat data structure. Typically, the data model of the
work items that use these types of forms have the following structure:
If work item data originates from a Form Client form that uses grouped fields, or from an XML
document, your data may not be flat. For an example of a data model that is not flat, see “The Data Model
and Form Client Forms” on page 9.
The Data Model and Form Client Forms
Form Client forms can use a nested data structure. If your data originates from forms that use grouped
fields, the associated data model includes nodes that correspond with the field groups. The data structure
can also be nested if it originates from XML documents.
For example, the form Shipping has the groups named Address and Items. The group Address contains
the fields Street and Country. The group Items contains the fields ProductName and SKU. The form has
the following data model in the XFA data DOM.
For information about how to use data that is not flat, see “Working with Nested Data” on page 20.
To persist data from work item to work item in a process, the data must be compatible with all the forms
that each work item can use. If some of your users use Form Client forms and some users use Form Server
forms, do not use grouped fields in your Form Client forms. Form Client supports grouped fields. Other
form types do not support grouped fields.
datasets
data
FieldName1
FieldName2
...
FieldNameN
FormName
datasets
data
Country
Shipping
Address
Items
Street
ProductName
SKU
2 Manipulating Work Item Data
Manipulate existing work item data if you need to change or retrieve values on a form. At times, you may
also need to change the structure of the data to fit a specific form.
To manipulate the data, you follow these steps:
• Retrieve the data model. See “Retrieving the Data Model” on page 10.
• Navigate to specific items in the data model. See “Retrieving Field Data” on page 11.
• Change the data. See “Editing and Adding Data” on page 11.
Before beginning, determine which access method is best for the data you will be manipulating. Use the
XFA data DOM when:
• Your data includes multiple fields of the same name.
• Your data exists in several levels.
Use JScript if your data includes field names that are unique within a form. For more information, see the
Scripting for Workflow Agent with JScript guide.
RETRIEVING THE DATA MODEL
Before you can manipulate work item or process data, you must retrieve the data model. When you
retrieve the data model, you create an XFA COM object that provides access to the data.
If you want information about the structure of the data model, see “Understanding the Model Structure”
on page 8.
The method you use to retrieve the data model depends on the location of your script:
• In a process definition, use the WorkItem::data method of the JScript extensions to return an
IXFADataModel object.
var oXFADataModel = WorkItem.data;
//now use oXFADataModel to manipulate the work item data.
• In a Web application, use the FormContent object, and the XMLData::GetXFAModel method of the
Object Library to return an IXFADataModel object. This method supports all form data regardless of
the form type.
var oXMLData = oFormContent.Content;
var oXFADataModel = oXMLData.GetXFAModel;
//now use oXFADataModel to manipulate the work item data.
Manipulating Work Item Data Retrieving Field Data 11
RETRIEVING FIELD DATA
Retrieve field data when you require the value of a specific field. To retrieve field data, you can use the
IXFADataModel::resolveNode method to retrieve the node that represents the form field.
Note You can call resolveNode on any object that is an IXFANode. IXFAModel and IXFADataModel,
IXFADataGroup, and IXFADataValue objects are IXFANode Objects. For more information, see
the inheritance diagram in “XFA Data COM Object Reference” on page 28.
For example, a purchase order form includes a field named CustomerID. The form is a Form Server 5.1
form, so the data for the work item is flat. The form name is Order. The data model of the form looks like:
To retrieve the value of the CustomerID field you use the following expression:
var strCustID = oIXFADataModel.resolveNode(‘Order.CustomerID’).value;
In this expression, Order.CustomerID is an XFA Scripting Object Model (SOM) expression. If your
data is flat, and the field names are unique within the form, the SOM expression is in the format
FormName.FieldName. If your data is not flat or has many fields of the same name, you must use more
complex SOM expressions. For more information, see “XFA SOM Expressions” on page 20.
Field names are case-sensitive. Ensure that you use the proper case when you specify the field name.
For more information about IXFADataModel and the associated properties and methods, see “XFA Data
COM Object Reference” on page 23.
➤ To retrieve field data
1. Retrieve the data model of the work item.
For information, see “Retrieving the Data Model” on page 10.
2. Use the IXFADataModel::resolveNode method to retrieve the node that represents the form field.
EDITING AND ADDING DATA
Use the XFA COM objects to change the values of form fields in work items. You can also remove and add
data.
• For information about changing node values, see “Changing Data Values” on page 12.
• For information about removing nodes, see “Removing Data” on page 12.
• For information about adding nodes, see “Adding Nodes” on page 13.
datasets
data
CustomerName (SomeBusiness)
CustomerID (USNW152)
...
Order
Manipulating Work Item Data Editing and Adding Data 12
Changing Data Values
Change the value of nodes when the current value is no longer valid. The value that you specify appears in
the corresponding form field in the work item.
For example, your organizational database contains information about process users. When users open a
form in a work item, you want to populate certain form fields with information from the database. To
populate the form fields, you change the value of the associated node in the data model.
You can change the value of data-value nodes only. For information about data-value nodes, see
“Mapping XML to XFA” on page 16.
➤ To change data values
1. Retrieve the data model of the work item.
For more information, see “Retrieving the Data Model” on page 10.
2. Use IXFANode::resolveNode to retrieve the node that you want to change.
3. Use IXFADataValue::value to set the value of the node.
The following example retrieves the Address node and sets the value for it. The example uses a variable
strAddress, which contains the address for the user. The example does not show the script that retrieved
the address from the database.
//retrieve the Address node
var nAddress=oFormNode.resolveNode(‘Address’);
//set the value for the Address node
nAddress.value=strAddress;
Removing Data
Remove a node from the data model when you no longer require the data.
Note To ensure that forms are properly populated with work item data, the structure of the data model
must correspond with the structure of the form.
For information about adding a node, see “Adding Nodes” on page 13
When you remove nodes from the data model, corresponding form fields remain on the form.
➤ To remove a node
1. Retrieve the data model of the work item.
For more information, see “Retrieving the Data Model” on page 10.
2. Use IXFADataModel::resolveNodes to retrieve the nodes you want to delete.
3. Use the IXFANode::nodes method to retrieve an IXFANodeList that includes the node you want to
remove.
4. Use IXFANodeList::remove to remove the node.
Manipulating Work Item Data Editing and Adding Data 13
For example, you want to create a list of people in your organization that includes information about how
to contact each of them. You have retrieved the information you need, but the data includes confidential
information about salaries. Because you want to distribute the contact list, you remove the nodes that
correspond with the confidential salary information.
//retrieve all the Salary nodes below the form node
var oNodeList = oFormNode.resolveNodes('Salary[*]');
//remove all of the Salary nodes
for (i=0;i<oNodeList.length;i++)
{var oNode = oNodeList.item(i);
oNode.parent.nodes.remove(oNode);
i=i-1; //decrement because the index changes after removing the node
}
Adding Nodes
Add nodes to the data model to append data to a work item.
Note To ensure that forms are properly populated with work item data, the structure of the data model
must correspond with the structure of the form.
If you want to specify a value for an existing node, see “Changing Data Values” on page 12.
You can include data that does not appear on the form, but is persisted for use with subsequent work
items in the process. To include hidden data, save the information in a node that does not have a
corresponding node on the form.
➤ To add a node
1. Use IXFADataModel::createNode to create a new node.
2. Use IXFANode::value to set a value for the node.
3. Use INodeList::append to add the node as the last node in the node list, or use INodeList::insert to
add the node at a specific place in the list.
For example, the form that is associated with a task is an order form that is sent to your supplier of
stationary products. You are populating the form with products that you want to order. To insert
products, you add nodes that correspond with the Product fields on the form.
//create a new node and set the value for it
var NewNode = oModel.createNode("dataValue", "total");
NewNode.value = ‘Pen51Blue’;
//NewNode has the value Pen51Blue
//Append the new node to the model
var someNode = oModel.resolveNode(‘$data.Order.Quantity’);
someNode.parent.nodes.append(NewNode);
3 Working With XML Files
Use XML files to pass data between Workflow Server and other third-party software. To interact with
other software, you can:
• Load XML from a file into the XFA data DOM. See “Loading XML Files” on page 14.
• Save work item data as XML. See “Exporting Data as XML” on page 16.
• Predict how information maps between XML and the XFA data DOM. See “Mapping XML to XFA”
on page 16.
LOADING XML FILES
To use data from an external source, read an XML document from a file and load it into the XFA data
DOM.
When you load the XML file, the corresponding XFA data model has the following structure:
To load XML from a file, you first create an instance of the data model, and then load the XML into the
model. After you load the XML, you can manipulate the data using the COM interfaces of the XFA data
DOM.
The information from the XML document that is accessible through the XFA data model includes:
• elements with character-data
• elements with element-content
• elements with mixed-content
• empty-elements
• attributes
Other information, such as XML processing instructions or element namespaces, does not appear in the
XFA data model, but is persisted. For more information, see “Specifying XML to Ignore” on page 15.
For information about how XML elements map to the XFA data DOM, see “Mapping XML to XFA” on
page 16.
datasets
data
ElementName1
...
DocumentNodeName
xfa
Working With XML Files Loading XML Files 15
You can load the entire XML file into the XFA data DOM, or specify portions of the XML to ignore. For
information, see “Specifying XML to Ignore” on page 15.
Your XML may be organized in several layers. For information about using data that is not flat, see
“Working with Nested Data” on page 20.
➤ To load XML files
1. Use XFAAppModel to instantiate the XFA model and add the XFA data model factory to the XFA
model.
2. Use XFAAppModel to load the XML file and then use IXFANode to retrieve the node that
corresponds with the XML document element.
For example, the following script from a process definition loads an XML file into the XFA data DOM.
The script then retrieves the data model for a work item, and appends the data from the XML document
to the data model. When the user opens the work item, the data from the XML document populates the
work item form.
//Instantiate the XFA model and add the XFA data model factory.
var oApp = Agent.CreateObject("AutoXFA.XFAAppModel");
var oFactory = Agent.CreateObject("AutoXFAData.XFADataModelFactory");
oApp.addFactory (oFactory);
//Load the XML file and retrieve the Order node, which corresponds with the XML
//document element.
var oRoot = oApp.loadFile("C:\\xmldata.xml");
var nDocument = oRoot.resolveNode("datasets.data.Order");
//Retrieve the data model for the work item, and retrieve the form node.
var oModel = WorkItem.data;
var nModelRoot = oModel.resolveNode("data.SomeFormName");
//Replace the work item data with the data from the XML file.
nModelRoot.parent.nodes.append(nDocument);
nModelRoot.parent.nodes.remove(nModelRoot);
Specifying XML to Ignore
When you load XML from a file into the XFA data DOM, you can specify XML that you do not want
represented in the XFA data DOM.
By default, Workflow Server loads all attributes, and contiguous elements that contain character data,
other elements, or both. Workflow Server does not load:
• The XML declaration, and document type declaration of the XML file.
• Attributes with the xml: namespace identifier.
• Namespace declarations.
• Content that belongs to the namespace http://www.xfa.com/schema/xfa-package/ or
http://www.xfa.org/schema/xfa-package/.
• Attributes that belong to the namespace http://www.xfa.org/schema/xfa-Data/1.0/.
Working With XML Files Exporting Data as XML 16
To specify the XML you do not want to load, you must edit the XML document appropriately. Use one of
the namespaces in the list to designate XML elements that you do not want to load.
Note The XML that you specify to ignore does not appear in the XFA data model, but is persisted. For
example, you load an XML file that includes namespace declarations. The namespace
declarations do not appear in the XFA data model. You save the XFA data model as an XML
document, and the XML file includes the namespace declarations.
EXPORTING DATA AS XML
Save data as XML when you want to make the data available to other software programs over a period of
time. When you store the XML to a file, the data is available until you delete the file.
If you want to make work item data available only one time, you can use an XMLExchange task in your
process definition. For more information, see the Using Workflow Designer guide.
You can save XML to a file, or in a string variable:
• To save data as XML to a file, use the IXFADataModel::saveAs method. This method saves the entire
XFA data model to the file. See “IXFADataModel” on page 29.
• To save data as XML in a string, use the IXFANode::saveXML method. This method returns a string
that contains an XML document that represents the node. See “IXFANode” on page 33.
Note When you save to a file, you can use the save options of the IXFADataModel::SaveAs method to
specify the character set to use, and to specify the white space to preserve. For information, see
“IXFADataModel” on page 29.
Your XFA data model may have been based on an XML document that you loaded. Some information
from the XML document does not appear in the XFA data model, but is persisted. When you save to an
XML document, the document includes all the persisted data.
MAPPING XML TO XFA
Workflow Server maps XML to XFA when you load an XML document into the XFA data DOM.
Workflow Server maps XFA to XML when you export an XFA model or node to an XML document.
When you load XML into the XFA data DOM, the XFA data model includes nodes that correspond with
the XML elements or attributes. Each XML element maps to either a data-value node, or a data-group
node.
• Data-value nodes hold a unit of data. The data is analogous to the character-data content of XML
elements. The children of data-value nodes can only be other data-value nodes.
The associated class in the COM library of the XFA data DOM is IXFADataValue.
• Data-group nodes do not hold data. Data-group nodes are the parents of other data-group nodes and
data-group values. Data-group nodes are analogous to XML elements with element content.
The associated class in the COM library of the XFA data DOM is IXFADataGroup.
When you load or export XML documents, you can use the mapping rules to predict the results. For
information, see “Mapping Rules for XML Elements” on page 17.
Working With XML Files Mapping XML to XFA 17
Mapping Rules for XML Elements
Workflow Server maps XML to the XFA data DOM when you load XML documents. Mapping rules allow
you to predict how the XFA data model represents XML when you load an XML document.
Workflow Server maps XML elements to either data-value nodes or data-group nodes in the XFA data
DOM. The properties of the XML elements determine the name, value, and contains properties of any
resulting data values, and the name property of any resulting data groups.
Mapping rules dictate how the XFA data model represents the following XML elements:
• XML elements that contain only character data. See “Mapping XML Leaf-Elements” on page 17.
• Element-content XML elements. See “Mapping XML Elements with Element Content” on page 17.
• Mixed-content XML elements. See “Mapping XML Elements with Mixed Content” on page 18.
• Attributes of XML elements. See “Mapping XML Attributes to XFA” on page 19.
Mapping XML Leaf-Elements
XML elements that contain only character data map to data-value nodes. The corresponding data-value
nodes have the following properties:
• name = XML element type.
• value = the character data that the XML element contains.
• contains = “data”.
For example, the XML element <price>$4500.00</price> maps to a data-value node with the name price,
a value of $4500.00, and a contains of data.
Note This rule also applies to XML elements with empty content. For empty content, the value of
corresponding data-value nodes is an empty string.
White space that appears in XML character data is preserved in the value of data-value nodes. White space
can be tab or space characters, line feeds, and carriage returns.
Mapping XML Elements with Element Content
XML elements that contain other XML elements map to either a data-group node or a data-value node.
• An XML element that contains other elements maps to a data-group node when no ancestors of the
XML element contain character data. The name property of the data-group node is the element type
of the XML element.
Note Data-group nodes can have only data-group nodes as ancestors.
• An XML element that contains other XML elements maps to a data-value node when any ancestors of
the XML element contain character data. The name property of the data-value node is the element
type of the XML element. The value property is the ordered concatenation of the character data of all
child elements of the XML element.
Note Data-value nodes can have only data-value nodes as descendents.
Working With XML Files Mapping XML to XFA 18
Mapping XML Elements with Mixed Content
XML elements that contain character data and other XML elements map to several data-value nodes. One
data-value node is created for:
• The XML element that contains the mixed content.
• Each fragment of character data that is directly within the XML element.
• Each child XML element.
The parent XML element maps to a data-value node with a name of the XML element type, a value of the
character data that the parent element and all child elements contain, and contains of “data”.
Each fragment of character data maps to a data-value node with a name of ““ (empty string), a value of
the fragment of character data, and a contains of “data”. These data-value nodes are children of the first
data-value node. Fragments of character data are character data that are separated by child elements.
The child XML elements map to data-value nodes according to the rules for mapping XML to the XFA
data model. The order of child data-values is the sequence that they appear in the XML.
date
month (August)
year (2003)
day (22)
order
date (22August2003)
month (August)
year (2003)
day (22)
order (Internal)
<order>
<date>
<day>22</day>
<month>August</mon
th>
<year>2003</year>
</date>
</order>
<date> has no ancestors that
contain character data.
<date> has ancestors that
contain character data.
<order>Internal
<date>
<day>22</day>
<month>August</mon
th>
<year>2003</year>
</date>
</order>
XML XFA
XML that corresponds
with a data value
Value of name
property Value of value property
Value of contains
property
Parent XML
element
The element type
of the parent XML
element.
The character data that the parent
element and all descendent
elements contain.
“data”
Fragment of
character data
“”(empty string) The fragment of character data. “data”
Child XML
element(s)
According to the
rules.
According to the rules. “data”
Working With XML Files Mapping XML to XFA 19
In the following example, an XML element with mixed content is mapped to a data-value node with
several child nodes.
Mapping XML Attributes to XFA
XML Attributes map to data-value nodes. A data-value node that corresponds with an attribute is a child
of the node that corresponds with the XML element of the attribute. The child nodes that correspond
with XML attributes are placed ahead of any child nodes that correspond with character data or element
content.
The data-value nodes that correspond with XML attributes have the following properties:
• name = attribute name.
• value = the value of the attribute.
• contains = “metadata”.
Expressing Null Values
When you load XML documents into the XFA data DOM, you can represent data as null values. Null
values are not the same as an empty value such as a zero-length string.
To load null values, you must edit the XML file. XML elements map to data-value nodes with values of
null if the element:
• Belongs to the following namespace:
http://www.w3.org/2000/10/XMLSchema-instance
• Has an attribute nil in the same namespace, assigned a value of true.
For example,
Note If the nil attribute has a value of false, the element is interpreted as a zero-length string in the XFA
data DOM.
<Model>Generic Laptop
<Mem>512 Mb</Mem>
<Disk>50 Gb</Disk>
</Model>
Model (Generic Laptop 512 MB50 Gb)
Mem (512 Mb)
Disk (50Gb)
(Generic Laptop)
XML element that contains
character data and XML elements.
Corresponding data-value nodes in the
XFA data model.
ISBN (null)
title (Introduction to XFA)
book <book
xmlns:null="http://www.w3.org/2000/10/
XMLSchema-instance">
<null:ISBN null:nil=’true’/>
<title>Introduction to XFA</title>
</book>
4 Working with Nested Data
Work items that use Form Server 5.1 forms, or HTML forms produce data that has a flat structure. There
are two scenarios where you can encounter nested data, which is not flat:
• You import XML that is structured using several levels.
• Your users process work items using e-mail and Adobe Form Client, and the work item forms use
grouped fields.
To use nested data, you step down into the data model to access specific nodes.
You can use the XFA Scripting Object Model (SOM) to reference any node in a data model. The following
XFA COM object methods use an XFA SOM expression as arguments:
• IXFANode::resolveNode
• IXFANode::resolveNodes
For example, the following expression returns an IXFANode object with the name of A.
oNode.resolveNode(‘A’);
where A is the XFA SOM expression.
For information about creating XFA SOM expressions, see “XFA SOM Expressions” on page 20.
XFA SOM EXPRESSIONS
Use XFA SOM expressions to reference specific nodes in an XFA data model.
For information about how to use SOM expressions with the XFA COM objects, see “Retrieving Field
Data” on page 11.
XFA SOM expressions use the name property of data nodes to identify them. The simplest SOM
expressions consist of a single node name. More complicated SOM expressions can include more than
one node name, occurrence numbers, and wildcard characters.
Note Node names are case-sensitive. Ensure that you use the proper case when you specify the name.
For example, A is an XFA SOM expression that references node A. The expression A.B references the first
child of A that has the name B.
Working with Nested Data XFA SOM Expressions 21
XFA SOM expressions use the following syntax:
Name1['['index|*']'][‘.’|’..’Name2]
– Name1 is the name of the node to be searched, beginning at the current node. Node names are
case-sensitive.
– index is the occurrence number. For information, see “Using Occurrence to Identify Nodes” on
page 21.
– * is a wildcard character. For information, see “Using Shortcut Notation in SOM Expressions”
on page 23.
– . or .. with a different node name Name2 searches for a node named Name2 that is a
descendent of node Name1. For information, see “Referencing Descendent Nodes” on page 22.
– Text inside brackets (“[ ]”) is optional.
– Characters inside quotes (‘‘) represent the literal characters.
– Vertical bars (“|”) separates possible values for a parameter.
Using Occurrence to Identify Nodes
Use occurrence numbers in XFA SOM expressions to reference different nodes that have the same name
in an XFA data model.
Occurrence numbers are a 0-based index that represent the order of sibling nodes that have the same
name. For example, in a flat data model, the third node named Product has an occurrence number of 2. In
XFA SOM expressions, occurrence numbers appear after the node name inside brackets (“[]”).
If you want information about using XFA SOM expressions in script, see “Working with Nested Data” on
page 20.
In XFA SOM expressions, you use either:
• Absolute occurrence numbers. See“Absolute Occurrence Numbers” on page 21.
• Occurrence numbers that are relative to the occurrence number of the referencing node. See “Relative
Occurrence Numbers” on page 22.
Absolute Occurrence Numbers
In XFA SOM expressions, absolute occurrence is the position of like-named sibling nodes relative to the
referencing node.
For information about the referencing node, see “Understanding Node Resolution” on page 23.
Working with Nested Data XFA SOM Expressions 22
For example, a purchase order form includes one row of information for each product that a client orders.
Each row includes the fields Product, Model, Quantity, and Price. The occurrence number for the fields in
the fourth row is 3. The following script uses the XFA SOM expression Product[3] to retrieve the
value of the Product field in the fourth row:
var strProduct = oIXFADataModel.resolveNode(‘Product[3]’).value;
In this example, the referencing node is oIXFADataModel.
For more information about using occurrence numbers in SOM expressions, see “Using Occurrence to
Identify Nodes” on page 21.
Relative Occurrence Numbers
In XFA SOM expressions, relative occurrence is the position of like-named sibling nodes relative to the
occurrence number of the referencing node.
For information about the referencing node, see “Understanding Node Resolution” on page 23.
A positive or negative occurrence number indicates relative occurrence:
• A positive occurrence number indicates a higher occurrence than the occurrence of the referencing
node. For example, if node D has an occurrence number of 3, then D.E[+1] finds the E node below D
that has an absolute occurrence number of 4.
• A negative occurrence number indicates a lower occurrence than the referencing node. For example,
if node D has an occurrence number of 3, then D.E[-2] finds the E node below D that has an absolute
occurrence number of 1.
You typically use relative occurrence to reference the previous or next occurrence of a particular node. For
example, oNode represents the first A node below node Z in the diagram below. The following script
returns the second A node.
var SecondANode = oNode.resolveNode(‘A[+1]’);
Referencing Descendent Nodes
XFA SOM expressions use a special notation to represent descendent nodes.
• Use a period to denote immediate child nodes. For example, A.B denotes the first child with the name
B of node A.
• Use two periods to denote the nearest descendent, regardless of how removed. For example, A..C
denotes the nearest descendent of node A with the name C.
datasets
data
Z
B
A
A
Referencing node
Working with Nested Data Understanding Node Resolution 23
For example, oNode represents the first A node below node Z in the diagram below. The following script
returns the C node that is the descendent of oNode.
var CNode = oNode.resolveNode(‘A..C’);
Using Shortcut Notation in SOM Expressions
XFA SOM provides several wildcard characters that make writing XFA SOM expressions easier:
• "$" refers to the current node.
• "!" refers to the first two nodes of the XFA model (i.e. xfa.datasets).
• “$data" refers to the root node of the data model (i.e. xfa.datasets.data).
• A[*] finds the first A node, and all its siblings that are called A.
For example, oNode represents node Z in the diagram below. The following script returns an
IXFANodeList object that contains both A nodes:
var ANodes = oNode.resolveNodes(‘A[*]’);
UNDERSTANDING NODE RESOLUTION
To use XFA SOM expressions, you must understand how the expression is evaluated. This information
will help you create SOM expressions that resolve to the desired nodes.
If you want information about using SOM expressions in script, see “Understanding Node Resolution” on
page 23.
XFA SOM expressions are evaluated in the context of a referencing node. In script, the referencing node is
the node object that uses the IXFANode::resolveNode or IXFANode::resolveNodes method.
datasets
data
Z
B
A
A
C
datasets
data
Z
B
A
A
Working with Nested Data Understanding Node Resolution 24
To find the node or nodes that satisfy a given XFA SOM expression:
• The search for the node occurs first in the child nodes of the referencing nodes. See “SOM
Expressions That Resolve to Child Nodes” on page 24.
• If no child node satisfies the expression, the search continues up the hierarchy of the data model. See
“SOM Expressions That Do Not Resolve to Child Nodes” on page 24.
SOM Expressions That Resolve to Child Nodes
The search for the node or nodes that satisfy a SOM expression occurs first in the child nodes of the
referencing node. Node resolution occurs when the referencing node has a child that satisfies the SOM
expression.
For information about the referencing node, see “Understanding Node Resolution” on page 23.
For example, in the diagram below, oNode is a variable that represents node Z. The following script
evaluates the XFA SOM expression in the context of node Z:
oNode.resolveNode(‘A’);
The SOM expression resolves to the first child of node Z that has the name A.
If there is more than one child node of the same name, the SOM expression resolves to the node with the
lowest index. For information about node indexes, see “IXFANodeList” on page 36.
If the referencing node has no child nodes that satisfy the SOM expression, the search continues up the
hierarchy of the data model. For information, see “SOM Expressions That Do Not Resolve to Child
Nodes” on page 24.
SOM Expressions That Do Not Resolve to Child Nodes
The search for the node or nodes that satisfy an XFA SOM expression can occur in the hierarchy above the
referencing node. The search occurs upwards in the hierarchy if no child node of the referencing node
satisfies the SOM expression.
For information about the referencing node, see “Understanding Node Resolution” on page 23.
When searching upwards in the hierarchy, the search continues in the siblings of the reference node, and
in the ancestors of the referencing node and their siblings, until the node is resolved.
datasets
data
Z
B
A
A
Working with Nested Data Understanding Node Resolution 25
The number of nodes that exist in the data model that can satisfy the SOM expression determines the
node to which the expression resolves. Different results occur if:
• Only one sibling of an ancestor has the node name that is being searched.
• Many siblings of an ancestor have the node name that is being searched.
More rules apply if the SOM expression includes a compound name. For information, see “Resolving
Compound Names” on page 26.
One Node Satisfies the SOM Expression
If only one ancestor node or sibling node of an ancestor has the node name that is being searched, the
expression evaluates to that node.
For example, in the diagram below, oNode represents the node B below node A. Node B has no child
nodes with the name X. The search for node X occurs in the siblings of A. The following expression
returns the X node.
resolvedNode = oNode.resolveNode(‘X’);
More Than One Node Satisfies the SOM Expression
When more than one node has the name that appears in the SOM expression, the occurrence numbers of
the referencing node and of its ancestors determine the node to which the SOM expression resolves.
If you want information about occurrence numbers, see “Using Occurrence to Identify Nodes” on
page 21.
To resolve the node, the SOM expression selects the sibling of the ancestor that has the same occurrence
number as that ancestor.
datasets
data
Z
B
A
X
C
Referencing node
Working with Nested Data Understanding Node Resolution 26
For example, in the diagram below, oNode represents the second node B below the first node A. The first
node A has an occurrence number of 0. Node B has the occurrence number 1. The following expression
returns a node with the name X. The resolved node is at the same level as the ancestor node A, and has the
same occurrence number as that node A:
resolvedNode = oNode.resolveNode(‘X’)
The following steps describe how the node resolution occurs:
1. Search the child nodes of Node B for a node with the name X.
No node found.
2. Search the sibling nodes of node B for a node with the name X.
No node found.
3. Search the parent of node B and the siblings of the parent for a node with the name X.
There are two nodes with the name X that are siblings of the parent of node B.
4. The parent of node B has the occurrence number of 0, so the expression evaluates to the X node with
the occurrence number 0.
Resolving Compound Names
For compound XFA SOM expressions, the path to the resolved node may mirror the path to the
referencing node. When the search occurs in the hierarchy above the referencing node, the path to the
referencing node determines the path to the node to which the XFA SOM expression resolves.
For more information about compound XFA SOM expressions, see “Referencing Descendent Nodes” on
page 22.
The first name in the compound expression is resolved using the method described in “SOM Expressions
That Do Not Resolve to Child Nodes” on page 24. The subsequent names in the compound name are
found based on the occurrence numbers of the nodes in the path to the referencing node. The nodes in
datasets
data
Z
B[0]
X[0]
A[0]
B[0]
X[1]
A[1]
B[1]
D[0]
D[1]
D[2]
D[0]
D[1]
[0]
Numbers in brackets are
occurrence numbers.
oNode.resolveNode(‘X’)
Referencing
node
Working with Nested Data Understanding Node Resolution 27
the path to the resolved node have the same occurrence numbers as the nodes in the path to the
referencing node.
For example, in the diagram below, oNode represents the second node B below the first node A. The
following expression returns a node with the name D, that is a child of a node named X:
oNode.resolveNode(‘X.D’)
The following steps describe how the node resolution occurs:
1. The first node in the compound expression, node X, is found using the method described in “SOM
Expressions That Do Not Resolve to Child Nodes” on page 24.
From the level in the hierarchy where the first node in the compound expression is found, the path to
the referencing node is A[0].B[1], so the nodes in the path to the referenced node have the occurrence
numbers 0 and 1.
2. Search for child nodes of node X that have the name D.
There are three nodes named D below the node X.
3. Return the D node that has the occurrence number of 1.
datasets
data
Z
B[0]
X[0]
A[0]
B[0]
X[1]
A[1]
B[1]
D[0]
D[1]
D[2]
D[0]
D[1]
[0]
oNode.resolveNode(‘X.D’)
Referencing
node
Numbers in brackets are
occurrence numbers.
5 XFA Data COM Object Reference
Use the classes and interfaces of the AutoXFAData and AutoXFA COM libraries to access XFA data
models. All the members of the AutoXFAData library are useful to your Workflow Server script. Only two
members of the AutoXFA library are useful.
The following diagram shows the inheritance of the members of the AutoXFAData library:
Library Member
AutoXFAData IXFADataGroup
IXFADataModel
IXFADataValue
IXFAModel
IXFAModelFactory
IXFANode
IXFANodeList
IXFAObject
XFADataModelFactory
AutoXFA XFAAppModel
IXFAStringList
IXFAObject
IXFANode
IXFAModel
IXFADataGroup
IXFADataValue
IXFAModelFactory
IXFANodeList
XFADataModelFactory
IXFADataModel
AutoXFAData Library
XFA Data COM Object Reference IXFADataGroup 29
IXFADATAGROUP
IXFADataGroup is the interface associated with data-group nodes in an XFA data model.
Data-group nodes are the parents of other data-group nodes and data-group values. Data-group nodes do
not hold data. Data group nodes are analogous to element-content XML elements.
IXFANodeGroup inherits the properties and methods of IXFAObject, and IXFANode.
IXFADATAMODEL
IXFADataModel is the starting point for any XFA data work such as opening or saving a data source, or
creating new nodes. IXFADataModel is the interface associated with the datasets node in an XFA data
model.
IXFADataModel is useful for manipulating work item data. Use the WorkItem::data method of the
Workflow Server JScript extensions to retrieve the data model of a work item. To change the work item
data, you make changes to the nodes below datasets.
Note For work item data, the node below data represents the form for the work item.
In addition to the following properties and methods, IXFADataModel inherits the properties and
methods of IXFAObject, IXFANode, and IXFAModel.
Properties
saveFormat
This Property returns a constant that represents the data format of the IXFADataModel. saveFormat
determines the text in a string that the IXFANode::saveXML method returns.
The data format can be XPF or XML:
• If saveFormat returns 1, the format is XML.
• If saveFormat returns 2, the format is XPF.
Properties Methods
saveFormat saveAs
datasets
data
FieldName1
FieldName2
...
FieldNameN
FormName
XFA Data COM Object Reference IXFADataValue 30
Methods
saveAs
This method saves the data model as an XML document to the file system. You can use the saveOptions
parameter to specify either the white space or the character encoding.
Syntax
oDataModel.saveAs(filename, [saveOptions]);
filename is the name of the file and the path to the network drive where it is located.
saveOptions is a parameter in the form format=option:
Example
var strFile=’C:\SavedXML.xml’;
var strOptions=’format=UTF
oDataModel.saveAs(strFile, strOptions);
IXFADATAVALUE
IXFADataValue is the interface associated with data-value nodes in an XFA data model.
Data value nodes hold a unit of data. The data is analogous to the character-data content of XML
elements. The children of data-value nodes can only be other data-value nodes.
In addition to the following properties and methods, IXFADataValue inherits the properties and methods
of IXFAObject, and IXFANode.
Value of option Description
raw Save with no white space or carriage returns.
simple Save with carriage returns and no white space.
pretty Save with carriage returns and white spaces.
character encoding
string, such as
“UTF
The character set to use when writing the XML file.
Properties Methods
contains
contentType
match
value
(no methods)
XFA Data COM Object Reference IXFAModel 31
Properties
contains
This property returns a string that indicates the relation of this node to the parent node:
• A value of “data” indicates that this node maps to a child XML element.
• A value of “metadata” indicates that this node maps to an XML attribute.
contentType
Returns a string that contains the content type of this data value.
match
This property returns a constant that indicates whether the name of this node is unique within the data
model.
• A value of 2 indicates that this node matches more than one other node.
• A value of 1 indicates that this node matches one other node.
• A value of 0 indicates that this node matches no other nodes.
value
Returns a string that contains the value of this data value node.
If the data value node has child nodes, the value includes the concatenation of the values of the child
nodes. For example, the following diagram illustrates a data-value node date that has three child nodes.
The value of date is the concatenation of the values of the child nodes.
IXFAMODEL
IXFAModel is the base interface for the IXFADataModel, and other XFA model types.
date (22August2003)
month (August)
year (2003)
day (22)
order (Internal)
IXFANode
IXFAModel
createNode
XFA Data COM Object Reference IXFAModelFactory 32
In addition to the following properties and methods, IXFAModel inherits the properties and methods of
IXFAObject, and IXFANode.
Methods
createNode
Creates and returns a new IXFANode based on a valid classname that you specify.
Syntax
oNode=oModel.createNode(className, [nodeName], [namespace]);
className is a string that holds a valid class for the node.
nodeName is an optional string that holds the name of the new node. If no value is provided, the
name of the node is an empty string.
namespace is an optional string that holds the namespace to which the node belongs. If no value is
provided, the namespace of the node is an empty string.
For an example that uses createNode in script, see “Adding Nodes” on page 13.
IXFAMODELFACTORY
IXFAAppModel uses XFAModelFactory to create an IXFAModel when loading an XML file. The factory
provides interfaces for defining the behaviors of the newly created IXFAModel.
Properties
rootName
This property returns a string that contains the name of the root node of the model factory.
Properties Methods
(no properties) createNode
Properties Methods
rootName (no methods)
XFA Data COM Object Reference IXFANode 33
IXFANODE
IXFANode is the base interface for all nodes.
In addition to the following properties and methods, IXFANode inherits the properties and methods of
IXFAObject.
Properties
all
This property returns an IXFANodeList that contains a collection of all like-named, in-scope, same-typed
nodes.
If you want to retrieve a list of all child nodes, see “nodes” on page 34.
Properties Methods
all
index
model
name
nodes
parent
applyXSL
clone
loadXML
resolveNode
resolveNodes
saveXML
IXFANode
IXFANode
IXFANode
IXFANode
IXFAModel model
nodes
parent
clone
resolveNode
resolveNodes IXFANodeList
IXFANodeList
IXFANode createNode
IXFANode
IXFANode item
namedItem
XFA Data COM Object Reference IXFANode 34
The IXFANodeList that results from using this property changes automatically as the property changes.
For example, your code contains the expression
var oNodeList=oNode.all;
At some point after this expression is evaluated, several nodes are deleted from the data model. The nodes
are automatically removed from oNodeList.
index
This property returns a long value that represents the 0-based position of this node in its collection of
like-named, in-scope, same-typed nodes.
model
This property returns the IXFAModel object that represents the model of this node.
name
This property returns or sets a string that contains the name of the node object.
nodes
This property returns an IXFANodeList object that contains all child IXFANodes belonging to this node
object.
The IXFANodeList that results from using this property changes automatically as the property changes.
For example, your code contains the expression
var oNodeList=oNode.all;
At some point after this expression is evaluated, several child nodes are deleted. The nodes are
automatically removed from oNodeList.
parent
This property returns an IXFANode object that represents the parent of this node. If the parent does not
exist, this method returns NULL.
Methods
applyXSL
This method returns a string that contains the XML representation of this node, that has been
transformed by a specified XSL transformation.
Note Workflow Agent does not ensure that the returned string contains valid XML.
The results of this method are equivalent to the results of calling saveXML and transforming the result
with the specified XSL document.
XFA Data COM Object Reference IXFANode 35
Syntax
var strTransformed=oNode.applyXSL(xslString);
xslString is a string variable that contains the XSL document.
clone
This method returns a new IXFANode object with the same properties as the current node.
Syntax
var oCloneNode=oNode.clone(deep);
deep is a Boolean that indicates whether the clone action is recursive:
– If deep is TRUE, the clone is recursive and applies to all child nodes.
– If deep is FALSE, the clone is not recursive, and applies only to the current node. The new node
does not have children.
loadXML
This method loads and appends the specified XML document to this node.
Note Workflow Agent does not ensure that the document contains valid XML.
Syntax
oNode.loadXML(xmlString, [ignoreAggregatingTag];
xmlString is a string variable that holds the XML document you want to append.
ignoreAggregatingTag is a Boolean variable that specifies whether to load the XML document
node. The default value is TRUE:
– If TRUE, the document node of the XML is ignored and only its children are loaded.
– If FALSE, the document node and its children are loaded.
resolveNode
This method returns an IXFANode object according to the specified XFA SOM (Scripting Object Model)
expression.
The SOM expression must evaluate to a single node:
• If the SOM expression does not evaluate to a node, this method returns a null node.
• If the SOM expression evaluates to more than one node, this method throws an exception.
XFA Data COM Object Reference IXFANodeList 36
Syntax
oFoundNode=oNode.resolveNode(somExpression);
somExpression is an XFA SOM expression that identifies the node you want to retrieve. For
information about XFA SOM expressions, see “XFA SOM Expressions” on page 20.
Example
oProd=oOrder.resolveNode(‘product[3]’);
resolveNodes
This method returns an IXFANodeList object according to the specified XFA SOM (Scripting Object
Model) expression. If the SOM expression does not evaluate to any nodes, this method returns an empty
IXFANodeList.
Syntax
oNodeList=oNode.resolveNodes(somExpression);
somExpression is an XFA SOM expression that identifies the nodes you want to retrieve. For
information about XFA SOM expressions, see “XFA SOM Expressions” on page 20.
For an example of the use of resolveNodes in script, see “Removing Data” on page 12.
saveXML
This method saves the current node as an XML fragment to a string.
Syntax
strXML=oNode.saveXML();
IXFANODELIST
IXFANodeList is a collection of IXFANode objects.
IXFANode
IXFANode
IXFANodeList
item
namedItem
XFA Data COM Object Reference IXFANodeList 37
In addition to the following properties and methods, IXFANodeList inherits the properties and methods
of IXFAObject.
Properties
item
This property retrieves a specific IXFANode object from the 0-base indexed collection of nodes.
Syntax
oNode=oNodeList.item(index);
index is a long that indicates the position of the node in the collection.
length
This property returns a long containing the number of IXFANode objects in the collection.
namedItem
This property returns the IXFANode object in the collection that has the specified name. If more than one
node has the specified name, namedItem returns the node with the numerically lowest index.
Syntax
oNode=oNodeList(name);
name is the name of the node you want to retrieve.
Methods
append
This method appends an IXFANode to the collection as the last item in the list.
When you append a node, the value of the length property increases by 1. The node you append has the
numerically highest index.
Properties Methods
item
length
namedItem
append
insert
remove
XFA Data COM Object Reference IXFAObject 38
Syntax
oNodeList.append(oNode);
oNode is the node you want to append.
For an example of the use of append in script, see “Adding Nodes” on page 13.
insert
This method inserts a specific IXFANode to the collection at a given position in the list.
When you insert a node, the value of the length property increases by 1. The index of each item in the list
is also adjusted appropriately.
Syntax
oNodeList.insert(oNode, oRefChild);
oNode is an IXFANode object that represents the node you want to insert.
oRefChild is an IXFANode object that represents the reference node in the collection. oNode is
inserted before oRefChild. If oRefChild does not exist, this method throws an exception.
remove
This method removes the specified IXFANode from this collection.
When you remove a node, the value of the length property decreases by 1. The index of some nodes in the
list also change. Nodes with an index that are higher than the index of the node you remove decrease by 1.
Syntax
oNodeList.remove(oNode);
oNode is an IXFANode object that represents the node you want to remove. If oNode does not
exist, this method throws an exception.
For an example of the use of remove in script, see “Removing Data” on page 12.
IXFAOBJECT
IXFAObject is the base interface for all XFA COM objects
Properties
className
This property returns a string that contains the class name of the XFA object.
Properties Methods
className (no methods)
XFA Data COM Object Reference IXFAStringList 39
IXFASTRINGLIST
A collection of character strings.
In addition to the following properties and methods, IXFAStringList inherits the properties and methods
of IXFAObject
Properties
item
This property retrieves a specific string from the 0-base indexed collection of strings.
Syntax
bString=oStringList.item(index);
index is a long that indicates the position of the string in the collection. If the index is out of range,
this method throws an exception.
length
This property returns a long that contains the number of strings in the collection.
XFADATAMODELFACTORY
XFAAppModel uses XFADataModelFactory to create a data model where appropriate when loading an
XML file. The factory provides interfaces for defining the behaviors of the newly created data model.
var oApp = Agent.CreateObject("AutoXFA.XFAAppModel");
var oFactory = Agent.CreateObject("AutoXFAData.XFADataModelFactory");
oApp.addFactory (oFactory);
Properties Methods
item
length
(no methods)
Properties Methods
attributesAreValues
rootName
(no methods)
XFA Data COM Object Reference XFAAppModel 40
Properties
attributesAreValues
This property returns a Boolean that indicates whether XML attributes are treated as IXFADataValue
nodes when loading XML documents into the XFA data DOM.
• If TRUE, XML attributes have corresponding IXFADataValue nodes in the XFA data DOM.
• IF FALSE, attributes do not have corresponding IXFADataValue nodes in the XFA data DOM.
Note When this property is FALSE when you load an XML document into the XFA data DOM, the
XML attributes are preserved. When you export the data model to an XML document, the
attributes appear in the XML.
rootName
This property returns a string that holds the name of the root node of the factory.
XFAAPPMODEL
XFAAppModel is the top-level object in the XFA object model. All models are represented as sub-models
below this one. The following graphic shows an XFA model that uses the XFA data model.
Use XFAAppModel to open and save XML documents. The model that this object uses is specified in a
model factory, through the XFAAppModel::addFActory method.
var oApp = Agent.CreateObject("AutoXFA.XFAAppModel");
var oFactory = Agent.CreateObject("AutoXFAData.XFADataModelFactory");
oApp.addFactory (oFactory);
datasets
data
ElementName1
...
DocumentNodeName
xfa
XFA Data COM Object Reference XFAAppModel 41
Properties Methods
all
className
context
index
model
name
nodes
parent
addFactory
applyXSL
clone
createNode
loadFile
loadXML
newDOM
resolveNode
resolveNodes
saveXML
XFAAppModel
IXFANode
IXFANode
IXFANode
IXFAModel model
nodes
parent
clone
resolveNode
resolveNodes IXFANodeList
IXFANodeList
IXFANode createNode
IXFANode createNode
IXFANode newDOM
all IXFANodeList
IXFANode
IXFANode item
namedItem
IXFANode context
classNames IXFAStringList
XFA Data COM Object Reference XFAAppModel 42
Properties
all
This property returns an IXFANodeList that contains a collection of all like-named, in-scope, same-typed
nodes. If the data model is derived from an XML document, this property returns nodes regardless of the
namespace of the corresponding XML elements.
If you want to retrieve a list of all child nodes, see “nodes” on page 34.
The IXFANodeLists that result from using this property change automatically as the property changes.
For example, your code contains the expression
var oNodeList=oNode.all;
At some point after this expression is evaluated, several nodes are deleted from the data model. The nodes
are automatically removed from oNodeList.
className
This property returns a string that contains the class name of the XFA object.
context
This property returns an IXFANode that represents the current starting node for calls to the resolveNode
and resolveNodes methods.
index
This property returns a long value that represents the 0-based position of this node in its collection of
like-named, in-scope, same-typed nodes.
model
This property returns the IXFAModel object that represents the model of this node.
name
This property returns or sets a string that contains the name of the node object.
nodes
This property returns an IXFANodeList object that contains all child IXFANodes belonging to this node
object.
The IXFANodeList that results from using this property changes automatically as the property changes.
For example, your code contains the expression
var oNodeList=oNode.all;
At some point after this expression is evaluated, several child nodes are deleted. The nodes are
automatically removed from oNodeList.
XFA Data COM Object Reference XFAAppModel 43
parent
This property returns an IXFANode object that represents the parent of this node. If the parent does not
exist, this method returns NULL.
Methods
addFactory
Adds a given model factory to the list of available factories. Add factories for models to use in a full
implementation. If no model is specified, a default model is used which has minimal functionality.
Syntax
oAppModel.addFactory(factory);
factory is an IXFAModelFactory object.
For an example of the use of addFactory in script, see “Loading XML Files” on page 14.
applyXSL
This method returns a string that contains the XML representation of this node, that has been
transformed by a specified XSL transformation.
Note Workflow Agent does not ensure that the returned string contains valid XML.
The results of this method are equivalent to the results of calling saveXML and transforming the result
with the specified XSL document.
Syntax
var strTransformed=oAppModel.applyXSL(xslString);
xslString is a string variable that contains the XSL document.
clone
This method returns an IXFANode object with the same properties as this node.
Syntax
var oCloneNode=oAppModel.clone(deep);
deep is a Boolean that indicates whether the clone action is recursive:
– If deep is TRUE, the clone is recursive and applies to all child nodes.
– If deep is FALSE, the clone is not recursive, and applies only to the current node. The new node
does not have children.
XFA Data COM Object Reference XFAAppModel 44
createNode
This method creates and returns a new IXFANode object based on a valid classname that you specify.
Syntax
oNode=oAppModel.createNode(className, [nodeName], [namespace]);
className is a string that holds a valid class for the node. If the given classname is not valid, this
method throws an exception.
nodeName is an optional string that holds the name of the new node. If no value is provided, the
name of the node is an empty string.
namespace is an optional string that holds the namespace to which the node belongs. If no value is
provided, the namespace of the node is an empty string.
loadFile
This method loads and appends the specified XML file to this node. You can automatically process an XSL
script when you load the file. Other options can be set.
Syntax
oNode=oAppModel.loadFile(XMLFile, [processXSL], [loadOptions]);
XMLFile is a string that holds the file name and location of the file you want to load.
processXSL is a Boolean that determines if the XSL transformation is applied when loading occurs.
The default is TRUE:
– TRUE means apply XSL processing instructions that are found in the XML file.
– FALSE means do not apply processing instructions that are found.
loadOptions is a string that holds options you want to use when loading, in the format:
OptionName = ‘OptionValue’[Option2Name = ‘Option2Value’]...
OptionName is the name of the option.
OptionValue is the value of the option.
The following OptionName-OptionValue pairs are available:
• processXSL=[1|0] (Set to a value of 1 to apply processing instructions found in the XML
file.)
• XSL="filename" (filename is the file that holds the XSL script to apply to the loaded
XML.)
Note If you provide a value for processXSL and you use the processXSL load option, the
value for processXSL is used.
For an example of the use of loadFile in script, see “Loading XML Files” on page 14.
XFA Data COM Object Reference XFAAppModel 45
loadXML
This method loads and appends the specified XML document to this node.
Syntax
oAppModel.loadXML(xmlString, [ignoreAggregatingTag];
xmlString is a string variable that holds the XML document you want to append.
ignoreAggregatingTag is a Boolean variable that specifies whether to load the XML document
node. The default value is TRUE:
– If TRUE, the document node of the XML is ignored and only its children are loaded.
– If FALSE, the document node and its children are loaded.
newDOM
This method returns an IXFANode that represents the root node of a new XFA DOM.
Syntax
oNode=oAppModel.newDOM();
resolveNode
This method returns an IXFANode object according to the specified XFA SOM (Scripting Object Model)
expression.
The SOM expression must evaluate to a single node:
• If the SOM expression does not evaluate to a node, this method returns a null node.
• If the SOM expression evaluates to more than one node, this method throws an exception.
Syntax
oFoundNode=oAppModel.resolveNode(somExpression);
somExpression is an XFA SOM expression that identifies the node you want to retrieve.
resolveNodes
This method returns an IXFANodeList object according to the specified XFA SOM (Scripting Object
Model) expression. If the SOM expression does not evaluate to any nodes, this method returns an empty
IXFANodeList.
Syntax
oNodeList=oAppModel.resolveNodes(somExpression);
somExpression is an XFA SOM expression that identifies the nodes you want to retrieve.
saveXML
This method saves the current node as an XML fragment to a string.
strXML=oAppModel.saveXML();
Index
Symbols
! SOM special character 23
$ SOM special character 23
$data SOM special character 23
* SOM special character 23
A
absolute occurrence 21
adding data nodes 13
ancestor nodes
resolving non-unique 25
resolving unique 25
attributes, mapping to XFA 19
C
changing work item data 12
child nodes, SOM expressions 22
COM objects, XFA data 28
creating XFA data models 14
D
data
changing 12
form fields 11
manipulating 10
nested 20
null values 19
structure 8
data handling
accessing the data model 8
adding nodes 13
changing 12
loading XML 14, 15
removing nodes 12
typical tasks 7
data models
exporting 16
flat 9
mapping from XML 17
nested 9
node types 16
retrieving 10
data node types 16
data-group nodes 16
from element content 17
data-value nodes 16
from attributes 19
from element content 17
from leaf elements 17
from mixed content 18
descendent nodes
node resolution 26
SOM expressions 22
determining node types 17, 18, 19
documentation suite 6
duplicate nodes 21
E
element content, mapping to XFA 17
evaluating SOM expressions 23
F
field data 11
fields, retrieving data 11
Form Client, data model of forms 9
form data, retrieving 11
form fields, data 8
Form Server
data model for forms 9
forms
manipulating data 10
retrieving data 11
Index 47
H
HTML data model for forms 9
I
ignoring XML fragments 15
importing XML 14
importing XML, selective 15
inheritance, COM objects 28
IXFADataGroup 29
IXFADataModel 29
resolveNode example 11
retrieving data 10
saveAs method 30
saveFormat property 29
IXFADataModelFactory 39
attributesAreValues property 40
rootName property 40
IXFADataValue 30
contains property 31
contentType property 31
match property 31
value property 31
IXFAModel 31
createNode method 32
IXFAModelFactory 32
rootName property 32
IXFANode 33
all property 33
applyXSL method 34
clone method 35
index property 34
loadXML method 35
model property 34
name property 34
nodes property 34
parent property 34
resolveNode method 35
resolveNodes method 36
saveXML method 36
IXFANodeList 36
append method 37
insert method 38
item property 37
length property 37
namedItem property 37
remove method 38
IXFAObject 38
className property 38
IXFAStringList 39
item property 39
length property 39
IXMLData, retrieving data 10
J
JScript extensions, accessing data 8
L
layered data 20
leaf elements, mapping to XFA 17
loading XML 14
selectively 15
M
manipulating data 10
mapping XML to XFA 17
mixed-content elements, mapping to XFA 18
N
native PDF, data model for forms 9
nested data 20
node resolution 11, 20, 23
ancestor nodes 24
child nodes 24
compound names 26
nodes
absolute occurrence 21
adding to data model 13
changing 12
distinguishing duplicates 21
referencing node 23
relative occurrence 22
removing from data model 12
resolving 11, 20, 23
nodes, mapping
from attributes 19
from element content 17
from mixed-content elements 18
null values in data 19
Index 48
O
object diagrams
IXFADatamodel 29
IXFAModel 31
IXFANode 33
IXFANodeList 36
XFAAppModel 40
Object Library, accessing data 8
occurrence
absolute 21
relative 22
occurrence numbers 21
P
PDF, data model for forms 9
process definitions, retrieving work item data 10
R
referencing node 23
relative occurrence 21, 22
removing data nodes 12
resolving nodes 11, 20
ancestors 24
children 24
non-unique ancestors 25
unique ancestors 25
retrieving
field data 11
the data model 10
S
saving data as XML 16
scripting
adding data nodes 13
changing data nodes 12
creating data model objects 14
removing data nodes 12
retrieving field data 11
shorthand, SOM 23
signed occurrence numbers 22
SOM 20
SOM expressions
compound names 26
descendent nodes 22
evaluating 23
resolving to ancestors 24
resolving to children 24
special characters 23
syntax 20
structure data model 8
syntax, SOM expressions 20
T
types of data nodes 16
W
Web applications, retrieving work item data 10
work item data
adding nodes 13
changing 12
removing 12
retrieving 10
saving as XML 16
work items
changing data 12
manipulating data 10
Workflow Server documentation 6
X
XFA 7
XFA data DOM 7
JScript extensions 8
Object Library 8
tree structure 8
XFA data model
exporting to XML 16
from XML 14
instantiating 14
XFA data, COM objects 28
XFA SOM 20
XFA SOM expressions 11
XFA SOM, descendent nodes 22
XFA to XML 17
Index 49
XFAAppModel 40
addFactory method 43
all property 42
applyXSL method 43
className property 42
clone method 43
context property 42
createNode method 44
index property 42
instantiating XFA models 14
loadFile method 44
loadXML method 45
model property 42
name property 42
newDOM method 45
nodes property 42
parent property 43
resolveNode method 45
resolveNodes method 45
saveXML method 45
XFADataModelFactory, instantiating data models 14
XML
attributes 19
element content 17
exporting from XFA 16
leaf elements 17
mixed content 18
null values 19
to XFA 17
XML documents, data model 9, 14
XML files 14
importing data 14
importing selectively 15