General tab

The XML node main properties control the overall behavior of the node and also specify the XML Schema and element to be used in the XML Builder Wizard and XML Output Wizard. Most of the main properties are on the "General" tab.

XML Builder/Parser section

The XML Builder/Parser is built into the XML node properties dialog box, appearing in the main tab labeled "General". The XML Builder is a tool that simplifies the task of building or parsing an E4X XML object based on an XML Schema (XSD).

Property What it means
Action

The Action menu controls whether the node will build or parse XML. When Action is Build, the XML Builder will display the structure of the XML to build. When Action is Parse, the XML Builder only shows a field where you specify what input source is to be parsed. For parsing XML, the information in the Output view is more relevant than the XML Builder view. More details on how the node builds or parses XML is available.

The usage of the E4X XML string is different depending on whether Build or Parse is selected for the activity’s Action field.

Build XML Object

In Build mode, this field holds the E4X XML expression that is evaluated when the XML activity node runs. A simpler way of thinking of it is that this text is the XML that is built. However, as this is actually an E4X JavaScript expression, the XML can contain JavaScript expressions contained in curly braces ({}).

At design time, the XML Builder Wizard parses this string according to a specified schema and helps you build or modify this string. When you make changes in the XML Builder Wizard view, they are reflected in the Input E4X String, and vice versa. It is always better to edit this string using the XML Builder Wizard rather than to edit this string directly, as it is easy to introduce errors in the string when editing it by hand.

At runtime, this string is evaluated as the right-hand side of a JavaScript expression. Since this is an E4X string, JavaScript expressions in curly braces are evaluated and placed in the resulting XML object, according to the rules established by E4X. This is how the server variables are substituted in the XML. Complex element contents may also be built using JavaScript expressions. Information on how the node behaves at runtime is in a later section.

In "build" mode, the "Value" column holds the value of the node just like the Input tab. This column is not editable.

Parse XML Object

In "parse" mode, the input E4X string holds a single JavaScript expression that will be evaluated at runtime and parsed into an E4X XML object. This is usually used to specify a single string or variable to parse into XML.

In "parse" mode, the "Variable" column is used to supply variables that will be assigned the value from the node when the XML is parsed. Variables have the following properties:

  • The variable name can be specified with or without the E4X curly braces. Both of the following are acceptable:

    a

    {a}

  • The variable name does not need to be defined previously. If it is defined, then the variable will be updated.

    If the variable is not previously defined, it will be defined as a local variable and the value will be set from the node.

  • If the variable is defined as String, but the schema node property specifies "maxoccurs = unbounded" and there are multiple occurrences of the node in the parsed XML, the variable will be converted into an XML list, which is similar to an array.

    Example: Parsed XML:

    <foo>
        <bar>baz 1</bar>
        <bar>baz 2</bar>
    </foo>
    

    The variable "baz" is defined as String in the Start node. When above XML is parsed, the variable "baz" will be converted to an XML list. If you need to extract the values inside each element, you will need to iterate through the "baz" XML list, which can be done using a JavaScript expression in an Assign node.

    If there is one occurrence of the node in the parsed XML, the variable will be left as String.

Evaluate on condition

You can select this option and supply a condition (for example, item_count > 100 && po_app != "Manager").

If the condition is matched, then it builds the XML as usual. In the case where the condition is not matched, the XML content will not build, that is, that the output XML will be set to null. In addition, if "Append output to" is selected and the condition is not matched, then nothing gets appended.

Append output to

This option allows constructed or parsed XML output to be appended to an existing E4X XML output variable (which will usually be from a previous XML activity node). The XML object is appended using E4X rules, which are described in another section.

For example, SyncSupplierInvoiceBOD_output.*::DataArea.*::SupplierInvoice[invoiceCount].*::SupplierInvoiceHeader.*::ContractReference. In this case, the XML built by the XML activity will be appended to XML node.

The option also provides a drop-down list of previous activity output variables that match the selected schema and root element for the node.

Preserve white spaces in XML Select this check box if you want to preserve white spaces in the XML.
Do not parse variables in XML Select this check box if you do not want to parse variables in the XML.

E4X XML Builder dialog box

The XML Builder is a tool that simplifies the task of building an E4X XML object based on an XML Schema (XSD). The E4X XML Builder dialog box appears when you click the Build button.

Changes made in the XML Builder are reflected in the E4X XML string in the Input tab.

The Output tab shows the XML object output that is expected from the activity. This information is based on the selected root element of the XML Schema. The Output tab shows the output that may occur; the actual output is known only at runtime.

Property What it means
Schema URL

The Schema URL text field is used to select the XML Schema (XSD) file to be used in the XML Builder and XML Output wizards. The URL can point to a local file or a web address. WSDL files with schema definitions are accepted in addition to XSD files.

The popup menu for the Schema URL field holds a list of previously loaded XSD or WSDL files.

Using an XML Schema is not absolutely required. The Schema is used by the XML Builder wizard to help you create an E4X XML string, and to show the expected output in the Output wizard. Without a schema, you cannot use the XML Builder or XML Output wizards, but you can still edit the E4X XML string by hand, and you can hand-code output variable references in the process. Both of the latter are tedious and error-prone, however, so it is highly recommended that you supply an XML Schema for the XML you wish to build or parse and use the XML Builder and XML Output wizards.

Load Use the Load button to load a schema after specifying in the URL in the Schema URL field.
File The File… button can be used to select a local file using a file dialog.
Global Element The Global Element popup menu is used to select which global element of the XML schema is used as the root XML element. If Action is Build, this element will be the root element in the XML Builder view and in the Output view. If Action is Parse, this is the root element expected to be parsed. When a schema is loaded, the global element with the deepest content is automatically selected. However, the user may want to use a different global element, for example in order to construct XML in separate, smaller pieces.
Child Element The Child Element field may specify a descendant element of a global element to be used as the root element for building or parsing XML. This field is set by selecting an element node in the XML Builder view and clicking the "Make Root" button. This feature allows any element node to be used as a root node, not only elements that are defined globally in the schema.

The table below lists the different options that go with the Input tab:

Property What it means
XML Builder Tree

The XML Builder tree view shows the structure of the selected XML element of the selected schema. Nodes in the XML structure can be added or their contents edited based on the schema to construct the XML object.

When an XML Schema is opened in the XML Builder view, the XML Builder reads the entire schema definition, including any schema files that are referenced by the main schema file by XSD import or include statements. The XML Builder view shows the entire structure of the selected element, saving you the task of looking through possibly many separate definition files to understand an XML schema’s structure. The Description field displays, among other things, the schema source file from which the definition for the selected node came.

XML Builder Tree (continued)

Nodes displayed in the XML Builder view include elements and attributes, and also XML Schema nodes such as "sequence," "choice," "all" and "any." Element nodes in the tree show simply the element tag name, while other node types show the node type. For example, "attribute validFrom" represents an attribute node with the name "validFrom."

When a node is selected, the Description and Value fields and the editing buttons on the right are updated based on the selected node. Explanations of the Description and Value fields and the editing buttons appear later in this table.

The XML Builder view shows the structure of the schema, including elements that can be used but have not yet been added. Nodes that have not yet been added are called "placeholder"’ nodes in the XML Builder Wizard; they are shown in the tree view using parenthesis. For example, "(attribute lang)" indicates an attribute named ‘lang’ that can be used in the XML at that position but which has not been added to the XML yet.

As the XML Builder view is based on the XML Schema, the view only shows the XML structure when a valid XML Schema is specified in the Schema URL field. The E4X input string is not updated from the XML Builder view when there is not a valid schema selected.

XML column

This column contains check boxes that represent each XML element. When a check box is selected, the XML element becomes an XML fragment, that is, the value specified for the element becomes an XML fragment for that element. The elements and attributes for the element are pulled from the fragment.

When a check box is selected, the elements and attributes for the XML are disabled.

Node Value

The node’s text value, if any, appears in the Value field. The popup menu for the Value field contains a list of variables that can be used in the field, using E4X curly-brace notation, described below.

The value field holds the text value for an element, attribute, or "any" node. Attribute values must be surrounded by quotation marks or E4X curly braces ({}). Element values must follow the rules for XML element values. If content that is not allowed in an XML element is used, a warning dialog will be displayed and the entire content will be wrapped in an XML CDATA section.

If the node value is edited while a placeholder node is selected, the placeholder node will be instantiated (added), along with any placeholder nodes that enclose the selected node.

Node Description The Description field shows information about the node selected, including the nodes name, how many times the node can occur in the XML, the node’s type, any restrictions on content, and the source schema file for the node definition.
Show all schema nodes The Show All Sequences check box controls whether certain sequence nodes are displayed in the XML Builder view. When Show All Sequences is unchecked (the default), sequence nodes which are children of an element node and which have minOccurs=1 and maxOccurs=1 are not displayed, to cut down on clutter in the XML Builder view. If Show All Sequences is checked, all schema nodes are displayed. The behavior of the activity at runtime is the same whether Show All Sequences is checked or not.
Hide Empty Assignments

Select this check box if you want to hide nodes that do not have assigned values.

Expand All The Expand All button expands all nodes under the selected node so that they are visible, not hidden.
Collapse All The Collapse All button collapses all nodes under the selected node so that they are not visible.
Make Root The Make Root button makes the currently selected node the root node for building or parsing XML. The Global Element and Child Element fields are updated accordingly. If a child element has already been made the root node, this button displays "Original Root" and will restore the root element to the selected Global Element, clearing the Child Element field.
Add Node If the schema allows an instance to be added, the Add Node button adds an instance of the currently selected node. If the selected node is a placeholder node, it will be instantiated, along with any placeholder nodes that enclose the selected node.
Delete Node The Delete Node button deletes the currently selected node. If the node should not be deleted according to the schema, the XML Builder will display a warning dialog. The node can still be deleted even if the schema says it should be present, as XML can be built in multiple activities and combined later.
Move Up The Move Up button moves up the currently selected node. This command only works on instances of elements or nodes that occur more than once; it is only enabled when an array instance node is selected.
Move Down The Move Down button moves down the currently selected node. This command only works on instances of elements or nodes that occur more than once; it is only enabled when an array instance node is selected.
Find The Find… button can be used to search for an element or node name containing search text.
Find Next The Find Next button finds the next instance of a node matching the criteria previously given using the Find… command.

The table below lists the different options that go with the Output tab:

Property What it means
XML Output Tree View The XML Output tree view shows the structure of the selected XML element of the selected schema.
Node Description The Description field shows information about the selected output XML element or node. The first line of the description shows a JavaScript expression that could be used to access the XML element’s content. This JavaScript expression is a template or starting point for accessing the information; array subscripts in the expression must be filled in by the user.
Show All Sequences The Show All Sequences check box controls whether certain sequence nodes are displayed in the XML Builder view. When Show All Sequences is unchecked (the default), sequence nodes which are children of an element node and which have minOccurs=1 and maxOccurs=1 are not displayed, to cut down on clutter in the XML Builder view. If Show All Sequences is checked, all schema nodes are displayed. The behavior of the activity at runtime is the same whether Show All Sequences is checked or not.
Expand All The Expand All button expands all nodes under the selected node so that they are visible, not hidden.
Collapse All The Collapse All button collapses all nodes under the selected node so that they are not visible.
Find The Find… button can be used to search for an element or node name containing search text.
Find Next The Find Next button finds the next instance of a node matching the criteria previously given using the Find… command.