A Sample for Developers: Add-on for API Connection with kintone

I made an Add-on for kintone connection, using a scheme of self-made of Add-ons. (This article is oriented for developers.)


Questetra Ver.11.1.0, which was released the other day, allows you to install self-made Add-ons.
* See the following User manual page on how to create an Add-ons.
M416 AUTOMATED STEP Create your own Auto-Step for Business Process Definition


I made a sample of an Add-on to connect with kintone of Cybozu, Inc., using that method, and I would like to introduce it to you.
Although several examples about connection with kintone have been published in articles in Workflow-sample, I summarized the contents of the settings in “Throwing Message Intermediate Event (HTTP)” into an add-on so that it could be easy-to-understand.

* This sample add-on is intended for developers who are familiar with the specifications of kintone APIs.
* I did not include the part to generate send-data with JSON data and request parameter into the add-on, since it varies according to the application setting of kintone.


You are required to configure the following items of “Throwing Message Intermediate Event (HTTP)” to connect with kintone.

  • Network Setting: Access URL
  • Network Setting: HTTP Method
  • Security / Custom header: custom Header
  • Send Parameter Setting: (If specifying with Request parameter)
  • Request Body: Process Data Item to be sent as Request Body (If specifying with JSON data)
  • Request Body: Content-Type of Request Body (If specifying with JSON data)

Also, you should configure the following items even though these are not mandatory.

  • Network Setting: String type data item that will contain error details when an error occurs
  • Response Setting: Data item to save the response

I have created an add-on that has a property screen containing items which have been narrowed down to the ones necessary.

The following is the image of the property screen.
Setting examples in the above image are:

  • API URL: Specify which API to call by URL
  • HTTP method: Specify either of “get”, “post”, “put”, “delete”, for which HTTP method to use
  • API token: Specify the value which has been specified for “X-Cybozu-API-Token” in HTTP header
  • JSON data(post/put)/request parameter(get/delete): Select either “String type Data Item (multiple lines) to store JSON data” or “String type Data Item (single line) to store a Request parameter”, to send to kintone
  • error data: Select a String type Data Item (multiple lines) to store the error details when an error occured
  • response data: Select a String type Data Item (multiple lines) to store the response from kintone
* Concerning HTTP method, you are required to type them in because it is impossible to create a setting item to select from options determined in advance in the current specification. It is supposed to be improved in future upgrades.
* Regarding JSON data / Request parameter, it requires JSON data if HTTP method was post/put, Request parameter if get/delete.]
* Regarding Content-type, I have excluded it from setting items since it will be fixed according to the HTTP method.


And I also created an icon.

* I created the right-bottom part by base64 encoding on a square image (you will find a web page that converts it for free), as described in the User Manual page for self-creating add-ons.


The Process Model Diagram below is created by substituting the “Throwing Message Intermediate Event (HTTP)” with this add-on, in the Workflow sample “Episode 484: Addition of New Client via kintone API“.


The following is the add-on XML.

<?xml version="1.0" encoding="UTF-8"?>

  <label>kintone Connect</label>
  <label locale="ja">kintone 連携</label>

    <config name="api_url" required="true">
      <label>API URL</label>
    <config name="method" required="true">
      <label>HTTP method(get/post/put/delete)</label>
    <config name="api_token" required="true">
      <label>API token</label>
      <label locale="ja">API トークン</label>
    <config name="send_data" required="true" form-type="SELECT" select-data-type="STRING_TEXTFIELD|STRING_TEXTAREA">
      <label>JSON data(post/put)/request parameter(get/delete)</label>
      <label locale="ja">JSON データ(post/put)/リクエストパラメータ(get/delete)</label>
    <config name="response_data" form-type="SELECT" select-data-type="STRING_TEXTAREA">
      <label>response data</label>
      <label locale="ja">レスポンス データ</label>
    <config name="error_data" form-type="SELECT" select-data-type="STRING_TEXTAREA">
      <label>error data</label>
      <label locale="ja">エラー データ</label>


var errorMsg = '';

try {

  var url = configs.get("api_url");
  var method = configs.get("method");
  var api_token = configs.get("api_token");
  var send_data = data.get(configs.get("send_data"));

  if (method == "post") {
    var response = httpClient.begin()
      .header("X-Cybozu-API-Token", api_token)
      .body(send_data, "application/json")
  } else if (method == "get") {
    var response = httpClient.begin()
      .header("X-Cybozu-API-Token", api_token)
      .get(url + "?" + send_data);
  } else if (method == "put") {
    var response = httpClient.begin()
      .header("X-Cybozu-API-Token", api_token)
      .body(send_data, "application/json")
  } else if (method == "delete") {
    var response = httpClient.begin()
      .header("X-Cybozu-API-Token", api_token)
      .delete(url + "?" + send_data);

  if (response.getStatusCode() != 200) {
    throw new Error("status code is not 200. code:" + response.getStatusCode());
  } else {
    var responseText = response.getResponseAsString();
    retVal.put(configs.get("response_data"), responseText);

} catch(e) {
  errorMsg = e.message;

retVal.put(configs.get("error_data"), errorMsg);




Download Add-on XML here:

* Please see this Manual page on how to install add-ons.
M415 AUTOMATED STEP Adding an Auto-Step to be Used for Business Process Definition


You are able to create add-ons that are specialized for specific kintone environments, applications, or processing, by extending this method. Consider what to include in an add-on according to its purpose.


About Kusaka Tsuyoshi

View all posts by Kusaka Tsuyoshi

Prev article - 50. Questetra Tips How to do Multilingual Support of a Process Data Item Name in the Input Screen?
Next article - 50. Questetra Tips How to Upload and Download Files to and from kintone
Another article - Kusaka Tsuyoshi Several Ways to Manage Master Data with Questetra