Jitterbit Success Central will be undergoing system maintenance and may be inaccessible starting at this time: November 30 7:00 am PST; 30 November 15:00 UTC; 1 December 2:00 am AEDT.

Skip to end of metadata
Go to start of metadata

Introduction

Project variables are one of the types of global data elements available in Jitterbit Harmony. The other types of global data elements — global variables, Jitterbit variables, and filename keywords — are also available globally throughout a project. They are set differently, as described in Global VariablesJitterbit Variables, and Filename Keywords, respectively. However, as all global data elements share the same namespace, their names must be unique when compared against all other global data elements.

Project variables are set before runtime of an operation and become available to use across all workflows in a project, for example within scripts and transformations, or in endpoints created using connectors. Common uses of project variables include for endpoint credentials, filenames, or variables that can change from environment to environment, or any variable that you want to be able to edit through the Management Console or Citizen Integrator.

When deploying a project variable that has already been deployed in the Harmony cloud, you are presented with options for selecting which project variable values to use. This is covered under Selecting Schedules and Project Variables in Project Deployment.

Display of Project Variables

Defined project variables are displayed in several places:

  • In the project pane, project variables are displayed in the Components tab in the Project Variables category. From here you can see if the project variable is referenced elsewhere in the project and view dependencies.
  • In the script editor, project variables are displayed in the component palette on the right, within the Variables tab, in the Project Variables sub-tab. This location provides easy access for inserting project variable references in scripts, including within transformation scripts in script mode.
  • In transformation mapping mode, project variables are displayed within the Variables tab on the left, in the Project Variables category. This location provides easy access for inserting project variable references during transformation mapping in mapping mode.
  • In endpoint configurations, project variables can be accessed and used in any fields that have a variable icon . As an alternative to selecting a project variable, you can manually enter the variable reference using the standard Jitterbit Script square bracket syntax.

Creating and Updating Project Variables

You create and update project variables from within Cloud Studio, as well as update existing project variables of a deployed project from the Management Console and Citizen Integrator.

These next sections describe how to create a new project variable from different locations in Cloud Studio: 

Once a new project variable has been created, you configure it — depending on how it was created — either in list view or individually, as described below in Configuring a Project Variable.

Project Variable List

The project variable list screen is a complete list of the project variables created for a project. It includes controls to create new project variables and to edit and delete existing project variables.

You can access the project variables list screen both from outside and within a project. It is not necessary to open a project in order to access the project variable list.

  • From outside of a project, this can be done from the project index in either card view or list view:
    • Card View: Hover over the project card to reveal the back of the card, click the actions menu icon , and from the menu select Project Variables.
    • List View: Hover over the project row to reveal actions in the last column, click the actions menu icon , and from the menu select Project Variables.
  • From within the project, click the actions menu icon  at the top of the project pane, and from the menu select Project Variables.

The project variable list view is displayed:

To create a new project variable, click New Variable:

To edit an existing project variable, click within the fields of the project variable table and edit the values inline.

Additional information about searching for, deleting, and configuring project variables from this view is provided in Configuring Project Variables in List View later on this page.

Project Pane

To create a new project variable from the project pane, in the Components tab, hover over the category Project Variables and click the actions menu icon  to open the actions menu. From the menu, select Create New:

To edit an existing project variable from the project pane, in the Components tab, hover over the project variable name and click the actions menu icon  to open the actions menu. From the menu, select View/Edit.

Both of these menu options open the individual project variable configuration screen, as covered under Configuring a Project Variable Individually later on this page.

Additional menu actions are covered under Project Variable Actions Menu later on this page.

Script Editor

From the script editor, open the Variables tab of the component palette:

Then go to the Project Variables sub-tab.

  • To create a new project variable, click Add New:

  • To edit an existing project variable, hover over the variable name to view additional information and click anywhere on the project variable name or the information popup:

Both of these actions open the individual project variable configuration screen, as covered under Configuring a Project Variable Individually later on this page.

Transformation Mapping Mode

From transformation mapping mode, open the Variables tab on the left and expand the Project Variables category:

  • To create a new project variable, click Create New Project Variable:

  • To search for a particular variable by name, click the search icon  and enter a keyword or multiple keywords separated by commas in the search box. The search returns a list of variables having any of the keywords.
  • To edit an existing project variable, hover over the variable name and click the edit icon :

Both the actions of creating a new project variable and editing an existing project variable open the individual project variable configuration screen, as covered under Configuring a Project Variable Individually later on this page.

Endpoint Configurations

While using a connector to configure an endpoint, in fields that have a variable icon , click the icon to display a list of existing variables. To create a new project variable, click Add in the lower right corner:

  • To edit an existing project variable from this list, hover over the project variable row and click the edit icon  on the far right.
  • When an existing project variable has already been used within a configuration field, hover over the variable pill to view information about the variable, then click the edit icon or Edit in the lower left:

All of these actions open the individual project variable configuration screen, as covered under Configuring a Project Variable Individually later on this page.

Existing Project Variable Configurations

In an individual project variable configuration screen, you can save the current project variable and then enter a new configuration screen to create a new project variable. This feature is useful when creating project variables in bulk.

Within a new project variable configuration screen, configure the variable as described under Configuring a Project Variable Individually later on this page, and then click Save & New:

This saves the current project variable and opens another individual project variable configuration screen for creating a new project variable.

Project Variable Actions Menu

After a project variable is created, menu actions for that project variable are accessible from the project pane. In the Components tab of the project pane, hover over a project variable name and click the actions menu icon  to open the actions menu.

Each of these menu actions is available:

  • View/Edit: Opens the individual project variable configuration screen for you to configure the project variable. For details, see Configuring a Project Variable Individually later on this page.
  • Delete: Permanently deletes the project variable (see Component Dependencies, Deletion, and Removal).
  • Rename: Positions the cursor on the component name in the project pane for you to make any edits as necessary.
  • View Dependencies: Changes the view in the project pane to display any other parts of the project that the project variable is dependent on (see Component Dependencies, Deletion, and Removal).
  • Deploy: Deploys the project variable and any components it is dependent on (see Component Deployment).
  • Configurable Deploy: Opens the deployment screen, where you can select project components to deploy (see Component Deployment).
  • Add to Group: Opens a prompt to create a new custom group or to add the component to an existing group. Custom groups are an organizational tool to help organize a project (see Component Groups).
  • Duplicate: Creates a copy of the project variable as a new, unreferenced component. After creating the component copy, the cursor is positioned on the component name within the project pane for you to rename the component.

Configuring a Project Variable

Once a project variable is created, it is configured in one of two ways:

The list view is used if you are creating or editing project variables from outside the project in the project index or if you select Project Variables from the project actions menu. Otherwise, project variables are configured individually.

Configuring Project Variables in List View

Configuring a project variable in the list view is one of two views used for configuring project variables. (The other view is used when configuring an individual project variable, covered under Configuring a Project Variable Individually.)

You can access the project variables list screen both from outside and within a project. It is not necessary to open a project in order to access the project variable list.

  • From outside of a project, this can be done from the project index in either card view or list view:
    • Card View: Hover over the project card to reveal the back of the card, click the actions menu icon , and from the menu select Project Variables.
    • List View: Hover over the project row to reveal actions in the rightmost column, click the actions menu icon , and from the menu select Project Variables.
  • From within the project, click the actions menu icon  at the top of the project pane, and from the menu select Project Variables.

The project variable list view is displayed:

New project variables are created by clicking New Variable:

This adds a new project variable row to the top of the project variable table. If the table already contains project variables, you can add a new project variable row at the bottom of the table by placing the cursor in the last row's variable Description field and then pressing the Tab key.

With either method of creating a new project variable, the cursor is placed in the Name field for you to rename the project variable:

CAUTION: As all global data elements (global variables, project variables, and Jitterbit variables) share the same namespace, their names must be unique when compared against all other global data elements.

Once you focus out of the fields of the new project variable, the project variable is saved and the New Variable button again becomes active for you to create additional variables. You can change the sort order can be changed by clicking the column header for Name, Default Value, Label, or Description.

Project variables can be configured by clicking or tabbing to each field within the table and editing it inline.

For new project variables, the configuration is saved when you shift focus out of the new project variable row. For existing project variables, the configuration is saved each time you change focus to another field, even within the same project variable row.

To search for a project variable by its Name or Description, enter a single keyword or keyword string into the search box.

Project Variable Table Columns

Each column of the project variable table is described below:

  • Select: The column on the far left can be used to select one, multiple, or all project variables for deletion. After at least one project variable is selected, the Delete Variable(s) button at the top of the table is available for you to permanently delete the project variable (see Component Dependencies, Deletion, and Removal).
  • Name: Enter the name of the project variable. The project variable name must be unique within the project, must not contain spaces, and can be composed from these characters: letters (a-z, A-Z), numbers (0-9), periods, and underscores. Other characters are not recommended and may cause issues. Project variable names are case-insensitive; for example, a variable called ProjectVar is treated the same as projectvar.

    TIP: When creating new project variables, it is a best practice to prefix project variables so that they are easy to look up later. For example, a project variable org.netsuite.auth.username is first prefixed with org, then netsuite, etc. to effectively organize it in a list among other project variables.

    CAUTION: As all global data elements (global variables, project variables, and Jitterbit variables) share the same namespace, their names must be unique when compared against all other global data elements.

    WARNING: If you plan to use the project variables in JavaScript later, we recommend using underscores instead of periods. More information is provided below in Retrieving Project Variables in Scripts or Transformations.
    NOTE: An existing global variable can be converted into a project variable by entering its name into the Name field. See Converting a Global Variable to a Project Variable for details.
  • Default Value: Enter an optional default value to be used as the initial value for the project variable. This value can be modified later through scripting. If you do not want the project variable to have a default value, leave this field blank.
  • Hide Value: Use the slider to toggle on the Hide Value option. Enabling this option hides the default value by replacing it with asterisks in various places throughout the user interface. You may want to use this if the value contains sensitive information that you do not want to be visible on the screen. After enabling this option, you are prompted to confirm that you want to hide the value:

    WARNING: Hiding the value does not prevent the value from being accessible in a script.

    CAUTION: When you use this option, the value cannot be unhidden later.

    If you disable this option after enabling it, you are prompted to confirm that you want to remove the current value (as a previously hidden value cannot be unhidden):

    After clicking Continue, the cursor is positioned in an empty Default Value field.

  • Label: Enter an optional label to describe the variable. This label appears when you hover over the variable in scripts and in configuration screens.
  • Description: Enter an optional description to provide further details about the variable. This description appears when you hover over the variable in scripts and in configuration screens.

Configuring a Project Variable Individually

Configuring a project variable in a dialog is one of two views used for configuring project variables. (The other view is the project variable list view, covered under Configuring Project Variables in List View.)

This view is used when you create or edit a project variable directly from the project pane, inside a script or transformation, or inside an endpoint configuration screen.

When you create a new or edit an existing project variable individually, the View/Edit Project Variable dialog is displayed:

  • Project Variable Name: Enter the name of the project variable that you want to declare. The project variable name must be unique within the project, must not contain spaces, and can be composed from these characters: letters (a-z, A-Z), numbers (0-9), periods, and underscores. Other characters are not recommended and may cause issues. Project variable names are case-insensitive; for example, a variable called ProjectVar is treated the same as projectvar.

    TIP: When creating new project variables, it is a best practice to prefix project variables so that they are easy to look up later. For example, a project variable org.netsuite.auth.username is first prefixed with org, then netsuite, etc. to effectively organize it in a list among other project variables.

    CAUTION: As all global data elements (global variables, project variables, and Jitterbit variables) share the same namespace, their names must be unique when compared against all other global data elements.

    WARNING: If you plan to use the project variables in JavaScript later, we recommend using underscores instead of periods. More information is provided below in Retrieving Project Variables in Scripts or Transformations.
    NOTE: An existing global variable can be converted into a project variable by entering its name into the Name field. See Converting a Global Variable to a Project Variable for details.
  • Default Value: Enter an optional default value to be used as the initial value for the project variable. This value can be modified later through scripting. If you do not want the project variable to have a default value, leave this field blank.

  • Hide Value in UI: Use the slider to toggle on the Hide Value option. Enabling this option hides the default value by replacing it with asterisks in various places throughout the user interface. You may want to use this if the value contains sensitive information that you do not want to be visible on the screen. After enabling this option, you are prompted to confirm that you want to hide the value:

    WARNING: Hiding the value does not prevent the value from being accessible in a script.

    CAUTION: When you use this option, the value cannot be unhidden later.

    If you disable this option after enabling it, you are prompted to confirm that you want to remove the current value (as a previously hidden value cannot be unhidden):

    After clicking Continue, the cursor is positioned in an empty Default Value field.

  • Label: Enter an optional label to describe the variable. This label appears when you hover over the variable in scripts and in configuration screens.
  • Description: Enter an optional description to provide further details about the variable. This description appears when you hover over the variable in scripts and in configuration screens.
  • Save: Click to save and close the project variable configuration.
  • Save & New: Present only when creating a new project variable, this button may be useful for creating project variables in bulk. Click this button to save the current project variable and open another project variable configuration screen for creating a new project variable.
  • Delete: After opening an existing project variable, click to permanently delete the project variable and close the configuration (see Component Dependencies, Deletion, and Removal).

Retrieving Project Variables in Scripts or Transformations

In Cloud Studio, the value of a project variable can be returned using either Jitterbit Script in scripts or transformations, or using JavaScript only in scripts created as a project component.

Jitterbit Script

In scripts and transformations, you can begin with a dollar sign $ or use the Get() function to retrieve the value of a project variable.

  • $Prefixed with a dollar sign $, the code example $org.netsuite.auth.username retrieves the value of the project variable called "org.netsuite.auth.username".
  • Get: Using the Get() function, the code example Get("org.netsuite.auth.username") returns the same value.

In scripts and transformations, existing project variables are displayed in the Variables tab of the script component palette inside the Project Variables sub-tab. See Adding a Project Variable to a Script below.

JavaScript

In JavaScript used within scripts within an operation, the syntax used for retrieving the value of a project variable depends on whether the project variable name contains a period.

  • Name does not include a period (recommended): The value of a project variable that does not contain any periods in its name can be retrieved by prefixing with a dollar sign $.
    • $: Prefixed with a dollar sign $, the code example $org_netsuite_auth_username retrieves the value of the project variable called "org_netsuite_auth_username".
  • Name with periods (recommended only for Jitterbit variables and JavaScript object values)A variable that contains a period in its name can be updated or retrieved in JavaScript only with the Jitterbit.SetVar and Jitterbit.GetVar functions. As these functions are not intended for user-defined project variables, see the section on Jitterbit variables for more information.

In scripts and transformations, existing project variables are displayed in the Variables tab of the script component palette inside the Project Variables sub-tab. See Adding a Project Variable to a Script below.

WARNING: The JavaScript Jitterbit.SetVar and Jitterbit.GetVar functions are designed specifically to access the predefined Jitterbit variables. They are not to be used to access user-defined project variables.

In JavaScript, do not mix and match your usage of SetVar (and GetVar) with $-prefixing when setting (and retrieving) a variable. Use only one syntax. Mixing the two different syntaxes for the same variable can cause issues at runtime.

If a JavaScript fails, any changes made to the value of a project variable are lost. Only if the JavaScript successfully completes are modified project variable values available outside the script.

Adding a Project Variable to a Script

In either Jitterbit Script or JavaScript used within scripts created within an operation, existing project variables are displayed in the Variables tab of the component palette inside the Project Variables sub-tab:

Add a variable to a script using one of these methods:

  • Drag the variable from the palette to the script. The appropriate syntax for the script language is inserted.
  • Begin typing the variable name and then press Control+Space to display a list of autocomplete suggestions. Select a variable to insert the appropriate script language syntax.
  • Manually enter the appropriate syntax for Jitterbit Script for JavaScript.

Using Project Variables in Configuration Screens

During configuration of certain project components, including endpoint configuration using connectors, you can use project variables in any fields that have a variable icon . Variables can be used in fields along with other input, including with other variables or keywords. These actions are covered below:

Selecting a Project Variable

To access project variables, you can either click the variable icon  or enter an open square bracket [ to display a list of variables and keywords (if available for the current field).

Within the list, the variable or keyword type is indicated by the icon next to its name:

  •  for filename keyword
  •  for global variable
  •  for project variable
  •  for Jitterbit variable

In the list, hover over the variable name to preview information about it:

The icon's background is solid  if the project variable has a default value specified in the project variable configuration itself, or empty  if it does not. 

Select a variable to add to the field at the location of your cursor, anywhere in the string. The variable is displayed in a pill format similar to that shown below:

To review information about the variable, hover over the variable pill:

Toggling Formats Between Pill and Text

To change the default variable pill format to text format, click the collapse icon :

 This toggles the display of the pill format to a text format, with the variable name enclosed within square brackets [ ]:

To change from a text format back to pill format, change focus off of the field, such as by clicking into another configurable field. The field input automatically returns to the default pill format.

Removing a Variable

To remove the variable, click the remove icon :

Project Variable How-tos

This section provides information on how to complete specific tasks with project variables.

Converting a Global Variable to a Project Variable

To convert an existing global variable to a project variable, enter the name of the existing global variable into a Project Variable Name field. On saving (by shifting focus outside of the row if in list view or by clicking Save if in individual view), you are prompted to confirm that you want to convert the global variable into a project variable:

On clicking Continue, all references to and dependencies of the global variable are transferred to the project variable. This includes references to the former global variable within scripts, which now reference the project variable. Keep in mind that a value for a project variable set in a script during execution of the operation chain overrides the default value specified in the project variable configuration. Clicking Cancel cancels the conversion of the global variable.

On This Page

Last updated: Nov 19, 2020

  • No labels