Built-in helper functions

Canvas has several useful helper functions built in which will help you speed up integration development.

There are functions for storing values between runs (myVault), checking when the workflow last ran (dateLastRun), logging data (logger), storing session variables (session), in addition to a large library of application specific functions (see the fx docs in Canvas). - check after

This page provides an overview of these helper functions, which can all be used inside block code.

• Packages
  • api
  • fx
  • logger
  • myVault
• Properties
  • Datasource
  • dateLastRun
  • session
• Methods
  • getVariables()
  • getWorkflowVariables()

Packages

The following packages are provided by Canvas, and can be used in block Javascript code:

• api
• fx
• logger
• myVault

api

api package contains methods for working with CMA API.

CMA API is another CMA solution which is a wrapper for the APIs of third-party applications, which integration is provided by CMA. The list of supported applications is provided by this link

• api.get
• api.getDirect
• api.post
• api.postDirect

api.get

Sends get request to endpoint by specified url. Is asynchron method.

Parameters

url- relative path to endpoint, is mandatory. The path starts from application short name.

appkey- application key, is optional. If empty, then set by default from corresponded workflow application.

skey- session key, is optional. If empty, then set by default from corresponded workflow application.

api.getDirect

Sends get request to endpoint on specified CMA API server by specified url. Is asynchron method.

Parameters

url- relative path to endpoint, is mandatory. The path starts from application short name.

srv- CMA API server name, is optional.

appkey- application key, is optional. If empty, then set by default from corresponded workflow application.

skey- session key, is optional. If empty, then set by default from corresponded workflow application.

api.post

Sends post request to endpoint by specified url. Is asynchron method.

Parameters

url- relative path to endpoint, is mandatory. The path starts from application short name.

jData - request body, is mandatory.

appkey- application key, is optional. If empty, then set by default from corresponded workflow application.

skey- session key, is optional. If empty, then set by default from corresponded workflow application.

api.postDirect

Sends post request to endpoint on specified CMA API server by specified url. Is asynchron method.

Parameters

url- relative path to endpoint, is mandatory. The path starts from application short name.

jData - request body, is mandatory.

srv- CMA API server name, is optional.

appkey- application key, is optional. If empty, then set by default from corresponded workflow application.

skey- session key, is optional. If empty, then set by default from corresponded workflow application.

fx

fx is a package, which contains functions provided by CMA, but also can be increased by organizations specific functions. Some functions are grouped by packages including applications specific functions.

logger

logger is a package which helps to work with User Logs in block JS-code.

The package contains just one log method.

return arr;

Please note that following values will be converted to null and logged as null then:

• undefined
• NaN
• Infinity
• '' - empty string

myVault

myVault is a package which contains methods for working with collections of keys-value pairs. All methods are grouped by access level type:

• Workflow level. A collection is shared between all workflow blocks.
• Account level, which is also called as Global myVault. A collection is shared between blocks of all account workflows.

There are myVault methods which you can call in js-code:

Description	Workflow level	Account level
Writes key and value into myVault dictionary	set	setGlobal
Writes key and value into myVault dictionary on the workflow complete event	setOnComplete	setGlobalOnComplete
Reads value from myVault dictionary by specified key	get	getGlobal
Removes key-value pair from myVault dictionary by specified key	remove	removeGlobal
Determines whether the myVault dictionary contains the specified key	contains	containsGlobal

myVault.set

Writes key and value into myVault dictionary belonged to the workflow.

Parameters

key-the key of the element to set.

value-the value of the element to set. The value can not be null.

Example 1:

let key =  1;
let value = fx.utcNow();
await myVault.set(key, value);

Example 2:

let key =  'order#1';
let value = fx.utcNow();
await myVault.set(key, value);

Example 3:

let keys =  [1, 2, 3, 4, 5];
let value = fx.utcNow();
await fx.forEach(keys, async(key)=> { 
    await myVault.set(key, value); 
});

myVault.setGlobal

Writes key and value into Global myVault dictionary belonged to the account.

Parameters

key-the key of the element to set.

value-the value of the element to set. The value can not be null.

Example 1:

let key =  1;
let value = fx.utcNow();
await myVault.setGlobal(key, value);

Example 2:

let key =  'order#1';
let value = fx.utcNow();
await myVault.setGlobal(key, value);

Example 3:

let keys =  [1, 2, 3, 4, 5];
let value = fx.utcNow();
await fx.forEach(keys, async(key) => { 
    await myVault.setGlobal(key, value); 
});

myVault.setOnComplete

Writes key and value into myVault dictionary belonged to the workflow.

This method differs from myVault.set method in “saving into myVault is deferred” condition and will be executed on workflow complete event.

Parameters

key-the key of the element to set.

value-the value of the element to set. The value can not be null.

Example 1:

let key =  1;
let value = fx.utcNow();
await myVault.setOnComplete(key, value);

Example 2:

let key =  'order#1';
let value = fx.utcNow();
await myVault.setOnComplete(key, value);

Example 3:

let keys =  [1, 2, 3, 4, 5];
let value = fx.utcNow();
await fx.forEach(keys, async(key) => { 
    await myVault.setOnComplete(key, value); 
});

📋Related articles Please also see session.vault by this link Please see conditions for “Workflow complete“ by this link

myVault.setGlobalOnComplete

Writes key and value into Global myVault dictionary belonged to the account.

This method differs from myVault.setGlobal method in “saving into Global myVault is deferred” condition and will be executed on workflow complete event.

Parameters

key-the key of the element to set.

value-the value of the element to set. The value can not be null.

Example 1:

let key =  1;
let value = fx.utcNow();
await myVault.setGlobalOnComplete(key, value);

Example 2:

let key =  'order#1';
let value = fx.utcNow();
await myVault.setGlobalOnComplete(key, value);

Example 3:

let keys =  [1, 2, 3, 4, 5];
let value = fx.utcNow();
await fx.forEach(keys, async(key) => { 
    await myVault.setGlobalOnComplete(key, value); 
});

📋Related articles Please also see session.vaultGlobal by this link Please see conditions for “Workflow complete“ by this link

myVault.get

Reads value from myVault dictionary by specified key.

Parameters key-the key of the element to get.

Example 1:

let value = await myVault.get(1);

Example 2:

let value = await myVault.get( 'order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5];
let values = [];
await fx.forEach(keys, async(key) => { 
    values.push(await myVault.get(key)); 
});

myVault.getGlobal

Reads value from Global myVault dictionary by specified key.

Parameters key-the key of the element to get global value.

Example 1:

let value = await myVault.getGlobal(1);

Example 2:

let value = await myVault.getGlobal( 'order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5];
let values = [];
await fx.forEach(keys, async(key) => { 
    values.push(await myVault.getGlobal(key)); 
});

myVault.remove

Removes key-value pair from myVault dictionary by specified key.

Parameters

key-the key of the element to get global value.

Example 1:

let value = await myVault.remove(1);

Example 2:

let value = await myVault.remove('order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5];
await fx.forEach(keys, async(key) => {
    await myVault.remove(key); 
});

myVault.removeGlobal

Removes key-value pair from Global myVault dictionary by specified key.

Parameters

key-the key of the element to get global value.

Example 1:

let value = await myVault.removeGlobal(1);

Example 2:

let value = await myVault.removeGlobal('order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5];
await fx.forEach(keys, async(key) => {
    await myVault.removeGlobal(key); 
});

myVault.contains

Determines whether the myVault dictionary contains the specified key

Parameters

key-the key of the element to get global value.

Example 1:

let contains = await myVault.contains(1);

Example 2:

let contains = await myVault.contains('order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5, 6, 7, 8, 9];
keys = await fx.filter(keys, async(key) => { 
    return await myVault.contains(key); 
});

myVault.containsGlobal

Determines whether Global myVault dictionary contains the specified key

Parameters

key-the key of the element to get global value.

Example 1:

let contains = await myVault.containsGlobal(1);

Example 2:

let contains = await myVault.containsGlobal('order#1');

Example 3:

let keys =  [1, 2, 3, 4, 5, 6, 7, 8, 9];
keys = await fx.filter(keys, async(key) => { 
    return await myVault.containsGlobal(key); 
});

Properties

All properties provided by Canvas and which can be used in block JS-code:

• Datasource
• dateLastRun
• session

Datasource

Datasource is an array of block responses, which dependency is set for the block

Example:

//the block has dependencies with 2 blocks: employees and timepunches
let employees = Datasource[0];
let timepunches= Datasource[1];

📋Related articles Please see the documentation for Response via this link

dateLastRun

dateLastRun is a global workflow property which can be used in js-code. The property value is a date and time when a workflow was processed successfully last time. If workflow is a new and has not been run before, then property value is NULL.

You can see the value of workflow dateLastRun on the Workflow box in the Workflows menu.

Rules when dateLastRun is updated

There is a list of cases when dataLastRun is updated:

• on Workflow complete;
• when processed block was stopped programatically with fx.stopAfterThisBlock(true).

📋Related articles You can learn how to stop a running workflow on this page

session

session is an object which is shared between all blocks in the workflow and contains following properties:

• session.vault
• session.vaultGlobal
• session.vars

session.vault

session.vault is an object of keys-value pairs which was set by myVault.setOnComplete() method and which will be moved into myVault on workflow complete event.

Example 1:

let key = 1;
let value = fx.utcNow();
session.vault[key] =value; // the same code with myVault.setOnComplete(key, value);

Example 2:

let value = fx.utcNow();
session.vault.abc =value; // the same code with myVault.setOnComplete('abc', value);

danger

Please note that overriding of session.vault is forbidden.

For example, you will not be able to set following: session.vault = []; session.vault = null; session.vault = 5;

session.vaultGlobal

session.vaultGlobal is an object of keys-value pairs which was set by myVault.setGlobalOnComplete() method and which will be moved into Global myVault on workflow complete event.

Example 1:

let key = 1;
let value = fx.utcNow();
session.vaultGlobal[key] =value; // the same code with myVault.setGlobalOnComplete(key, value);

Example 2:

let value = fx.utcNow();
session.vaultGlobal.abc =value; // the same code with myVault.setGlobalOnComplete('abc', value);

danger

Please note that overriding of session.vaultGlobal is forbidden. For example, you will not be able to set following: session.vaultGlobal = []; session.vaultGlobal = null; session.vaultGlobal = 5;

session.vars

session.vars is an object which Canvas provides for keeping of global variables in workflow context, which are not included into block responses.

Example:

session.vars = {c: 1, str: 'abc'};
session.vars.obj = {id: 1, name: 'flower'};
session.vars.arr = [1,2,3,4,5];

danger

Please note that overriding of session.vars is forbidden. For example, you will not be able to set following: session.vars = []; session.vars = null; session.vars = 5;

Methods

Canvas provides just 1 method which can be used in block JS-code, it is getVariables().

getVariables()

Returns array of block variables. No parameters.

Example:

let v = getVariables();
let url = `quin/Sections?apikey=${v.apiKey}`;
let sections = await api.get(url);

getWorkflowVariables()

Returns array of workflow variables. No parameters.

Example:

let v = getWorkflowVariables();
let url = `quin/Sections?apikey=${v.apiKey}`;
let sections = await api.get(url);