Creating block templates

Canvas comes with a library of ready-made blocks for supported applications, but you may find that you have specific needs that are not covered by these blocks.

While you can customize any blocks directly in the workflow, it is usually better to create a new block template with the new functionality: A block template will let you manage and update the block across all workflows where it is used, and also add block questions (block settings selectable in the UI without the need for coding).

To create a new block template head to the Workbench section:

Click the + sign to create a new block template.

In this article we will create a new block for the Test application (which is registered to our account), which will return an array of employee names from the Test app API. (The Test app provides dummy data for testing purposes.)

You will now be presented with the block template editor.

The editor has four tabs:

• The Configuration Manager tab lets you create block questions, which are settings that can easily be changed by without the need for coding to customize the block.

• The Code Editor tab is where you write and debug the code for the block

• The Input Model tab lets you define the schema/model that the block accepts/expects as input.
  (This information is used by the Mapper block to fill out field names and types in the mapping table.)

• The Output Model tab lets you define the schema/model that the block gives as output.
  (This page is often left blank, as the Mapper block can dynamically create the model by sampling the output data from the block.)

Sections in this article:

Configuration Manager

The Configuration Manager tab lets you configure the block settings (aka “block questions”) that will be shown to users of the block:

About the fields:

• The Title is a short description of the setting

• The Information field can be used to provide additional info to the user. It is shown when hovering the pointer over the ℹ️ icon in the block settings

• The Tag name provides the name of the variable containing the settings, which can be accessed in the block code via getVariables()

• The Control type field lets you select the input type for the setting.

• The DataSource path field is where you select or define the option set for the control type, in cases where there are pre-defined options.
  For example, if you want to provide a dropdown menu (via the “Select” Control type), you can defined the dropdown options here.
  To create a new option set, simply start typing a name, and click “Add item…”:

When you click on “Add item …” you will be presented with a popup where you can create a list of the options for the block question:

- Under “Label” enter the description that will be shown to the user in the UI.
- Under “Value” enter the value that will be used in the block code.

You can see a preview of the block options on the right hand side.

Code Editor

The Code Editor tab is where you enter the actual code that will be used by the block:

• For more information about block development see:
  Development on Canvas

• You can debug the block code by pressing F12 and clicking the bug icon, as shown here:
  Running blocks in the debugger

Input Model Editor

The Input Model tab lets you define the schema/model in JSON format that the block accepts/expects as input. This information is used by the Mapper block to fill out field names and types in the mapping table.

Since the block we have created in previous steps does not accept incoming data (i.e. it does not use Datasource in its code), there will no need to define an Input Model.

Here is instead an example of an input model from a different block:

Output Model Editor

Similar to the Input Model, the Output Model lets you define the schema/model that the block gives as output. This page is often left blank, as the Mapper block can dynamically create the model by sampling the output data from the block.

Committing changes and publishing the template

Block templates in Canvas are version controlled. This enables you to potentially make changes to blocks across many workflows, without having to edit each individually. This works the same way as previously described for workflow templates:

• You can make changes to the template by clicking the pencil icon in Workbench.

• Changes made in workbench will first have “draft” status:

• Click the Publish icon to make the block template available for use in the workflow editor:

When committed, the changes will be replicated to all instances of the block template, in all workflows where it is in use.

If you for example have 100 workflows each using a block based off of the same block template, then changes you make and commit to the block template will be replicated to all 100 blocks in the 100 workflows (unless the blocks have been “customized” by having the code altered in the workflow editor).