Javascript Functions (technical preview)

If you like to write scripts from time to time, or you are a seasoned software engineer – we have great news for you! We're rolling out JavaScript Functions as part of our efforts to make Jitsu a scriptable platform. We started with enabling functions for scripting table names and WebHook request bodies. Later, we're going to expand Functions to all aspects of event processing, including mapping and filtering.

If you are unfamiliar with programming languages – no worries. This may be a good place to start because our Code Debugger allows you to interactively practice writing JavaScript code on test data samples.

Interactive Code Debugger

How to use#

JavaScript Functions come in handy in cases when certain destination parameters need to be evaluated based on properties of an incoming event. These parameters are:

• Table name – to choose destination table name or skip event from processing
• HTTP URL – to fill destination URL like WebHook URL
• JSON Body – to produce JSON payload that will be sent to destination

Jitsu UI marks fields where JavaScript Function can be applied with a green bug icon 🪲. Clicking on that icon brings a Code Debugger window where you can perfect your function.

Click the green bug

Technical Details#

Fast delivery of new features for our clients is our primary goal in Jitsu.

That is why the first implementation of the dynamic fields evaluation was based on the GO text template. Because we write Jitsu backend with Go language, the decision to choose GO text/template came naturally as it is the fastest tool to deliver that does the job. Jitsu will keep supporting the GO text/template to maintain backward compatibility with all our current user setups. Language is detected automatically based on syntax of expression.

When we were deciding how to integrate JavaScript support into our Go application, we were committed to our goal. That is why for our first implementation of JavaScript engine we preferred dop251/goja over a V8-based solution. Goja engine is written in pure Go. That allowed us to save a lot of time on not dealing with supporting different architectures of V8 dependency for our packages.

JavaScript Functions use Babel 7.14 internally to allow users to use some nice features of JavaScript language like Optional chaining or Template literals.

We still like the idea of migrating to V8 in the future.

Examples#

Table name evaluation examples#

Table name expression that skips events without user's email. Passed events go to table based on metric_type:

$.user?.email && $.metric_type

Tables will have 'event_type_YYYY_MM' format based on 'event_type' and date. Golang's Format function is used for convenience (Take a hint).

;`${_.event_type}_${_._timestamp.Format("2006_01")}`

Keep only conversion events (skip other) in case a user isn't Google Analytics known user:

$.event_type == "conversion" && !$.ids?.ga && $.event_type

more readable form:

if ($.event_type == "conversion") {
  //only for conversion events
  if (!$.ids?.ga) {
    //no ga id present
    return $.event_type
  }
}
return ""

Data Masking#

Simple example that removes all emails from an event object before choosing a table name. Object modifications in JavaScript Function reflect on what actually will be sent to destination:

var emailRegexp =
  /^([a-zA-Z0-9_\-\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([a-zA-Z0-9\-]+\.)+))([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$/
function removeEmails(obj) {
  for (const key in obj) {
    if (typeof obj[key] === "object") {
      removeEmails(obj[key])
    } else if (typeof obj[key] === "string" && obj[key].match(emailRegexp)) {
      delete obj[key]
    }
  }
}
removeEmails($)
return "events_without_emails"

WebHook with JSON Body example#

Choose a Webhook URL based on event type:

let baseURL = "https://hooks.slack.com/services/"
switch ($.event_type) {
  case "conversion":
    return baseURL + "123/abc/ABC"
  case "newuser":
    return baseURL + "987/xyz/XYZ"
}
return ""

Fill the body of WebHook payload:

return {
  blocks: [
    {
      type: "header",
      text: {
        type: "plain_text",
        text: "🤘" + ` ${_.metric_type} from ${_.user?.email}`,
        emoji: true,
      },
    },
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text: `User ${_.user?.email} has sent *${_.metric_type}* in <https://example.com?email=${encodeURIComponent(
          _.user?.email
        )}>`,
      },
    },
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text: "*Data*:```" + JSON.stringify(_, null, 4) + "```",
      },
    },
  ],
}

Learning More#

• Follow & star Jitsu on GitHub
• Try a cloud version of Jitsu. It's free for up to 250,000 events per month
• Join our Slack! Our community will help you with any questions!