These are not actually pre-requisites, but good to have understanding before you jump into developing custom actions for Kaizala.
- Introduction to Kaizala Extensibility
- Developing a custom action for Kaizala
- Exploring Kaizala card view scenarios
In this post, we will develop a feedback card where we will have 2 questions: a rating (1-5) and a verbatim feedback text. Let’s say we have 2 users: user A sends the survey / card and user B responds to the survey.
As shown in the picture above, it involves 3 flows:
- Creation flow – where user A sends / creates the survey
- Summary flow – where user B sees his response
- Response flow – where user B responds / edits his previous response
We will be calling particular APIs in the SDK (KASClient.js) to achieve these.
Developing Feedback card
To develop the feedback card, we will need to provide the following files in a zipped package:
- Action package SDK – KASClient.js
- Question / answer model – AppModel.json
- Package manifest with view definitions – package.json
- Create the various views required
- Creation view
- Response view
- Response results view
Action Package SDK
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.
Question / answer model
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. Below is the app model file for our example.
The developer could choose the name of the app model file but has to be specified in package.json. In this example, we have kept it as AppModel.json. The schema for app model file can be found here.
Package manifest with view definitions
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 is the screenshot for the example package.json file.
(in the interest of keeping the post short, will explain the fields in the package.json in a separate post)
Creating the various views
In order to have the creation flow, response flow and summary flow – we will need to have the corresponding views (html / js) files. In the package.json screenshot above, you will notice that we have defined the file CreationView.html to host the creation flow, ResponseView.html to host the response view and SummaryView.html to host the summary view. These views will call into select APIs in KASClient.js to achieve / build the scenario. Below screenshot gives a gist of what we will be doing.
In the creation view, we will need to get the instance of the form, set a few fields (expiry and title in this example) in the form and then submitFormRequest to create a survey / card instance. This will result in a card being shown on the chat canvas allowing user to respond to the survey.
The HTML part of the creation view has fields for the title and a button to create the card / survey (shown below).
In the response view, we will query for the response of the user. In this example, we allow editing of the previous response if the user had already responded.
- Querying for user’s response is done by calling getMyFormResponsesAsync API
- In order to submit a form response, we will need to build a json that will contain the question to answer map
- Finally, submit the user’s using sumbitFormResponse API (** notice the spelling of sumbit in sumbitFormResponse!).
In the summary view, we will query for the form summary to show all the responses / feedback.
Code snippet to fetch the summary:
- Microsoft documentation for getting started with actions [link]
- The KASClient APIs for the various flows have been documented at:
- The objects used in the SDK have been documented here.
- Sample packages and KASClient SDK download location [link]
I hope that was helpful to get a basic understanding on developing a request-response type of Kaizala action. The package for the card developed in this example has been shared here. Please share your comments, feedback / any questions you may have through the Contact page.