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.

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

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.

From within Cloud Studio, you can create or update project variables from several locations, including the project variable list, the project panescriptstransformations, connector configuration, and the individual project variable configuration screen. After creating a project variable, you can configure it either in list view or individually, as described later on this page.

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, to create a new project variable, click the New Variable button:

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

Additional information about 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, then 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 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, 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

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

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

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

Or, when an existing project variable has already been used within a configuration field, hover over the variable name to view information about the variable, then use the edit icon or click 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.

Project Variable

Once within an individual 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 Individually later on this page, then click the button Save & New:

This opens another individual 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:

  • View/Edit: This 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: This is used to permanently delete the project variable (see Component Dependencies, Deletion, and Removal).
  • Rename: This positions the cursor on the component name in the project pane for you to make any edits as necessary.
  • View Dependencies: This 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: This deploys the project variable and any components it is dependent on (see Component Deployment).
  • Configurable Deploy: This opens the deployment screen, where you can select project components to deploy (see Component Deployment).
  • Add to group: This 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: This creates a copy of the project variable as a new, unreferenced component. Upon creating the component copy, the cursor is positioned on the component name within the project pane for you to rename the component.

Configuring Project Variables in List View

Configuring project variables in list view is one of two views for configuring project variables, the other being the individual project variable configuration screen as covered under Configuring a Project Variable Individually later on this page.

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:

This will add a new project variable row to the project variable table below. New rows are automatically added at the top of the table, with the cursor positioned on the Name field for you to rename the project variable:

Once you focus out of the name field, if other project variables are present, the new project variable will be reordered in alphabetical order by name within the table and the New Variable button will again become active for you to create additional variables. The sort order can be changed by clicking on 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. The configuration is saved each time you change fields. Each column of the project variable table is described below:

  • Select: The column on the far left can be used to select one or more project variables for deletion. Select the checkbox in the column header to select all variables at once, or select checkboxes individually by project variable row to select variables one at a time. After at least one project variable is selected, the Delete Variable(s) button along the top of the table becomes available for you to permanently delete the project variable (see Component Dependencies, Deletion, and Removal).
  • 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 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 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: Enter a default value (optional) 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 will 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. Upon enabling this option, a prompt will ask you to confirm that you want to hide the value. When you use this option, note that the value cannot be unhidden later.

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

    Upon disabling this option, a prompt will ask you to confirm that you want to remove the current value (as a previously hidden value cannot be unhidden):

    Upon clicking Continue, the cursor will be positioned in the Default Value field, which will now be empty.

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

Configuring a Project Variable Individually

Configuring a project variable individually is one of two views for configuring project variables, the other being the project variable list view as covered under Configuring Project Variables in List View earlier on this page.

When you create a new or edit an existing project variable individually, this screen opens:

  • 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 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 Project 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: Use the slider to toggle on this option. Enabling this option will 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. Upon enabling this option, a prompt will ask you to confirm that you want to hide the value. When you use this option, note that the value cannot be unhidden later.

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

      Upon disabling this option, a prompt will ask you to confirm that you want to remove the current value (as a previously hidden value cannot be unhidden):

      Upon clicking Continue, the cursor will be positioned in the Default Value field, which will now be empty.

    • 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.
  • 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: After opening an existing project variable, click Delete to permanently delete the project variable and close the configuration (see Component Dependencies, Deletion, and Removal).

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 to display a list of autocomplete suggestions. Select a variable to insert the appropriate syntax for Jitterbit Script.
  • 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 to display a list of autocomplete suggestions. Select a variable to insert the appropriate syntax for JavaScript.
  • 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 display a list of keywords and variables.

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

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

The icon's background will be solid  if the project variable has a default value, or empty  if it does not.

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

Select a variable to replace the contents of the field. 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 review information about the variable, hover over the variable pill:

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:  Jan 22, 2020

  • No labels