@kissflow/lcnc-sdk-js

JavaScript SDK for developing over the Kissflow LCNC platform


License
MIT
Install
npm install @kissflow/lcnc-sdk-js@1.2.3

Documentation

Kissflow Lowcode JavaScript SDK

JavaScript SDK for developing over the Kissflow lowcode platform

Use as an npm module

Install the SDK as a module: npm i @kissflow/lowcode-client-sdk Then import into your project:

import KFSDK from "@kissflow/lowcode-client-sdk";
let kf;
(async function () {
	kf = await KFSDK.initialize();
})();

Note: Initializing Kf SDK in custom components returns a promise.

Use as a <script> tag directly in HTML

SDK can also be loaded directly into HTML by adding:

<script src="https://unpkg.com/@kissflow/lowcode-client-sdk@latest/dist/kfsdk.umd.js"></script>

Then SDK can be initialized as:

let kf;
window.onload = async function () {
	kf = await window.kf.initialize();
};

User and Account details

Details of authenticated user can be accessed as following

const { Name, Email, _id } = kf.user;

And account id can be accessed as kf.account._id

Fetch Api through sdk

Fetch any other kissflow api & external api using this method. kf.api has header tokens by default for making authenticated kissflow api calls

Note: This method has a limit of 10 seconds for an api call

kf.api(url, config).then((res) => {...})
// or
let resp = await kf.api(url, config)

Table of contents

1) Context

Context methods are polymorphic, it has different classes pre-initialized based on execution context.

Custom component

kf.context returns a CustomComponent class while using inside custom component. Custom component supported methods:

a) Watch Params

Listens for changes in parameter given to custom components in lowcode application.

kf.context.watchParams(function (data) {
	console.log(data);
});

Kissflow Forms

kf.context returns a Form class when it is used inside a kissflow's form that could be either Process, case or Dataform & it has following supported methods

a) getField()
Description:

Use this function to get the current value of a form field

Syntax:
kf.context.getField(fieldId).then((res) => {...})
// or
let value = await kf.context.getField(fieldId)
b) updateField()
Description:

Use this function to get update any field in the form

Syntax:
kf.context.updateField({ fieldId_1: fieldValue, fieldId_2: fieldValue });
c) toJSON()
Description:

Use this function to get the JSON data of the current form

Syntax:
const json = await kf.context.toJSON();
Output:
{
    "Untitled_Field": "testing",
    "_created_at": "2022-03-01T03:04:09Z",
    "_flow_name": "form events",
    "_id": "Pk4_T1WGWuMe",
    "_modified_at": "2022-03-01T03:04:09Z"
}

Form Table

kf.context.getTable(tableId) returns a Table class which has the following methods

a) addRow()

Description:

Appends row details to the table.

Syntax:
const table = kf.context.getTable(tableId);
table.addRow({ columnId1: value, columnId2: value });
Note: If there are more than one rows to be added to table then use addRows() instead for these bulk operations

b) addRows()

Description:

Appends multiple rows details to the table.

Syntax:
const table = kf.context.getTable(tableId);
let accumulator = [];
someArrayOfObjects.forEach(function (rowDetail) {
	accumulator.push({
		columnId1: rowDetail[columnId1],
		columnId2: rowDetail[columnId2]
	});
});
await table.addRows(accumulator);

c) deleteRow()

Description:

Deletes a row from the table based on the row id

Syntax:
const table = kf.context.getTable(tableId);
await table.deleteRow(rowId);
Note: If there are more than one rows to be deleted then use deleteRows() instead.

d) deleteRows()

Description:

Deletes multiple rows from the table based on given array of strings.

Syntax:
const table = kf.context.getTable(tableId);
await table.deleteRows([rowId1, rowId2, rowId3]);

e) getRow()

Description:

Use this function to perform form actions on any row inside a child table

Syntax:
const table = kf.context.getTable(tableId);
const row = table.getRow(rowId);
Output:

Returns an instance of TableForm class

f) getRows()

Description:

Gets all the rows of the table

Syntax:
const rows = await kf.context.getTable(tableId).getRows();
Output:

Returns an array of TableForm instances

g) toJSON()
Description:

Use this function to get the JSON data of the child table

Syntax:
const json = await kf.context.getTable(tableId).toJSON();
Output:
[{
    "Untitled_Field": "row 1",
    "_created_at": "2022-03-01T03:04:09Z",
    "_flow_name": "form events",
    "_id": "Pk4_T1WGWuMe",
    "_modified_at": "2022-03-01T03:04:09Z"
},{
    "Untitled_Field": "row 2",
    "_created_at": "2022-03-01T03:04:09Z",
    "_flow_name": "form events",
    "_id": "Pk4_T1WGWuMe",
    "_modified_at": "2022-03-01T03:04:09Z"
}]

Table Row

A single row inside a table is known as Table row kf.context returns a TableForm class which has the following methods

a) getField()
Description:

Use this function to get the value of the table row

Syntax:
kf.context.getField(fieldId).then((res) => {...})
// or
let value = await kf.context.getField(fieldId)
b) updateField()
Description:

Use this function to get update any field in the table row

Syntax:
kf.context.updateField({ fieldId_1: fieldValue, fieldId_2: fieldValue });
c) getParent()
Description:

Use this function to perform form actions on the main form

Syntax:
const mainForm = kf.context.getParent();
mainForm.updateField({ fieldId_1: fieldValue, fieldId_2: fieldValue });
Output:

Returns an instance of Form class using which we can perform any action on the main form

d) toJson()
Description:

Get JSON output of table row

Syntax:
const json = await kf.context.toJSON();
Output:
{
    "Untitled_Field": "testing",
    "_created_at": "2022-03-01T03:04:09Z",
    "_flow_name": "form events",
    "_id": "Pk4_T1WGWuMe",
    "_modified_at": "2022-03-01T03:04:09Z"
}

2) Client

Show Toast
kf.client.showInfo(message);
Show confirm

Displays the confirmation dialog, and returns users's action as a response

kf.client.showConfirm({ title, content }).then((action) => {
    if(action === "OK") // user clicked ok button

    else // user clicked cancel button or clicked outside the popup
})
Redirect to URL
kf.client.redirect(url);

3) Application

kf.app represents the active kissflow app and kf.app._id returns its id.

Get value to application variable
const appVarible1 = await kf.app.getVariable("variableId");
Set value of application variable
let value = await kf.app.setVariable("variableId", value);
// or
await kf.app.setVariable({
	variableId_1: "value_1",
	variableId_2: 3345
});
Open a page

openPage(id) returns Page class instance

const pageInputParameters = {
	param1: value,
	param2: value
};
kf.app.openPage(pageId, pageInputParameters);
// Note: Page Input parameters are optional.
Get a dataform instance

getDataform(formId) returns a Dataform class instance

const dfInstance = kf.app.getDataform("dataform_id");

4) Page

kf.app.page returns the active page opened inside application and kf.app.page._id returns its id.

Page parameters
let value = await kf.app.page.getParameter("parameterId"); // for retreiving single parameter

Get all page parameters

let allParams = await kf.app.page.getAllParameters();
// returns an object
{
    parameterName: "Sample value",
    parameterName2: "Sample value 2"
}
Access a Component

getComponent returns a Component class.

const componentName = await kf.app.page.getComponent("componentId");
Open a popup

openPoup returns a Popup class.

kf.app.page.openPopup("popupId", { inputParam1: "value" });
// Note: Popup parameters are optional.

5) Component

getComponent(id)

Parameter: Component's Id Returns: Component class instance

const component = await kf.app.page.getComponent(componentId);
Standard Component Methods
component.refresh(); // Refreshes the component
component.hide(); // Hides the component
component.show(); // Shows the component if it's been hidden previously
Component Specific Methods
5.2.0) Component onMount

Component onMount takes in callBack function as argument.

Note: Any component specific methods that are used on Page load must be called inside component's onMount event.

Parameter: function

component.onMount(() => {
	// function logic goes here... For eg.
	// component.setActiveTab(2)
});
5.2.1) Tab component
1) setActiveTab

Sets specified tab as active. Parameter: Tabs' Number (Starts from 1 to N)

component.setActiveTab(2); // sets 2nd tab as active one

6) Popup

kf.app.page.popup returns the active popup instance opened inside the page and its id can be accessed via kf.app.page.popup._id And kf.app.page.getPopup(id) returns this popup class instance.

Popup parameters
let value = await kf.app.page.popup.getParameter("parameterId"); // for retreiving single popup parameter

Get all popup parameters

let allParams = await kf.app.page.popup.getAllParameters();
// Returns an object
{
    parameterName: "Sample value",
    parameterName2: "Sample value 2"
}
Close popup
kf.app.page.popup.close(); // for active popup
// or if you already have a popup instance...
greetPopup.close();

8) Dataform

Note: Get dataform instance from kf.app.getDatform

Import CSV

Opens up the import CSV modal where user could upload CSV file and map respective columns to the field.

let defaultValues = { fieldId: "value" };
dataformInstance.importCSV(defaultValues);
Example scenario

Consider scenario where few fields that aren't exposed to user(basically hidden in form visibilty). In such cases Default values can be used to provide data to hidden fields

// Here the location field is hidden to user,
// thus user isn't aware to include this on import csv.
let defaultValues = { location: "India" };
dataformInstance.importCSV(defaultValues);

Note:

  1. Default values here is optional
  2. Any variables or parameter can also be mapped in defaultValues.
  3. End user can't pass this value if default value is set by dev.
  4. Some fields cannot be set as default eg. Auto calculated fields, Sequence numbers etc.

7) Formatter

Format to KF Date
kf.formatter.toDate("08-24-2021").then((res) => {...})
// or
let value = await kf.formatter.toDate("08-24-2021");
Format to KF Date Time
kf.formatter.toDateTime("2021-08-26T14:30").then((res) => {...})
// or
let value = await kf.formatter.toDateTime("2021-08-26T14:30");
Format to KF Number
kf.formatter.toNumber("1,00,000.500000").then((res) => {...})
// or
let value = await kf.formatter.toNumber("1,00,000.500000");
Format to KF Currency
kf.formatter.toCurrency("1,00,000.500000", "USD").then((res) => {...})
// or
let value = await kf.formatter.toCurrency("1,00,000.500000", "USD");
Format to KF Boolean
kf.formatter.toBoolean("yes").then((res) => {...})
// or
let value = await kf.formatter.toBoolean("yes");
Other supported Boolean values
let value = await kf.formatter.toBoolean("1");
let value = await kf.formatter.toBoolean("true");
let value = await kf.formatter.toBoolean("no");
let value = await kf.formatter.toBoolean("0");
let value = await kf.formatter.toBoolean("false");