Developing a custom action for Kaizala

Kaizala custom action - banner

Kaizala ships with many actions out of box allowing you to get work done within the context of a conversation / group [read more]. Few of them are surveys, quick poll, request location, announcement, etc. But there could be a case(s) where these are not sufficient for your business / requirements and you may want to build your own action. Kaizala platform allows you to extend the client side functionality through custom actions (or cards). There are 2 ways you could create a custom action:

  1. Customizing templates present in Kaizala management portal (demonstrated in Part A of this post)
  2. Build / code a custom action

In this post we would be exploring option #2 – Building a custom action! 

Before we begin building a custom action, we will need to understand what an action / card is composed of, few concepts around the flows and various screens in a card (called views), the life-cycle of an action. As a pre-requisite, I would recommend you have played and are familiar with few actions that are shipped out-of-box with Kaizala – atleast survey and announcement. Below are the sections into which this post is organized into:

  1. Overview of custom action progammability
  2. Action card screen flows
  3. Components of an action package
  4. Action package life-cycle
  5. Building a custom action
  6. Testing and debugging
  7. Publishing an action

Lets get started!

Overview of custom action progammability

Kaizala platform provides developer an action package SDK (called KASClient.js) – which is a javascript library that abstracts out platform specific functionality and provides a way to interact with the underlying Kaizala runtime. The developer could build a custom action in HTML / JS / CSS by calling into the SDK. A custom action is a zipped bundle of few HTML/JS/CSS files, manifest files and KASClient.js – the action package SDK (more details in section to follow). Below picture gives an idea of where the custom action fits in and its interaction.

Action card interaction-3

Legend:

  • Blue blocks – provided by / part of Kaizala platform
  • Blue arrows – implicit actions, that happen subsequently as a consequence of a call from / to the SDK
  • Yellow block – action package
  • Orange blocks – files handcrafted / coded by developer
  • Orange arrow – calls made by developer’s code into SDK

Action card screen flows

An action / card has a couple of screens / views of which some are mandatory while others are open to the customization by the developer. Below are the list of views in a card:

  1. Discover view
  2. Creation view
  3. Chat canvas card view
  4. Response view
  5. Response results view

For showcasing the different views, I have picked the out-of-box survey action.

Discover view

Discover view is not a view actually but just the entry point to the action. It mainly consists of the icon, display name and description and appears in the palette and discover screen. Below screenshot gives an illustration. The configuration / customization options for a developer for this view are the 3: icon, displayName and description that get into the package manifest (package.json) file.

Survey discover view

Creation view

Creation view is launched by tapping on the action either from the palette / “try this action” from the discover screen.

creation view - launch points

Below is a screenshot of survey action’s creation view where user is asked for the title, description of the survey. Filling these details and submitting creates a survey in the group. This view can be developed using HTML / JS / CSS.

survey creation view

Chat canvas card view

The chat canvas card view is the card that appears on the group when a card / form is submitted. Below is a screenshot of the survey chat canvas card view. The survey chat card is a native view and can be customized using a declarative JSON schema (detailed here).

survey chat card - 2

Response view

Response view is the view that comes up on tapping the respond button on the chat card. In the survey example, it brings up the view that takes in the response for the survey. Below screenshot shows the survey response view. Response view can be customized / developed in HTML / JS / CSS.

survey response view

Response Results view / Summary view

The response results view / summary view comes upon tapping the chat canvas area of the chat card view. In the survey example, it brings up a view that shows the response count and ways to drill down to the responses. Below is a screenshot that shows the survey results view. Response results view can be customized / developed in HTML / JS / CSS.

survey results view

The creation view, response view and response results view are also called as immersive views.

Components of an action package

An action package is a zip file that contains package manifest file – package.json, KASClient.js, html view(s) and resources.

package.json

The package.json is the package manifest file that has the configuration details for the action package and should be in the root folder of the action package. This file is mandatory without which package upload would fail. The package manifest schema has been documented here. Below screenshot gives an example of package.json file.

sample package

App Model file

App model contains the question / answer model, properties and settings corresponding to the card. Like, the data you would like to capture while an user responds using the card. The developer could choose the name of the app model file but has to be specified in package.json. The schema for app model file can be found here. Below is a sample app model file.

appmodel sample

Action package SDK / KASClient.js

The action package SDK / KASClient.js file also needs to be a part of the action package. The methods / functionalities exposed by the SDK would be consumed by the immersive views (creation / response / response results views) and would be translated to native platform specific calls by the Kaizala runtime. The SDK could be downloaded from https://manage.kaiza.la/MiniApps/DownloadSDK. The Microsoft documentation for KASClient.js can be found here.

Action package life-cycle

An action package has 5 states: Draft, Staged, Active, Inactive, Removed.  Below diagram shows the interactions / operations that takes an action package across the various states.

action package lifecycle

Significance of various states

  1. Draft: cannot be used / associated to any group.
  2. Staged: A state for testing and debugging purposes. Can be associated to a group, but will show up with [STAGED] labeling.
  3. Active: At this stage action package is ready for consumption / in production
  4. Inactive: A state where action package cannot be associated with any new groups. (the package will continue to work in the groups where it has already been associated with)
  5. Removed: at this state, the action package will cease to exist in all the groups with which it was associated earlier and will also not be available for association with any other groups. You will not be able to re-activate it either.

Building a custom action

To build a custom action, you will need an editor. Notepad would do, Visual Studio works great. In the interest of keeping this post brief, I will not get into the details of building an action. You can follow this tutorial present on Microsoft documentation to get started with building your own custom action. It takes you step by step from creating the package manifest and app manifest to creating the various views as well as publishing the action using the Kaizala management portal.

Testing and debugging an action

In order to debug an action package, it needs to be in the staged state. Debugging is possible using the chrome web tools debugger for the immersive / HTML views. Pre-requisites: Windows PC with a chrome browser and an android phone with Kaizala installed and part of the group where the action package is associated and in staged state. Open the view you want to debug and navigate to chrome://inspect/#devices in Chrome browser. The view you want to debug should be listed there. Click on inspect from the list of pages.

For details refer the documentation here.

Hope that was helpful. If you need more details / anything is unclear, feel free to let me know through the comments. Thank you for reading!

27 thoughts on “Developing a custom action for Kaizala

  1. The package.json is a mandatory file and should be present in the root of the action package zip file. The typical errors we have seen are:
    1) The package.json is inside a folder (the files need to be zipped to create the action package and not the folder containing these files).
    2) package.json file name is case sensitive.

    Can you check and confirm its not one of these?

    Like

    1. Hello, I have a folder having 4 files (appModel.json,CreationView.html,KASClient.js,package.json) .I have zipped this folder and imported the zip file. but its throwing the erroe like package.json file is missing. Please let me know, what i am missing here

      Like

  2. Following on this, I have managed to create a custom action .but when i am clicking try this action option in kaizala app,kaizala app is stopping . how to resolve this .please help.

    Like

  3. Hello Gladson
    We are trying to integrate HTML page with custom action card.
    The HTML page will in turn fetch data from CRM and user will be allowed to do certain operations on it.

    Like

  4. var TOTAL_PAGES = 1;
    var SHOW_SUBMIT_IN_HEADER_SINGLEPAGE = true;
    var MAX_ATTACHMENT_COUNT = 4;

    Hi,
    If I have to submit a button on the third page and this single page has to break in three pages so what should I do?

    Like

  5. After following the steps on the documentation for debugging the Kaizala Action Card. When I try to view the contents of the KASForm on my local machine, It keeps stating that the KASClient is not defined. Is there anything else I am supposed to be doing to solve this problem?

    Like

  6. Hi there,
    I’ve been trying to debug my Kaizala action card for some time now.
    I followed the steps on the documentation, set up a python server to serve my files, set up my android phone so it reads from my local machine and not from kaizala.
    However, when I try to view the contents of a KASform for example, I get an error, “KASClient is not defined” and my KASClient is referenced in my HTML head. Is there anything else I need to do?

    Like

Leave a Reply to Annie Rizvi Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s