This section provides an detailed documentation of the utilities functions for integrating workflows APPs with TOQIO platforms. These functions offer greater flexibility, enabling more dynamic and customisable connections with your data.

All functions can be utilised by workflow designers within the Workflow editor. Below, you will find code snippets demonstrating how to implement them in expressions for seamless integration.

Store

Store functions are specifically used for storing and sharing data between different parts of the workflow. They do not involve any logic beyond saving objects, arrays, or other necessary information. Think of them as a session storage mechanism, where a key is used to retrieve specific data and/or data is inserted or associated with that key.

They would be accessible from the store object.

Navigation

Toqio uses React Router for screen navigation. However, when navigating from a Workflow screen, the default behaviour relies on href links, causing a full page refresh and impacting performance. To improve this, dedicated navigation functions allow seamless routing between Workflow screens and Toqio screens using React Router navigation instead.

These functions are accessible via the navigation object.

Navigate

• url： The Toqio CORE route to navigate to.
• params ：Parameters to pass along with the navigation.

Parameter

• sameApp: determines whether window.open is used instead of React Router navigation:
  • sameApp: true: used for navigation between different WF routes inside the same WF app.
  • sameApp: false (or not defined): used when navigating:
    • Between different WF apps.
    • Between WF and Toqio CORE routes.

Replace

• extraUrl: the additional path to append, including necessary query parameters.
• params: The parameters to include in the navigation URL.

Secondary navigation application Routing

For applications used in secondary navigation (which normally appears when a user selects a primary/top-level navigation item), additional parameters are required to ensure the correct path rendering:

• currentAppId: The ID of the app.
• currentPageId: The ID of the page.

This transforms the URL into: ...#/${currentAppId}/${currentPageId}/${extraUrl}

Set query params

• queryName : the name of the query.
• queryParams the parameters (e.g., filter values) that will be encoded and added to the URL.
• existingParams : additional parameters for completing the URL.

Secondary navigation application Routing

For applications used in secondary navigation (which normally appears when a user selects a primary/top-level navigation item), the required parameters typically include:

• currentAppId: The app ID
• currentPageId :The page ID.

This transforms the URL into: ...#/${currentAppId}/${currentPageId}/?${queryName}=${encodedQueryParams}

Example:

{{navigation.setQueryParams("search", queryParams, routeParams)}}

queryParams y routeParams are the following:

• routeParams (expression) -> {"currentAppId": "AFT", "currentPageId": "custom-methods"}
• queryParams (expression) -> {"date": "2025-02-01"}

When clicking the button, the current url will be changed from

/work/app-for-testing#/AFT/custom-methods

to

/work/app-for-testing#/AFT/custom-methods/?search=%7B"date"%3A"2025-02-01"%7D

Get query params

url: the URL from which query parameters will be extracted.

Files

This section provides functions for managing files, including downloading, encrypting, and handling file-related operations efficiently.

Download base64 file

• File will be the base64 file get on the endpoint response of back end.
• fileName will be the text to show on the file with the date. If you send “file-name”, it will generate a file name called “file-name-1309.pdf”.

Download blob file

• response will be the blob response get on the endpoint of back end.
• fileName will be the text to show on the file with the date. If you send “file-name” it will generate a file name called “file-name-1309.pdf”

Download file from Toqio

• documentKey: The unique identifier of the file stored in Toqio.
• documentName: The desired name for the downloaded file. The generated file name will include the current date (e.g., "file-name-1309.pdf" if "file-name" is passed).
• customerId: The ID of the customer in Toqio.
• merchantId: The ID of the merchant in Toqio.

Utilities

This section provides helper functions for handling objects and arrays efficiently. These functions enable easy data manipulation, such as removing specific keys or values and filtering data based on matching parameters. This can be used when building filter functionalities.

Remove by key

• options: An object containing various properties.
• key: The property to be removed from the object.

Example:

Input

const option = {
  "status": "ACTIVE",
  "name": "Random"
}

Output

const result = customMethods.removeByKey(options, "status")
console.log(result)
{
  "status": "ACTIVE"
}

Remove by value

• options will be an object of options
• value will be the value of the key to be removed

Example:

const options = {
  "ACTIVE": false
  "PENDING": false,
  "FAILED": true
}

Output

const result = customMethods.removeByValue(options, false)
console.log(result)
{
  "FAILED": true
}

Find all by params

• data will be an array of options
• key will be the key to filter the array with
• values will be the values that should match with the key values to filter them

Example input

const options = [
  { categories: ["accountant", "entretainment", "petrol", "others"] }
]

Example output

const result = customMethods.findAllByParams(options, "categories", ["accountant", "others"])
console.log(result)
[
  { categories: ["accountant", "others"] }
]

Security

Encrypt data

• publicKey: A key retrieved from the backend endpoint for encryption.
• data: The text to be encrypted, such as a security code, OTP, password, etc
• id: The ID of the currently logged-in user.

Encrypt with public key

⚠️

This encryption utility should be used in any action in the SME portal that requires secure handling of sensitive data—such as providing a security code when initiating a new payment.

• userId (required)(string): The ID of the currently logged-in user.
• publicKeyData (required)(object): Contains the following properties, which are required for data encryption:
  • keyId: The identifier of the public key.
  • publicKey: The actual public key to be used for encryption.
    These values should be retrieved from an endpoint such as /iam/security/users/:userId/publicKeypair. If invalid or incorrect values are provided, the encryption utility will fail.
• dataToEncrypt (required)(string | array): The data to be encrypted. This may be a string (e.g., a security code) or an array of strings.
• dataType(string): Specifies the type of data being encrypted. Accepted values are:

  • "SECURITY_CODE" (default)

  • "BIOMETRICS"

    If not explicitly set, this field will default to "SECURITY_CODE".

Example:

{
    "userId": userId // received userId in params
    "keyId": publicKeyData.keyId, // received publicKeyData object keyId in params
    "dataType": dataType, // received dataType in params (by default "SECURITY_CODE")
    "encData": "...",
    "encAesKey": "...",
    "tag": "...",
    "iv": "..."
}

Toqio

This section provides functions related to specific TOQIO core functionalities.

Get categories

Get a list of predefined categories, that can be later used to categories transactions or expenses.

⚠️

This function is only available in SME

• code: The category code used for matching.
• name: The untranslated category name. (For translations, refer to the categories endpoint in the backend.)
• icon:The name of the icon associated with the category.
• color: The color assigned to the category icon.
• backgroundColor: The background color assigned to the category icon.