Skip to end of metadata
Go to start of metadata

Introduction

Filename keywords are used to generate unique filenames for configurable fields that take filenames as input. These include certain fields available when configuring endpoints using connectors. Filename keywords are one of the types of global data elements available in Jitterbit Harmony. The other types of global data elements—project variables, global variables, and Jitterbit variables—are also available globally throughout a project. They are set differently, as described in Project Variables, Global Variables, and Jitterbit Variables, respectively. However, as all global data elements share the same namespace, their names must be unique when compared against all other global data elements.

Available Keywords

The keywords listed in the table below are available to use in certain fields within endpoint configuration screens. The keywords are not case-sensitive. For example, [time] is equivalent to [TIME] and [Time].

KeywordSubstitution
[date] Substituted with the current date in the format YYYY-Mon-DD.
[ext]

Substituted with the file extension, if any, as set when using a file-type source. The intended use of this keyword is in a file-type target filename field.

[file] Substituted with the base file name (that is, excluding the file extension, if any), as set when using a file-type source. The intended use of this keyword is in a file-type target filename field.
[sequence] Substituted with the sequence of the file: 1 for the first, 2 for the second, and so on. Similar to the Jitterbit functions SourceInstanceCount() and TargetInstanceCount().
[time] Substituted with the current time in the format HHMMSS.
[unique] Substituted with a GUID, a random unique identifier.
TIP: Note that the Jitterbit variable jitterbit.source.filename gives the complete filename, is set with each source invocation, and can be used instead of the keywords [file] and [ext].

Using Filename Keywords in Configuration Screens

During configuration of endpoints using connectors, you can use filename keyword substitutions in certain fields that have a variable icon  or that are explicitly listed below.

You can use filename keywords as:

WARNING: As keywords use the same syntax as global and project variables, it is possible to create a global or project variable that has the same name. Because this can cause confusion, we recommend not creating global or project variables that have the same name as these keywords.

The keywords will override any variables of the same name when the project component is evaluated.

Fields Where Keywords Can Be Used

Keyword substitutions are intended to be used within configurable fields that take filename(s) as input. This includes certain fields available during file-based endpoint configuration, as listed below.

Read Activities

Write Activities

NOTE: A restriction on using filename keywords in Trigger File and Success/Error Folder is described later on this page under Limitations and Workarounds.

Single Filename Keyword

To use a single keyword as the only value within one of the fields listed above that supports filename keywords, 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

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

NOTE: The value for a filename keyword always appears to be empty.

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

To review information about the keyword, hover over the keyword 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 .

Filename Keywords with Additional Input

To use a keyword 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 keyword name to preview information about it. Select a keyword to insert the keyword at the location of your cursor, anywhere in the string:

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

Filename Keywords with Default Values

When keywords are entered, a default value can be included in the event that the value of the keyword is null. This is useful for keywords such as [ext] and [file], as these may be null. As the other keywords would never be null, assigning a default to them will have no effect.

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

When default values are specified, the keyword value will be used if it is defined, else the default value will be used.

Limitations and Workarounds

When using filename keywords in the Trigger File or Success/Error Folder fields, a limitation is that the keywords are not resolved when using the trigger file or creating the success or error file, respectively.

For example, let's say you have a source file named customers.csv and the current date is October 2, 2019.

You might try to use a keyword combination like this to set the target filename:

[file]_[date].csv

With this example, if the filename keywords were resolved, you might expect the result to be a success file named something like this, with the trailing underscore and timestamp being added by the Success/Error Folder functionality:

customers_2019-10-02.csv-_2019-10-02_02-02-54-525

However, because filename keywords are not resolved, instead the actual result will be something like this, including the unresolved keywords still in brackets:

[file]_[date].csv_2019-10-02_02-02-54-525

A workaround is to use a global variable instead of filename keywords for the target filename:

  1. Create a global variable in a condition added to a target node of the transformation, and set that global variable to specify the source filename.

    In this example, a filename has been created that uses the source filename and the current time, in UTC:

    <trans>
    If(SourceInstanceCount() == 1, 
      $filename_target = $jitterbit.source.filename + "_";
      $filename_target += Replace(GetUTCFormattedDateTime(Now(), "UTC", false), ":", "-");
    );
    true;
    </trans>
  2. Use the global variable (in the example, called filename_target) as the target filename in the Success/Error Folder field.

    The global variable will be resolved correctly for the success or error file, respectively.

NOTE: Similarly, with a source Trigger File, the use of filename keywords will not be resolved correctly in a filename. As a workaround, use a global variable set to an appropriate value.
On This Page

Last updated: Apr 14, 2020

  • No labels