Skip to end of metadata
Go to start of metadata

Introduction

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 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.

WARNING: It is a known issue that project variable values that are modified or deleted in the Management Console are used by deployed projects but are not reflected in the Cloud Studio UI. The Projects page of Management Console will always display the configurations used by the deployed project. Until this issue is resolved, use Cloud Studio to update project variable values and deploy.

Project Variable List

You can access the project variables list screen within a project without needing to open the project, or from within the project itself.

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.

In the resulting screen, new project variables can be created by clicking the New Variable button to open the project variable configuration screen.

Existing variables are listed in a table, with each table column described below. By default, the project variables are sorted by creation time. Each column except for the one on the far right can be sorted by clicking on the column header.

  • Name: The name of the project variable.
  • Default Value: The default value of the project variable, if present. When a default value is configured to be hidden, asterisks are displayed in this field.
  • Label: The project variable label, if present.
  • Actions: Hover over the project variable row to reveal actions in the rightmost column:

Creating and Updating Project Variables

You can create and update project variables from within Cloud Studio, as well as update project variables from the Management Console and Citizen Integrator.

WARNING: It is a known issue that project variable values that are modified or deleted in the Management Console are used by deployed projects but are not reflected in the Cloud Studio UI. The Projects page of Management Console will always display the configurations used by the deployed project. Until this issue is resolved, use Cloud Studio to update project variable values and deploy.

From within Cloud Studio, you can access the project variable configuration screen from the project variable list, the project panescriptstransformations, or connector configuration, or from the project variable configuration screen itself. After creating a project variable or opening an existing variable to edit, see Configuring a Project Variable later on this page for configuration.

Project Variable List

From the project variable list, to create a new project variable, click the button New Variable.

To edit an existing variable hover over the project variable row and click the edit icon .

Project Pane

From the project pane in the Components tab, to edit an existing variable, hover over the project variable name, then click the actions menu icon  to open the actions menu. From the menu, select View/Edit. This and other actions in this menu are covered under Accessing Menu Actions later on this page.

Script

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, click the project variable name:

Transformation

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

To create a new project variable, click Create New:

To search for a particular variable by name, click the magnifying glass  and enter a keyword or multiple keywords separated by commas into the search box. Variables that have any of the keywords in the variable name will be returned.

To edit an existing project variable, hover over the variable name and click the edit icon :

Endpoint

While using a connector to configure an endpoint, from the connection or activity configuration screen on fields that have a variable icon , click the icon to bring up a list of variables:

To create a new project variable, click Add in the lower right corner:

To edit an existing project variable, hover over the project variable row and click the edit icon  on the far right.

Project Variable

Once within a new project variable configuration screen, you also have the ability to save that project variable and immediately enter the configuration screen for creating another new project variable. This feature may be useful when creating project variables in bulk.

Within a new project variable configuration screen, configure the variable as described under Configuring a Project Variable, then click the button Save & New:

This opens another project variable configuration screen for creating a new project variable.

Accessing Menu Actions

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:

Configuring a Project Variable

When you create a new or edit an existing project variable, the project variable configuration screen will open:

  • Variable Name: The name field is used for the actual variable name 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.

    TIP: When creating new project variables, it can be a good idea 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.

    WARNING: If you plan to use the project variables in JavaScript later, it is recommended to use underscores instead of periods. More information is provided below in Using Project Variables in Scripts or Transformations.

    To convert an existing global variable to a project variable, enter the name of the existing global variable into the Variable Name field. Upon saving, a prompt will ask you to confirm that you want to convert the global variable into a project variable:

    Upon clicking Continue, all references to and dependencies of the global variable will be transferred to the project variable. This includes references to the former global variable within scripts, which will now reference the project variable. (Keep in mind that a value for a project variable set in a script will override a default value specified in the project variable configuration during execution of the operation chain.)

  • Default Value: The default value, if specified, will be used as the initial value for the project variable, and can be modified later through scripting.

    • Hide value in UI (this is a one-time action): Select the checkbox to hide 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.

      CAUTION: Hiding the value does not prevent the value from being accessible in a script.
    • Default Value: Enter a default value for the project variable. If you do not want the project variable to have a default value, leave this field blank.

      WARNING: When this field is left blank, the project variable component is considered invalid and you will not be able to deploy. For this reason, we recommend that you always provide a default value and do not leave this field blank.
    • Overwrite Value: After saving a project variable with the Hide value in UI checkbox selected, when you reopen the project variable configuration screen, the value will be masked by asterisks and cannot be unhidden. To replace the default value, click the link to Overwrite Value displayed within the text box:

      This will open a window where you can specify a new default. Click Overwrite to replace the existing Default Value with what you enter in this text box:

  • Label: Enter a label to describe the variable name if desired. This label will show up when you hover over the variable in scripts.

  • Description: Enter a description to provide further details about the variable if desired.
  • Save: Click this button to save and close the project variable configuration.
  • Save & New: This button is present only when creating a new project variable and may be useful for creating project variables in bulk. Click this button to save the project variable and open another project variable configuration screen for creating a new project variable.
  • Discard Changes: After making changes to a new or existing configuration, click Discard Changes to close the configuration without saving. A message will ask you to confirm that you want to discard changes.
  • Delete: This deploys the project variable and any components it is dependent on (see Component Deployment).

Using 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 (or field in a transformation) 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 (or field in a transformation).

In scripts and transformations, existing project variables will also be displayed in the Variables tab of the component palette inside the Project Variables sub-tab:

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

  • Drag the variable from the palette to the script. The appropriate syntax for the script language will be inserted.
  • Begin typing the variable name and then press Control+Space (or Command+Space on Mac) to bring up a list of autocomplete suggestions. The appropriate syntax for Jitterbit Script will be inserted.
  • Manually enter the appropriate syntax for Jitterbit Script.

JavaScript

In JavaScript used within scripts created 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 without periods: 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: The value of a project variable that contains periods in its name can be retrieved only with the Jitterbit.GetVar function.

    • Jitterbit.GetVar: Using Jitterbit.GetVar, the code example Jitterbit.GetVar("$org.netsuite.auth.username") returns the value of the project variable called "org.netsuite.auth.username". Note that the dollar sign $ must be included within the variable name.

In JavaScript used within scripts created within an operation, existing project variables will also be displayed in the Variables tab of the component palette inside the Project Variables sub-tab:

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

  • Drag the variable from the palette to the script. The appropriate syntax for the script language will be inserted.
  • Begin typing the variable name and then press Control+Space (or Command+Space on Mac) to bring up a list of autocomplete suggestions. The appropriate syntax for JavaScript will be inserted.
  • Manually enter the appropriate syntax for JavaScript.

Using Project Variables in Configuration Screens

During configuration of various project components, including endpoint configuration using connectors, you can use project variables in any fields that have a variable icon .

Single Variable

To use a single variable as the only value within the field, click the variable icon  to bring up a list of variables. From the list, hover over the variable name to preview information about it. Select a variable to replace the contents of the field with it:

Any existing input entered within the field, if present, will be replaced with the variable. A single variable used as input in a field is displayed in a pill format similar to that shown below:

To change the pill format to text to use with additional input, with each variable displayed within square brackets [ ], click the collapse icon 

To clear the field, click the remove icon .

Variables with Additional Input

To use a variable along with other field input, including with other keywords or variables, enter an open square bracket [ into the field. From the list, hover over the variable name to preview information about it. Select a variable to insert the variable at the location of your cursor, anywhere in the string:

Variables entered using this method are displayed as text within square brackets [ ] within the field. Enter any additional input or add multiple keywords or variables using the same method described above:

Variables with Default Values

To define a default value, specify it within curly brackets { } immediately following the project variable name within the square brackets [ ]:

Though you can use variables when specifying a value of a configuration field, the default values of the variables will not work when testing in scripts. The default values will work when the script is run as part of an operation or at runtime.

To use variables to define the value of a configuration field and test them in scripts, you will need to either set explicit values using a script or define default values using curly brackets. Note that these default values will not be used at runtime if any other default values have been set in the project variable creation/update (in Cloud Studio), in the Management Console, or in Citizen Integrator.

CAUTION: As a best practice, the default value should be set during project variable creation/update (in Cloud Studio), in the Management Console, or in Citizen Integrator, rather than using the curly bracket syntax. A default value specified using the curly bracket syntax will take effect at runtime only if the default value defined using the other means is left blank.

On This Page

Last updated:  Aug 06, 2019

  • No labels