Nodes and fields in Jitterbit Integration Studio

Introduction

Nodes and fields are contained within the schemas that are specified either during activity configuration or in the transformation. While configuring a transformation, nodes and fields are displayed the same regardless of the transformation display mode.

Node and field notation

Each node or field is displayed with these components:

Cardinality key for nodes and fields
Name for nodes and fields
Data type for fields only
Attribute and value indicators (if applicable)

For example, the field below has a cardinality key of [0, 1], a name of id, and a data type of string:

source field notation

Cardinality key

Cardinality keys notate the relationship for nodes and (if the key is present) fields. The notation is derived from the concept of multiplicity as used in Unified Modeling Language (UML).

Cardinality Key	Usage	Definition
`[1]`	Nodes only	One and only one element is valid.
`[1+]`	Nodes only	One or more than one element is valid.
`[0,1]`	Nodes or fields	Zero or one element, value, or attribute is valid. This key means that a given node or field is effectively optional.
`[0+]`	Nodes only	Zero or more elements is valid.

Name

Each node or field has a name that comes directly from the data schema.

Data type

Each field has an associated data type, such as integer, float, double, long, string, boolean, or binary.

Attribute and value indicators

Some types of structures, such as XML, SOAP, or JSON, may have additional symbols that represent whether a field is a value or an attribute. Elements, represented by nodes, do not have any visual indicators. Elements may have one or more other elements, attributes, values, a combination of these, or none depending on the cardinality key.

Visual Indicator	Definition
@	Attribute as represented by a field. This field is used to indicate a node has an attribute, and may or may not also have a value. There may also be more than one attribute for each node.
#	Value as represented by a field. The field is used to indicate a node has a value and zero or more attributes.

XML example

The following is an XML structure that includes text and attributes in its elements:

Source XML

    <?xml version="1.0" encoding="UTF-8" ?>
    <catalog>
      <product description="Cardigan Sweater" product_image="cardigan.jpg">
        <catalog_item>
          <item_number>EX123</item_number>
          <price>49.99</price>
          <size description="Small">
            <color_swatch image="red_cardigan.jpg">Red</color_swatch>
            <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
            <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
          </size>
          <size description="Medium">
            <color_swatch image="red_cardigan.jpg">Red</color_swatch>
            <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
            <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
            <color_swatch image="black_cardigan.jpg">Black</color_swatch>
          </size>
          <size description="Large">
            <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
            <color_swatch image="black_cardigan.jpg">Black</color_swatch>
            <color_swatch>Custom</color_swatch>
          </size>
          <size description="Custom">
          </size>
        </catalog_item>
      </product>
    </catalog>

Shown is a color_swatch node with a required text value field (#) and an optional image attribute field (@) based on the structure:

target field value attribute

JSON example

The following is a JSON structure that includes a value property that can contain text or an object depending on the item:

Source JSON

{
  "sections": [
    {
      "fields": [
        {
          "__self__": "/api/v3/workspaces/items/TEXT_VALUE",
          "title": "Text value",
          "value": "Text",
          "defaultValue": ""
        },
        {
          "__self__": "/api/v3/workspaces/items/NESTED_OBJECT_VALUE",
          "title": "Nested object value",
          "value": {
            "title": "Nested object title"
          },
          "defaultValue": {
            "title": "Default nested title"
          }
        }
      ]
    }
  ]
}

Shown is value node with a text value field (#) and title field to support expected objects based on the structure:

target field nested object

If used as part of a source schema, a script can set a target value to the correct representation of value depending on the item:

<trans>
IfEmpty(json$sections$item.fields$item.value$title$, json$sections$item.fields$item.value$)
// Check to see if value is a nested object and use its title if so, otherwise use value as a text value.
</trans>

Reference path notation

When a source object is mapped, its individual reference path is inserted into a script on the target field. In most use cases, as these paths are automatically constructed, it is not necessary to know how to manually construct them. This information is provided as a reference to aid in understanding how these paths are constructed.

There are cases where you will need to understand how these paths are constructed, such as in the use of reference paths with Instance functions. In cases where a required input parameter for an instance function is an array, a hash symbol (#) can be inserted in the reference path of a data element to return an array of data as opposed to a single field. For more information, see Insertion of a hash to return an array under Instance functions.

For reference, the syntax used for the path of the object uses these symbols:

Category	Symbol	Meaning
Paths	`[ ]`	Square brackets are used to enclose a node path.
Paths		A path without square brackets is a value or attribute field.
Separators	`.`	A period following a node name indicates it is a loop node.
Separators	`$`	A dollar sign following a node name is used to indicate a `Once Only` or `[E]` element. This node cannot be a loop node.
Loop Nodes	`#.`	A hash sign-period following a node name indicates that an array for the record value fields will be returned. This notation can be used only on loop node names.
Loop Nodes	`#<n>.`	A hash sign followed by an integer returns the one-based index item of an array.
Complex CSV Structures	`_`	An underscore preceding `Root` is used to reference the root in a complex CSV. This is not present for other data structures. An underscore may also simply be an underscore already present in a node or field name.

As an example, the following table has sample paths for a complex CSV data structure. The paths for other structures follow the same format except that _Root is not present for other data structures.

Node paths are shown with a blue background, while the rest are field paths. A source can be mapped to an attribute or value field of a target. Though target nodes can have conditions applied on them, sources cannot map to them. Source node and field paths can be used in target node conditions and target field mappings.

Data Structure	Qualified Path	Meaning
`_Root` (Once Only)	`[_Root$]`	The `_Root` in a CSV data structure is always a node, and thus appears within brackets `[ ]`. The ending dollar sign indicates a `Once Only` element.
`Header` (Once Only) `[E]`	`[_Root$Header$]`	Sub-nodes use the reference of any preceding nodes, followed by the node name. The ending dollar sign indicates a `Once Only` or `[E]` element.
`Value [V]`	`_Root$Header$Value`	A value field is not enclosed within square brackets, but still uses the reference of any preceding nodes, followed by the value name.
`Detail` (One or More)	`[_Root$Header$Detail.]`	Sub-nodes use the reference of any preceding nodes, followed by the node name. The ending period indicates a loop node.
`Attribute` [A]	`_Root$Header$Detail.Attribute`	An attribute field is not enclosed within square brackets, but still uses the reference of any preceding nodes, followed by the attribute name.
`Value` [V]	`_Root$Header$Detail#.Value`	A value field is not enclosed within square brackets, but still uses the reference of any preceding nodes, followed by the value name. This specific example shows a hash sign preceding the loop node period, indicating that an array of the "Detail" record values will be returned.
`Value` [V]	`_Root$Header$Detail#1.Value`	A value field is not enclosed within square brackets, but still uses the reference of any preceding nodes, followed by the value name. This specific example shows an indexed hash sign preceding the loop node period, indicating that the first element of an array of the "Detail" record values will be returned.

For additional information about data structures, mapped fields, loop nodes, and instance and multiple mapping, see Data structures.