Format Strings with Templates

Any steps that accept or create strings can also include InsightConnect variables. These templates help you format string content for plugins and artifact cards.

Handlebars 101

InsightConnect’s templating syntax is based on the Handlebars language. Learn more about Handlebars at https://handlebarsjs.com/guide

Blocks

The Handlebars language structures content in “blocks,” which begin with tags that start with {{#<block type>}} and end with {{/<block type>}}. Type your content between the block tags, and substitute <block type> with the name of the block you intend to use. You can nest blocks within other blocks.

Format Variables Within Handlebars Blocks

All triggers and action steps create JSON-based output. Use a step’s output variables as input for any following steps.

To quickly format previous steps’ output variables, use the format {{[StepName].[variablename]}}, replacing StepName with the name of the step creating the output and replacing variablename with the name you configured for that variable.

Alternatively, you can click on the blue + sign in any variable-enabled string field to search for the desired variable. Variables are sorted according to the step that created it.

If you add any variables with the + sign into the following Handlebars-based templates, remove the curly braces on either side of the variable. A single Handlesbars statement should only have one set of four curly braces. For example, {{#each [StepName].[variable]}} is correct, and {{#each {{[StepName].[variable]}} }} is incorrect.

Conditional Display

If you would like to display only some variable information and not others, use conditional logic and statements to toggle what variable content your artifacts or plugins can publish.

Conditional logic uses conditions to toggle certain behavior between one option or another. In order for InsightConnect to choose one option, it must meet a given condition. If the condition isn’t met, then InsightConnect selects the second option instead.

In InsightConnect, use an “if statement” to specify the condition that would lead to the first option displaying. Follow the provided template and sample content to configure a conditional statement that works for your needs.

Template: Conditional Display

handlebars
1
{{#if <condition to check for>}}
2
Content to display if condition is met
3
{{else}}
4
Content to display if condition is not met
5
{{/if}}

Example: Conditional Display

The following example checks for a condition based on a step that searches for a provided URL (Check URL.url) in a database. If the step finds the URL in the database, the variable Check URL.wasfound will be set to true—if the URL wasn’t discovered, the value of Check URL.wasfound will be false.

handlebars
1
{{#if [Check URL].[wasfound]}}
2
The url {{[Check URL].url}} was found.
3
{{else}}
4
The url {{[Check URL].url}} was not found.
5
{{/if}}

This string template example checks the value of Check URL.wasfound. If the step checks for the URL google.com, the template will display “The URL google.com was found” or “The URL google.com was not found.”

Display Array Content

The Handlebars language allows you to iterate over array-type input variables. Array input and output save collections of data, and any following workflow steps that operate on that data can run actions on the full array.

Template: Display Array Content

handlebars
1
{{#each <collection of items to check>}}
2
Content to display for one item of the array
3
{{/each}}

Example: Display Array Content

To illustrate how to display array content, we’ll build upon the example provided for conditional display. Instead of operating on one Check URL.url value, this sample operates on an array of multiple URL strings, which are stored in the variable Check URL.$outputs.

handlebars
1
{{#each [Check URL].[array].$outputs}}
2
  {{#if [Check URL].in_database}}
3
  The url {{url}} was found.
4
  {{else}}
5
  The url {{url}} was not found.
6
  {{/if}}
7
{{/each}}

For this example, Check URL.$outputs contains the URLs google.com, bing.com, and askjeeves.com. If all three URLs were discovered in the database, the resulting artifact would display.

To display array items from a trigger’s array input, format the string content as follows:

handlebars
1
{{#each [TriggerName].[arrayvariable]}}
2
{{this}}
3
{{/each}}

The this variable refers to the current item in the array.

Display JSON Object Content

You can display all JSON object content in an artifact, or print only specific items by using key names.

Template: Print all JSON Object Items

You can print the list of all items in a JSON object with this template.

handlebars
1
{{#each [StepName].[JSON object variable]}}
2
{{#each .}}
3
  {{@key}} = {{.}}
4
{{/each}}
5
{{/each}}

The period . refers to the item values mapped within the JSON object. The {{@key}} = {{.}} statement prints the key reference and corresponding value. For example, the JSON item { “dog”: “fido”} will display as dog = fido.

Template: Print JSON Object Items by Key Name

You can also print JSON object values by referring to the values by their key name. Add your desired content between the each tags.

handlebars
1
{{#each [StepName].[JSON object variable]}}
2
Your content {{firstkeyname}}
3
{{nextkeyname}}, more of your content
4
{{etc keyname}}
5
{{/each}}

To illustrate how to print JSON objects with key name references, consider this sample object:

json
1
[ {'name': u'Line 6 amp b 52 400 watt cabinet', 'has_image': True, 'url': u'https://peoria.craigslist.org/msg/d/line-6-ampwatt-cabinet/6305140213.html', 'has_map': True, 'price': u'$400', 'geotag': None, 'where': Peoria, 'id': u'6305140213', 'datetime': u'2017-09-13 20:34'}
2
{'name': u'Crate Cube 40 GX guitar amp', 'has_image': True, 'url': u'https://springfieldil.craigslist.org/msg/d/crate-cube-40-gx-guitar-amp/6305483242.html', 'has_map': True, 'price': u'$135', 'geotag': None, 'where': Springfield, 'id': u'6305483242', 'datetime': u'2017-09-14 08:12'} ]

The string formatting based on the key name template could be:

handlebars
1
{{#each [Search For Sale].[sale_posting]}}
2
{{name}} - {{price}} in {{where}}
3
{{/each}}

The end result of the string formatting for the sample object is:

text
1
Line 6 amp b 52 400 watt cabinet - $400 in Peoria
2
Crate Cube 40 GX guitar amp - $135 in Springfield

Match Variables

You can also determine which content to display by comparing strings or integers with Handlebars. Your content only displays if the equal statement finds a successful string match.

Template: Match Variables

handlebars
1
{{#equal <variable> <constant>}}
2
Content to display
3
{{/equal}}

To format the equal statement in your artifact:

1. Replace the <variable> placeholder with your desired InsightConnect step variable formatted without curly braces, like [Stepname].[variable].
2. Replace the <constant> placeholder with the string or integer to compare with the InsightConnect variable value. Strings must be formatted in double quotes (”string”), and integers must be formatted without quotes (0).

Example: Match Variables

In the following example, if the value of the “CountPostings.count” variable matches the integer 0, the artifact will display the text "No postings for today.”

handlebars
1
{{#equal [Count Postings].[count] 0}}
2
No postings for today
3
{{/equal}}

Extract Nested Information

If your workflow uses nested arrays (arrays within arrays) or objects, use a nested with block to grab information within the nested structure.

Template: Extract Nested Information

handlebars
1
{{#each <parent structure>}}
2
  {{#with <child structure>]}}
3
   {{<item to extract>}}
4
  {{/with}}
5
{{/each}}

Example: Extract Nested Information

Consider this nested JSON object: { "hits": [{ "obj": { "message": "hi" }}] }. The following Handlebars content will print the value “hi” for the key message within the nested object obj. obj is the value of the parent object’s key hits. { "hits": [{ "obj": { "message": "hi" }}] }.

handlebars
1
{{#each [hits]}}
2
  {{#with [obj]}}
3
   message is {{message}}
4
  {{/with}}
5
{{/each}}

Other Formatting Options

Use these options to format your artifact content with Handlebars.

Time Variables

InsightConnect can also display time values with Handlebars.

{{$time.now}} : Display the current time in RFC 3339 date format.

For example, 2018-03-14 00:45:49.654049875 +0000 UTC{{$time.format <time variable> <format string>}} : Format a time variable into a different string format. The time variable can be {{$time.now}} or a previous step variable. Replace the <format string> value with one of the options from the table below according to your needs.

Time Format String Options

For example: {{$time.format ($time.now) "RFC822"}} would display: 02 Jan 06 15:04 UTC

Remove Newlines

If you include your Handlebars statements on separate lines from the rest of your content, InsightConnect will capture the new lines when creating the artifact or content. If you want to remove new lines from the variable, add ~ to the beginning of your logic statements. For example:

handlebars
1
line1
2
{{~#if [API Trigger].[myvariable]}}
3
line2
4
{{~/if}}
5
line3

will appear as

text
1
line1line2line3

whereas

handlebars
1
line1
2
{{#if [API Trigger].[myvariable]}}
3
line2
4
{{/if}}
5
line3

will appear as

text
1
line 1
2
line 2
3
line 3

Display Length

To show how many items are in an array or how many characters are in a string, use {{$length (["step_name"].[variable])}}. Replace step_name and variable with a step variable from your own workflow. You can also enter a standard non-variable string if needed, for example {{$length "Some Text Here"}}