Working with captured data

Assessing review and approval results
- Retrieving form data from XMl variables
Using submitted data with Guides or Flex applications and forms
Document attributes for attachments and notes
Adding data nodes to xml variables

This section provides information about how to use XPath expressions to work with task data that is submitted to the LiveCycle Server:

Assessing review and approval results

You can use XPath expressions to assess the results of review and approval processes from Task Result Collection values. Assign Multiple Tasks operations enable you to create routes based on the results of document reviews. However, the XPath expressions are useful for the following situations:

Sequential reviews where a series of Assign Task operations are used, and the results are accumulated in a Task Result Collection value.
When routing decision need to be made sometime after an Assign Multiple Tasks operation.

For example, a succession of users reviewed a document and selected either the Approve or Reject user action. If a majority of reviewers approve, the document is accepted. After the final review, the process sends an email that includes the results of the review to all the participants. XPath expressions are used to determine how many times each action was selected.

Task Result values include the selectedUserAction data item that stores the user action that was used to complete the task. You can apply XPath functions to Task Result Collection values to determine the number of tasks that were completed by using a specific action:

get-list-item-count:

Returns the number of times an action was selected.

get-list-item-percentage:

Returns the percentage of tasks that a specific user action was selected.

These functions require an XPath expression that resolves to the Task Result Collection and the name of the action that you want information for. The following XPath expression returns the number of times the action named Approve was selected. The Assign Multiple Tasks results are stored in a Task Result Collection variable named TRCvar:

get-list-item-count(/process_data/TRCvar/object/taskResults,'Approve','selectedUserAction')

The function call includes selectedUserAction as the property name parameter. This optional parameter is included because the selectedUserAction data item of Task Result values stores the user action that was used.

For Task Result Collection values only, the get-list-item-count and get-list-item-percentage functions enable you to simplify the expression, Specify only the path to the Task Result Collection value, and do not provide a property:

get-list-item-count(/process_data/TRCvar,'Approve')

Retrieving form data from XMl variables

Adobe XML forms and Adobe PDF forms can submit field data in XML data package (XDP) format. XDP.

XPath expressions are used for retrieving and setting form data that is stored in variables. To access the data, you must know how the data in the variables are represented internally.

The following process data model includes an XML variable named xmlVariable.

The root node of the data that is collected from the form is named MortgageApp. The structure of the data below this node represents the form schema. XDP data includes several levels of nodes above the root node of the form data.

The following XPath expression retrieves all of the form data:

/process_data/xmlVariable/xdp/datasets/data

Using submitted data with Guides or Flex applications and forms

A common scenario involves collecting data using a Guide or Flex application, and then displaying the data to a different user in a form. It is also common to populate a Guide or Flex application with data that was submitted with a form.

Guides, flex applications and forms use XML data. Forms that are created using Designer require the XML to be in XDP format. However, Guide and Flex application data do not include the XDP-specific elements:

To populate a form with the data that is submitted from a Guide or Flex application, you need to save the data in an XML variable that is configured to store data as XDP. (See Configuring XML variables for XDP data.)
To populate a Guide or Flex application with data that is submitted from a form, you need to remove the XDP-specific elements from the XML. Use the Set Value service to extract the field data and save it in another xml variable. Using the example XML data from Retrieving form data from XMl variables, the following Set Value mapping copies the field data from xmlVariable to xmlGuide, another xml variable:
```
/process_data/xmlGuide = /process_data/xmlVariable/xdp/datasets/data/*
```

Document attributes for attachments and notes

When a file or note is attached to a task, a document value is created to represent the attachment or note. Several attributes are created for the document values that are used to store information about the attachment or note.

Attribute name	Description	Default
wsfilename	The filename of the attached document or the title of the note that the document represents. The value can be the path to the file location and the filename, or just the filename.	`Attach` `number`, where `number` is the index that indicates the location of the document in a list variable used for storing the attachments and notes.
wsdescription	The description of the attachment or the note text	Empty string
wscreatorid	The user ID of the user who attached the document or provided a note to the task	Unique string that represents the user’s identification
wspermission	A bit mask number that represents the access permissions for the document. Access permissions determine how the document can be used when it is attached to a task. The value of the number is the sum of the number that represents each access permission provided for the document. `Read access:` 1 `Write access:` 2 `Delete access:` 4 Valid values are 1, 3, 5, and 7. For example, the value of `wspermission` for a document with read and write access is 3.	`7` (Read, write, and delete access)
wsattachtype	A `string` value that indicates whether the document represents an attachment or note: The value `attachment` indicates a binary file attachment. The value `note` indicates a note in text format.	The attachment type always determines the value.

You can use XPath expressions to retrieve or set the value of the attributes. (See getDocAttribute and setDocAttribute.)

For example, the notes and attachments of a task are saved in a list variable named attachmentVar. The following XPath expressions evaluate to the name, description, creator ID, and permission of the first attachment in the list:

getDocAttribute(/process_data/attachmentVar[1],"wsfilename") 
getDocAttribute(/process_data/attachmentVar[1],"wsdescription") 
getDocAttribute(/process_data/attachmentVar[1],"wscreatorid") 
getDocAttribute(/process_data/attachmentVar[1],"wspermission")

The following XPath expressions replace the values of the name, description, creator ID, and permission for the first attachment in the list:

setDocAttribute(/process_data/attachmentVar[1],"wsfilename", "BetterByAdobeRules.pdf") 
setDocAttribute(/process_data/attachmentVar[1],"wsdescription", "desc") 
setDocAttribute(/process_data/attachmentVar[1],"wscreatorid","00ECB211-F3A1-D93E-0EBE-EB13811A1C25") 
setDocAttribute(/process_data/attachmentVar[1],"wspermission", "1")

Adding data nodes to xml variables

You can add nodes to the data tree of xml variables and use them to store information during process execution.

Note: The added nodes do not appear in the data tree in XPath Builder.

Add nodes by using XPath expressions. When you use an expression that searches for a node that does not exist, LiveCycle creates the node when it evaluates the expression. After the node is created, you can use it the same way you use any other node in the tree.

The following rules apply when adding nodes:

You can add nodes only beneath the form’s schema root node.
Use the fully qualified path to the node.

For example, the following data tree is for a process that includes an XML variable named xmlLoanForm. The root element of the form schema is named MortgageSchema.

View full size graphic

The following expression adds a node named newNode to the schema:

/process_data/xmlLoanForm/xdp/datasets/data/MortgageSchema/newNode