Using Ruby with Workflows

Overview

Kinetic's workflow engine uses jRuby, a Java implementation of the Ruby programming language, in handlers, node parameters, and connectors. For the purposes of programming, it's easiest to think of it as "just" Ruby.

You can find a general overview of Ruby on the Ruby Programming Language website. Additionally, you can find Ruby documentation at Ruby-Doc.org.

In this guide, we'll discuss some common uses of Ruby in the workflow engine, how to test Ruby expressions, and how to understand basic Ruby syntax when it's used in trees and routines.

Prerequisites

To use Ruby on your local machine, you can install Interactive Ruby (IRB), which lets you run Ruby commands from your command line. You can find an official tutorial for IRB here: Ruby Lang IRB.

Working with Ruby in the Platform

Using Ruby Code in Parameters

When executing Ruby code in a parameter, remember to enclose the entire string within one set of ERB tags. You don't need to include tags for every @values, @result, and so on - just the one set will do.

Don't use ERB tags when executing code in a connector. The workflow engine knows that anything in a connector expression should be evaluated to true or false.

If-Then Operations

One of the most often-used conditional statements is the if...then...else statement. The basic version looks like this:

if condition
  Statement
end

You can also add an else to specify further direction:

if condition
  Statement
else
  Statement
end

You can use all of the stand conditional operators with this statement (that is, <, >, ==, <=, >=, !=). You can also use the ternary operator shortcut, which uses the Conditional **?** true statement **:** false statement format. This operator is frequently used as an alternative to an if...else statement.

To and From JSON

JSON is the standard for moving information through the workflow engine. We often return information as a .json string, and many of the Create handlers use JSON when adding values to fields on a form.

Here is some basic JSON:

{
  "name":"John", 
  "age":31, 
  "city":"New York"
}

to_json

Ruby uses the to_json method to turn hashes into JSON. The following example uses the to_json method in one of the parameters in a Create User node:

<%=
phone_number = @values['Phone Number'].to_s.empty? ? [] : [@values['Phone Number']]
{
  "First Name" => [@values['First Name']],
  "Last Name"  => [@values['Last Name']],
  "Work Phone" => phone_number,
  "Cell Phone" => phone_number
}.to_json%>

(Also note the ternary operator at the beginning for phone_number!)

Everything within the hash (between the curly brackets) is converted to JSON when the engine evaluates the code between the ERB tags.

JSON.parse

JSON.parse is used to get values out of a JSON string. Here's an example, also from the Create User node:

JSON.parse(@results['Approval Task']['Fields JSON'])['Space Admin']

The following JSON string would return a value of true for this method:

{
  "username" : "hsolo",
  "Space Admin" : "true"
}

Strftime

strftime is used to format time strings. The standard output for Date|Time is YYYY-MM-DDTHH:MM:SS+/-timezone offset. This comes out looking similar to this example: 2022-08-10T04:10:06+04:30.

If you wanted to reformat the date for comments or within a log file, you could do something like this:

<%=
require 'date'
x = DateTime.parse(@values['When Should Cleaning Happen'])
x.strftime("%F")
 %>

Instead of the more complicated output, this would return 2023-06-23.

Here are some other operators you can use:

Comments

Comments are a way to explain and enhance your code. In Ruby, comments begin with a #. There are a few other ways to add comments, but the limitations of using them in parameters in a node mean that using a # is the easiest way.

Example from a Submission config routine:

<%=
# Parse Source Data values
data = JSON.parse(@inputs['Source Data'])['values']
# Loop over each value and remove nil's and join arrays
result = {}

# Requested For
if data['Requested For Display Name'].nil?
  result['Requested For'] = data['Requested For']
else
  result['Requested For'] = "#{data['Requested For Display Name']} (#{data['Requested For']})"
end

has_key?

When you need to see if a node was executed or if a hash exists, the most common option is to use the .has_key? method. The following example uses it in a connector:

@results.has_key?('Test Node 1')

This evaluates to either true of false.

Here's another example, this time using .has_key? in a parameter:

<%=
if @results.has_key?('Test Node 1')
    @results['Test Node 1']['output']
else
    "Test Node 1 did not execute"
end
%>