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.
kintone_qbpms_send
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.
config_kintone_addon2
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.
icon_kintone_addon

* 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“.
diagram

 

The following is the add-on XML.

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

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

  <configs>
    <config name="api_url" required="true">
      <label>API URL</label>
    </config>
    <config name="method" required="true">
      <label>HTTP method(get/post/put/delete)</label>
    </config>
    <config name="api_token" required="true">
      <label>API token</label>
      <label locale="ja">API トークン</label>
    </config>
    <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>
    <config name="response_data" form-type="SELECT" select-data-type="STRING_TEXTAREA">
      <label>response data</label>
      <label locale="ja">レスポンス データ</label>
    </config>
    <config name="error_data" form-type="SELECT" select-data-type="STRING_TEXTAREA">
      <label>error data</label>
      <label locale="ja">エラー データ</label>
    </config>
  </configs>

  <script><![CDATA[

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")
      .post(url);
  } 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")
      .put(url);
  } 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);

  ]]></script>

<icon>
iVBORw0KGgoAAAANSUhEUgAAAC8AAAAvCAIAAAD8RQT7AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAALjSURBVFhH7Zg9aFNRGIbv5OYk4uAoCA4uQkEEHVxcHcRB3Lo4iEOdhErRwUVwchOHgCAuguAgglqtf01NY1uNtjZNbLGNtMafxCY1P6/vd3NSknPvSe6N98YO9+UlhHDO9z335JzznXMtbCVFNGZFNGZFNGb5p6nk8e0BMsOYHUTqpDh7CSsxlBaAmmrTq/zQ1Dfw9Tamj+KFhcftfmZhYjeWrkmz2jp+vkIuhuUb+JWQXp7lh4bJnjg4NJP1Zfsv49uRf4RaSQXpKG80Mip32nL4Mp8hfV7GrJu80azexWtHDl8m0JfrKppZHmgqa0gO6NF7cHwX1udUTIMcNFwaXCbPmyE4YZMH8bQlaM/mTM/dUlkMatLUqyjO4P1xPUSA5p/1+YpKZ5BNw0nKNflmr94/cE8dEaCFC8qLV7F2HxvLNonIphGUPXrPMMzhad0j+J1TgvNp7kxjStk08+faGvXfYxY+nEI5a6G89B9QmFHWxwAyI7JfN7cizvOY3jRscyS4GeYfolpoQGzKkvqntQ7VXOfMyD3MTZbMIK1DqB7fhuI7ldwhC/NDeodQPWrhx5hK7pAldV/rELZZ0g3imsr2e011oqHeHtI7hGc++fdRO7WLGnvxRDBV2ot5+Cqm7NQusmm4+aze089sIXnmGP7k7NQusmkoFk4WsKnDeudgzaokZy7jYb5JI6qhvIjMRT1EUOaM+XS2tWI71UpjixNeixKUE/s7o1AOGtaOwBc8A8Z3SnnuJgcNFeyxi4uI17/CtAreUW40KzcDG570kKxnzxc8NxoekOM79Lg9mCuo20TR5EZD8QL1L9sPS+PkgQ57rkkGmnpFrtzO+7bTvH7PDiKxTxpzMPhJjuxl2Sz8vyQw0FC80/CMmDohD6oRNMzfP55GIYnab5TS0pgVhp8sw37eBLTKTNMQL3s8cnCP5vFxk4NjQA5e1SRxVbUMQt1o+quIxqyIxqyIxqytRAP8BYs4RplP1leeAAAAAElFTkSuQmCC
</icon>

</service-task-definition>

Download Add-on XML here:
kintone-addonxml

* 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

Recommendations
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 Single Sign-On with Salesforce using SAML 2.0 (as of February, 2015)

Archive

 RSS