Getting started with custom Javascript

Introduction

Most of the time, you will use the expression editor to write single-line expressions that follow the constraints of Cargo's expression template.

However, there are situations where you need to write custom JavaScript to perform more complex operations than what an expression can handle.

Writing functions

Most Cargo users will write JavaScript functions to achieve simple outcomes from these javascript snippets. These functions accept parameters as input, process them through a logic, and return a value.

Within these functions, you can leverage the full power of JavaScript to manipulate data objects, perform data operations, and more. As powerful as this can be, it is meant to be used judiciously to perform standalone actions.

Let's use the example below to illustrate:

// Define the checkLastActivity function that takes an array as an argument
function checkLastActivity(array) {
    const threeMonthsAgo = new Date();
    threeMonthsAgo.setMonth(new Date().getMonth() - 3); // Calculating the date three months ago from the current date

    return array.some(obj => {
    const lastActivityDate = new Date(obj.LastActivityDate);
    return lastActivityDate >= threeMonthsAgo;
    });
     // If no recent activity is found after checking all objects, return false
},
checkLastActivity( nodes.sf_search_leads ); //call function wit the object from the 'sf_search_leads' node

Let's explain what's happening here:

1. First, we define the checkLastActivity function that takes an array as an argument and returns a boolean value.
2. Inside the function, we iterate through the array and return true as soon as we find a record with a LastActivityDate that is within the last three months.
3. For this we use array.some method in Javacript. If no match is found with this condition, the function returns false.
4. Finally we call the function with the object from the sf_search_leads previously appearing in the workflow where this snippet will execute.

Invoking functions

The function you write with the custom JS window is entirely executed within this isolated environment. The only interaction with the rest of the workflow are the correct inputs that the function requires from the rest of the workflow's context, e.g. the output of the 'sf_search_leads' as in the example above. Otherwise, the function is self-contained and will produce an output of the node wherein it is executed.

Although the functions you write in the custom JS window are using the power of Javascript, there are a couple of things to keep in mind:

• Console logs are not permitted in these functions. To debug different steps of the function, it is advised to write these in a piecemeal fashion and observe the outputs in the workflow. Ideally, users should avoid writing complex functions within one snippet.
• Functions are only available within the node where they are defined, not elsewhere in the workflow.If you need to use a function repeatedly, the best practice is to define it as a recipe and call it from the node where it is needed.

Passing parameters

Parameters emerging from a node previously in the execution flow are passed using the standard nodes notation but without requiring curly brackets, i.e. {{}} as the function is already operating in a JavaScript context.

For example, if you have a node named sf_search_leads that outputs an array, you can pass this array to your function like this:

checkLastActivity(nodes.sf_search_leads);

Saving a function as a recipe

Once a function has been defined and tested, it can be saved as a recipe. Saving a recipe puts a sort of interface on top of the custom JavaScript snippet, allowing it to accept inputs and return outputs in a standardized way.

This makes it easier to reuse the snippet across different nodes and workflows, promoting code reusability and maintainability.