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).

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

1 Packages
- 1.1 api
- 1.2 fx
- 1.3 logger
- 1.4 myVault
2 Properties
- 2.1 Datasource
- 2.2 dateLastRun
- 2.3 session
3 Methods
- 3.1 getVariables()
- 3.2 getWorkflowVariables()

Packages

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

1 api
2 fx
3 logger
4 myVault

api

api package contains methods for working with CMA API.

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

1 api.get
2 api.getDirect
3 api.post
4 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.

//get list of all endpoints provided for MyStore application
var response = await api.get('myst2/meta');

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.

//get list of all endpoints provided for MyStore application
var response = await api.getDirect('myst2/meta', 'cmaeu3');

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.

let newProduct = { 
    "number": "000TS-01",
    "name": "T-short Adidas White XS",
    "vatType": 31
};
var response = await api.post('trip2/product', newProduct);

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.

let newProduct = { 
    "number": "000TS-01",
    "name": "T-short Adidas White XS",
    "vatType": 31
};
var response = await api.post('trip2/product', newProduct, 'cmaeu3');

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.

Full documentation of all functions you can get by this link.

logger

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

The package contains just one log method.

logger.log('Hello world!');

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

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.

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

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

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.

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

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

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.

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

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

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 conditionas 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.

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

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

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 conditionas 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.

let value = await myVault.get(1);

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

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.

let value = await myVault.getGlobal(1);

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

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.

let value = await myVault.remove(1);

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

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.

let value = await myVault.removeGlobal(1);

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

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.

let contains = await myVault.contains(1);

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

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.

let contains = await myVault.containsGlobal(1);

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

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:

1 Datasource
2 dateLastRun
3 session

Datasource

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

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

// the block has a dependency with 1 block, which response is an array of objects with 3 properties: 
// API_key, employees and timepunches
let employees = fx.getEntityFromSource(Datasource[0], “employees“, ["API_key"]);
let timepunches = fx.getEntityFromSource(Datasource[0], “timepunches“, ["API_key"]);

Related articles

Please see documentation of fx.getEntityFromSource by this link

Please see also Response by 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 list page or read this value in js-code.

Rules when dateLastRun is updated

There is a list of cases when dataLastRun is updated:

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

Related articles

You can know how to start workflow running by this link

You can know how to stop workflow running by this link

session

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

1 session.vault
2 session.vaultGlobal
3 session.vars

session is stored for each workflow running. session is empty when new run is started (from first block) and is passed to next blocks till last. If you start running not from 1st block, for example from 3nd block, then session will be copied from 2nd block of previous running.

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.

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

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

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.

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

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

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.

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

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.

let v = getVariables();

let url = `quin/Sections?apikey=${v.apiKey}`;

let sections = await api.get(url);

getWorkflowVariables()

Returns array of workflow variables. No parameters.

let v = getWorkflowVariables();

let url = `quin/Sections?apikey=${v.apiKey}`;

let sections = await api.get(url);

[EXT] Canvas documentation

Built-in helper functions

Packages

api

api.get

api.getDirect

api.post

api.postDirect

fx

logger

myVault

myVault.set

myVault.setGlobal

myVault.setOnComplete

myVault.setGlobalOnComplete

myVault.get

myVault.getGlobal

myVault.remove

myVault.removeGlobal

myVault.contains

myVault.containsGlobal

Properties

Datasource

dateLastRun

Rules when dateLastRun is updated

session

session.vault

session.vaultGlobal

session.vars

Methods

getVariables()

getWorkflowVariables()