• Ready for review

    • Built-in helper functions

    Owned by Natalia Yudnikova
    Last updated: Nov 23, 2023
    7 min read

    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.

    Packages

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

    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

    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.

    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.

    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.

    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.

    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.

     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.

     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.

    myVault.getGlobal

    Reads value from Global myVault dictionary by specified key.

    Parameters

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

    myVault.remove

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

    Parameters

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

    myVault.removeGlobal

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

    Parameters

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

    myVault.contains

    Determines whether the myVault dictionary contains the specified key

    Parameters

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

    myVault.containsGlobal

    Determines whether Global myVault dictionary contains the specified key

    Parameters

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

    Properties

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

    Datasource

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

     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:

     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:

    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.

    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.

    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.

    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.

    getWorkflowVariables()

    Returns array of workflow variables. No parameters.