TeleFlow Step 0393

From TeleFlow

XML Fetch Step
Retrieve a value and/or attribute values from a node of an XML document.

To use this step, you must have loaded an XML document into memory with the XML Load step.

1 Properties
2 Action Steps
3 Example
4 Related Steps

Properties

XML handle: The number of the XML handle to fetch matching nodes from. This number must have been assigned by an XML Load step.

Node: The name of the xml node to retrieve. As XML nodes are hierarchical in nature, the node must be specified in notation that indicates where it is in relation to other nodes in the document. The TeleFlow notation for this follows:

{document node}->{node}->{node}…

or:

{node}->{node}…

where:
{document node} is the XML document node. As all XML documents have a document node, this aspect of referencing the node is optional.

{node} is any XML node that exists in the document. Note that if a node is specified as a "sub-node", it will only be located if it is a sub-node of the node (or nodes) indicated. When running multiple fetches, it is important to know that each node search is run from a position just after the most recently fetched node. Note that a node could be a parent node to the next node, and/or a child node to the previous node. You can specify any number of nodes.

The following are examples of valid XML node specifications
xml doc->employees->emp
employees->emp
employees
PRODUCE->Fruit->Apples
Fruit->Apples
Fruit

Capture value to variable: If the node of an XML document has a value, capture it to the TeleFlow® variable supplied in this field. This is an optional property. If this field is left empty, the value of the node will not be captured. Note that if a variable is specified here, but the node does not have a value the XML Fetch will fail (and take the path specified by the Fail action step).

Attributes: The node attributes to retrieve. Place each node name to retrieve on a single line. TeleFlow® will assign the attribute's value to a TeleFlow® variable with the same name. Optionally, specify the variable to assign the value to with the "as" keyword, for example: "Name as EMP_NAME". Do not include the '@' symbol in the variable name.

Fetch direction: Fetch forward for the next occurrence of a node, or backward for the previous occurrence. Each time an XML Fetch is run for a particular XML handle, it continues from where the last fetch left off. This means that if there are 4 matching nodes, and you start fetching forward, you can run a forward fetch for the handle 4 times before the application flow will follow the Failure/bomb path. This also allows you to go backward and forward through nodes in an XML document. This can be helpful when playing fetched results to a caller one at a time: If the caller is able to go forward and backward to the next and previous results, you can have two different XML Fetches using the same XML Handle, one set with forward fetch direction, the other backward, allowing the caller to "navigate" through the data.

Create variable scope: Indicates how TeleFlow® assigns (or creates) variables to store the node value and attribute values. The default behavior, "Automatic", uses local variables first if they already exist, then uses global variables, and creates any new variables as global variables. "Local" only uses and creates local variables, and "Global" uses and creates only global variables.

Action Steps

Failure: TeleFlow® could not find the XML node requested. This could occur because the node does not exist, or because there are no more instances of the node available to fetch (in the forward direction), or attempted to fetch before the first node (in the backward direction). When a failure occurs, the "search position" in the XML document for the XML handle is either at the beginning (if the Fetch direction was backward), or the end (if the Fetch direction was forward).