[JWF][DOC] Data Handling for Workflow Server

Adobe® Workflow Server

Version 6.2

Data Handling for Workflow Server

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

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.

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.

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 48 C .F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software

Documentation,” as such terms are used in 48 C .F.R. §12.212 or 48 C .F.R. §227.7202, as applicable. Consistent with 48

C.F.R. §12.212 or 48 C .F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and

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>

<month>August</mon

th>

</date>

</order>

<date> has no ancestors that

contain character data.

<date> has ancestors that

contain character data.

<order>Internal

<date>

<month>August</mon

th>

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

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

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

datasets

data

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

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

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

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

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 -8’ ;

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 -8” or “ASCII”.

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

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

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

IXFAModel model

nodes

parent

clone

resolveNode

resolveNodes IXFANodeList

IXFANodeList

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

absolute occurrence 21

adding data nodes 13

ancestor nodes

resolving non-unique 25

resolving unique 25

attributes, mapping to XFA 19

changing work item data 12

child nodes, SOM expressions 22

COM objects, XFA data 28

creating XFA data models 14

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

element content, mapping to XFA 17

evaluating SOM expressions 23

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

HTML data model for forms 9

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

JScript extensions, accessing data 8

layered data 20

leaf elements, mapping to XFA 17

loading XML 14

selectively 15

manipulating data 10

mapping XML to XFA 17

mixed-content elements, mapping to XFA 18

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

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

PDF, data model for forms 9

process definitions, retrieving work item data 10

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

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

types of data nodes 16

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

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

秒客网

[JWF][DOC] Data Handling for Workflow Server

相关文章