Toggle Side Panel
Close search
View Categories

Scripting Introduction

2 min read

Cyclr supports JavaScript as its scripting language, allowing you to manipulate data before it’s sent as well as after it’s been retrieved. This can be useful when moving data between applications as what’s valid in one, may not be valid in another – sometimes data just doesn’t quite “fit” so requires some transformation.

Jump to Scripting reference pages:

Inline Script #

Inline Script is typically used to make small changes to individual pieces data directly in a Field Mapping, which would be within the Builder through a Step’s Step Setup popup.

As an example, below we’re dynamically setting the name of a CSV file being uploaded to an FTP server to the current date and time using the Moment.js library which is available within Cyclr’s Script engine:

For Inline Script, you must prefix the JavaScript code with = (an equals sign), e.g.:

=(100 * 2)

or

=`[Mergefield]` === '' ? 'no value' : `[Mergefield]`;

When using Mergefields which may contain text, it’s best to use ` characters (backticks) around them to prevent line breaks or other quote characters from breaking your Script.

Note: The [Mergefield] above represents fields inserted by Cyclr in Step Setup when choosing Type a Value and selecting one from the dropdowns.

If you’re finding your Inline Script is becoming complex, or you have multiple pieces on the same Step over several field mappings, you should consider combining them into Step-level Script within a single before_action function. As well as the added readability, it avoids multiple Script Engine’s being created – which impacts overall performance – as each piece of Inline Script results in a separate Script Engine being initialized.

Escaping non-Script = characters
If you have text to use in a “Type a Value” box which begins with an equals sign (=), but isn’t Script that you want Cyclr to execute, you can escape it by prefixing the equals sign with a \ character.

For example:
=Not Script!

Would just become:
\=Not Script!

Step Script #

Step Script can be used when you want to want to make more complex changes to data.

If you’re working on a Template or Cycle in the Builder and need to perform a change to some data, click the Step Setup button on a Step, then expand the Advanced Settings area and enter some Script to tie in to Cyclr’s Events as described below:

This is generally easier to read than multiple inline scripts and there can be a performance advantage to using one set of Step Script instead of multiple Inline Scripts.

Connector Script #

If you’re building a Custom Connector you also have the option to add script directly into the Connector’s definition.

This is done in the Script section of the Connector toolkit, either at the Connector-level or within individual Connector Methods.

Limitations #

  • Script used in Event Handler functions will execute for a maximum of 60 seconds before Cyclr times it out and returns an error.

    Exceptions to this are:
    • after_action – times out after 90 seconds and runs separately for each page of data retrieved.
    • after_action_paging – times out after 90 seconds multiplied by the number of pages of data retrieved, e.g. if Cyclr retrieved 2 pages of data through paging, the after_action_paging function would be given 180 seconds to execute before timing out.
  • External HTTP requests: for security reasons, Cyclr uses the same authentication method as the Connector and the same authentication value when the Connector was installed by the user. You cannot use the script to access or modify the authentication value.
  • The cycle_variables object is not available to Inline Script. Use Script placed on a Step’s Advanced Settings area instead. Also, any changes made to that object or its properties are not persisted.

Further Reading #

See the following pages for more on Scripting as well as reference pages for Event Handlers and other Functions: