Variables can be mapped to a target field in either mapping mode or script mode. When you map a variable, the variable reference is inserted into a script on the target field. Variable references are constructed with a dollar sign (
$) preceding the variable name. For information on creating, configuring, and using variables, see Variables.
A known issue is that the mapping of variables with periods in the variable name doesn't work correctly, resulting in an incorrect target field mapping in the transformation. Until this issue is resolved, rename global variables by replacing any periods with underscores or by removing any periods another way. Because of this issue, at this time Jitterbit variables are unable to be directly referenced within a transformation.
Accessing Variables for Mapping¶
In mapping mode, existing variables are listed by type within the Variables tab on the source side of the transformation:
Within the list, the type of each variable is indicated by the icon next to the name:
- for global variable
- for project variable
- for Jitterbit variable
The icon's background is solid if the variable has a default value, or empty if it does not.
In script mode, existing variables are listed within the Variables tab of the script component palette in sub-tabs for each type:
Both modes have a search box where you can enter a keyword or keywords separated by commas. Variables that have any part of the keywords in their name are returned.
Project, global, and Jitterbit variables are available to use in the transformation:
Project Variables: Project variables that have already been created and are available to use globally within the project. To create or edit a new project variable:
Mapping Mode: To create a new project variable, click Create New Project Variable, or to edit an existing project variable, hover over the variable and click the edit icon .
Script Mode: To create a new project variable, click Add New, or to edit an existing project variable, click the name of the variable.
Global Variables: Global variables that have been defined anywhere in the project.
Global variables should be declared upstream of the transformation to be used within the transformation. If the global variable has not been initialized, the default value for a global variable is empty.
Jitterbit Variables: Jitterbit variables that are available to use globally within the project.
Some Jitterbit variables that are listed may not be applicable to the specific operation. Refer to the documentation on each variable under Jitterbit Variables.
Mapping to a Target Field¶
Variables can be mapped by dragging and dropping, double-clicking, or manually inserting the variable's reference path:
Drag-and-drop: Dragging and dropping variables can be done in mapping mode and script mode:
Mapping mode: Within the Variables tab on the left, drag a variable on the left to an appropriate target field on the right:
Script mode: Within the Variables tab on the right, drag a variable on the right to an appropriate target field on the left:
Double-click: In script mode, double-click the variable in the Variables tab to insert the variable's reference at your cursor's location within the script.
Manual insertion: You can open an editable script area to manually enter variable references from either mapping mode or script mode. To add a new script on a target field, do one of the following:
Double-click the field name.
Hover over the target field and click the add icon in the upper right to open a menu of actions. From the menu select Add Script:
A referenced variable is visually displayed within the mapped target field, with a script icon added in the top right to indicate the field has a mapping:
To view or edit the mapping as a script, double-click the field name or click the script icon to open the editable script area for the target field in script mode:
Mapping to a Field with an Existing Mapping¶
When dragging and dropping a variable to a target field that already has a mapping, you are presented with the option to copy the variable reference to your clipboard so that you can manually paste that reference into the script logic:
On clicking Continue, the target field becomes expanded with an editable script area for you to paste in the variable reference in script mode. For mappings that contain multiple references, you must then add scripting logic to make the script valid. For example:
When adding additional variable references by double-clicking or manual insertion, the dialog for copying a variable reference is not presented. However, you can add multiple variable references into the editable script area by double-clicking, dragging and dropping, or manually inserting the references.
Removing a Mapping¶
You can remove target field mappings one at a time (Remove a Single Field Mapping) or all at once for all field mappings contained within a node (Remove Multiple Field Mappings).
Removing a Single Field Mapping¶
To remove a single variable mapping from a target field (sometimes referred to as unmapping a field), hover over the variable within the target field and click the delete icon :
For mappings with multiple mapped objects or scripts, hover over the variable within the target field and click the edit icon , then edit the script to remove the variable mapping:
The editable script area is also accessible by clicking the script icon on the target field.
Within the editable script area, you can also manually clear the contents of the target field script to remove the entire mapping.
Removing Multiple Field Mappings¶
For mappings on hierarchal schemas, options for removing multiple target field mappings are available within a node's actions menu.
From either mapping mode or script mode, hover over a node name and click the actions menu icon to open the actions menu. From the menu, select one of these mapping removal options:
Remove Loop Node and Mappings removes the loop node definition due to mappings that are direct leaf children associated with the loop node, and removes those mappings.
Any other mappings within child loop nodes beneath the parent loop node are preserved, and the node retains its loop node definition if at least one grandchild is mapped.
This action is available only on nodes that have a loop node defined (either manually or by automatic generation).
Remove All Mappings Beneath This Node removes all mappings on fields contained within the node, as well as all mappings on fields contained within child nodes of that node.
Using this action on a root node removes all mappings in a transformation. On selecting this action, a message asks you to confirm that you want to remove mappings.
Remove All Invalid Mappings removes all invalid mappings on fields contained within the node, as well as all invalid mappings on fields contained within child nodes of that node.
For more information about invalid mappings, see Transformation Mapping Validity.