Zenn
🔨

kintone と EDITROOM の機能連携の実例解説： 自作プラグインを利用した連携１―準備

2022/11/22に公開
HTML
JavaScript
kintone
editroom
tech

目次

はじめに

アップデイティットの毛利です。

先日、弊社から「EDITROOM」という BtoB 向けの文書作成クラウドサービスをリリースしました。
データの収集・検証から、文書作成・配布までの一連を自動化するだけでなく、REST API を用いたサービス連携の実現を目指しています。

本記事では、EDITROOM で提供する REST API 群とコールバック機能を用い、
kintone のアプリ上から自作プラグインを経由して文書を作成する、実例を紹介できればと思います。

前提知識

本記事は、主に kintone とプラグイン開発に視点を置いた記事を心がけます。
――ですので、EDITROOM を使用する箇所については、適宜自分の利用したいサービスに読みかえていただければ、幸いです。

また、作業量が少し多いため、何個かの記事に分轄します。ご承知おきください。

加えて、以下の知見を有していると読み進めやすいです。

  • JavaScript の知見がある方を想定読者とします。
    • 最低限、ソースコードに手を入れる作業ができること。
  • REST API の使い方
    • cURL や Postman で触ったことがあれば尚良し

前提条件・準備

  • kintone アカウント
    • 本番適用のためには、プラグインを導入できる権限を持ったアカウントが必要です。
    • また、サンドボックス的環境の提供として、開発者ライセンスというのが存在します。
  • EDITROOM アカウント

また、一部は公式の解説と内容が重複するため、予め公式ドキュメントに目を通しておくと良いです。

作業

全体のユースケース

次の一連の動作を動かせるようにしてみます。

  1. 該当アプリから、レコードを指定して文書生成を発火する
  2. 自作プラグイン上で、EDITROOM API の発火に必要なパラメータを取り出す。
  3. 自作プラグイン上から、 EDITROOM に文書作成 API を発火する。

本記事中の作業範囲

  • ベースになるプラグイン環境の用意する。
  • 設定値周りをまっさらな状態にして、プラグインをアップロードする。
  • アプリ上で、動作確認をする。

開発環境の準備

1. create-plugin による初期設定

筆者環境は以下の通りです。

  • Windows 11 (note-pc)
    • PowerShell Core V
      • v 7.3.0
      • また、WSL/WSL2 は今回使いません。
    • Nodejs (on PowerShell)
      • v 18.12.1
      • nvm でバージョン切り換えをできるようにしています
    • @kintone/create-plugin
      • 執筆時点で、@5.1.20 でした。
    • VS code
      • お好みの IDE／エディタをお使いください。

まず、開発環境を整備します。CLI 上で以下のコマンドを入力すると、それ以下の質問が表示されますので、回答して進めてください。

npx @kintone/create-plugin kintone-editroom-plugin

? プラグインの英語名を入力してください [1-64文字] kintone-editroom-plugin
? プラグインの説明を入力してください [1-200文字] kintone-editroom-plugin
? 日本語をサポートしますか？ Yes
? プラグインの日本語名を入力してください 1-64文字
? プラグインの日本語の説明を入力してください 1-200文字
? 中国語をサポートしますか？ No
? プラグインの英語のWebサイトURLを入力してください (省略可)
? プラグインの日本語のWebサイトURLを入力してください (省略可)
? モバイルページをサポートしますか？ No
? @kintone/plugin-uploaderを使いますか？ Yes
依存ライブラリをインストールします

これでプロジェクトが作成されます。
（モバイルページのサポートや中国語対応については、今回は省略します。）

続いて CLI 上で次のコマンドを叩きます。

cd kintone-editroom-plugin
npm i

上記が完了した後、 VS Code で開くと、以下の画像のような状態になります。

いろいろ、環境を手直ししたいところですが、まずはこの素の状態をベースに進めます。

2. 設定画面系の全削除

「動作に必要な値で、かつアプリ管理者が設定したい」ものは、プラグインの設定画面とその JavaScript 操作を経由して設定できます。
今回は、EDITROOM API を発火するために必要な URL やパラメータが該当します。

プロジェクトを作成した初期状態では、config.html が設定画面の UI として機能し、config.js が設定値の保存処理を担っています。

見ての通り、仕組みは非常に単純です。

ですが、今回は最短で疎通させることを目指す為、まずは設定画面系を消し去ります。
実際の運用では、必要なパラメータはこの設定画面から入れる必要が出てきますが、今回はデモなので全て決め打ちとします。

config.html
<section class="settings">
  <h2 class="settings-heading">No Settings</h2>
</section>

コピペじゃなくて写経でも書けるコード量、簡単ですね。

さて、次は、config.js を修正します。
こちらは、初見ではおまじないだらけですが、ポイントになるのは次の 2 点です。

  • コード前半は画面が呼ばれた時の初期化処理。
    • kintone.plugin.app.getConfig から前に保存した値を保存するなどを実施してます。
  • $form.on('submit', function(e) {...} で実際に保存操作を実行したときの処理を行っています。
    • kintone.plugin.app.setConfig で新しい値に書き替えます。

――ですが、ここも全部処理を消します。

config.js
jQuery.noConflict();

(function($, PLUGIN_ID) {
  'use strict';
})(jQuery, kintone.$PLUGIN_ID);

次は、 desktop.js を修正します。
こちらも、初期状態の「meesage」があるため、まずはこれを消します。

desktop.js
jQuery.noConflict();

(function($, PLUGIN_ID) {
  'use strict';

  kintone.events.on('app.record.index.show', function() {
    var spaceElement = kintone.app.getHeaderSpaceElement();
    if (spaceElement === null) {
      throw new Error('The header element is unavailable on this page');
    }
    var fragment = document.createDocumentFragment();
    var headingEl = document.createElement('h3');
    var messageEl = document.createElement('p');

    messageEl.classList.add('plugin-space-message');
    messageEl.textContent = '';
    headingEl.classList.add('plugin-space-heading');
    headingEl.textContent = 'Hello kintone plugin!';

    fragment.appendChild(headingEl);
    fragment.appendChild(messageEl);
    spaceElement.appendChild(fragment);
  });
})(jQuery, kintone.$PLUGIN_ID);

最後に、 manifest.json を修正します。

この中に「設定画面から必ず指定しなければならないパラメータ」の指示が書かれています。
これを変更し忘れると、今までの修正によって消し去った「message」がないと怒られ続けます。

manifest.json
{
  ...中略...
  "config": {
    "html": "html/config.html",
    "js": [
      "https://js.cybozu.com/jquery/3.3.1/jquery.min.js",
      "js/config.js"
    ],
    "css": [
      "css/51-modern-default.css",
      "css/config.css"
    ],
    "required_params": [] 
  },
  ...中略...
}

required_params を空にして完了です。

ちなみに、この required_params を適切に修正しない場合、実際にアップロードして利用する時、不明なエラーが起きたり、設定値が足りないと怒られ続けたりします。

例えば、「n=1 ではない n レコードのうちの末端を jQuery が認知しない」という挙動が発生し、jQuery がエラー吐いて困惑するなど。

3. 動作確認

今までは、最低限のソースコード修正だけを行いました。
ここでは内容をアップロードして、実際にどう反映されるか確認します。

npm run start

kintone-editroom-plugin@0.1.0 develop
npm run build -- --watch
kintone-editroom-plugin@0.1.0 build
kintone-plugin-packer --ppk private.ppk --out dist/plugin.zip src

Succeeded: dist/plugin.zip
? kintoneのベースURLを入力してください (https://example.cybozu.com): ()

と出ますので、自身の kintone に払い出されている URL を入れます。

? kintoneのベースURLを入力してください : https://ABCDEFGHIJK.cybozu.com
? ログイン名を入力してください: () : ログインする時に使っているメールアドレス
? パスワードを入力してください: [hidden]
Open https://ABCDEFGHIJK.cybozu.com/login?saml=off
Trying to log in...
Navigate to https://ABCDEFGHIJK.cybozu.com/k/admin/system/plugin/
Trying to upload dist/plugin.zip
dist/plugin.zip をアップロードしました!

ログイン名（ログイン時に入れているやつ）とパスワードを入力すると、アップロードが完了します。
この「npm run start」は、「Ctrl+c」などで終了できます。
ただし、終了後、もう一度実行した場合も、同様にいろいろ聞かれるため、作業中はこの状態を維持することをおすすめします。

次に、画像の通りに操作し、アプリにプラグインを登録させます。

プラグインの登録後、さきほどの設定画面の修正によって、設定が必要となっていますので、設定ボタンを押します。

さきほど修正した設定画面用 HTML の内容通りですね。

所感

最近のフロントエンド事情だと「vite を使って TypeScript からフロントエンド群をビルドする」ような環境が多くなっている印象があります。
そのため、このバニラな HTML と JavaScript を触ることに忌避感がある人もいるでしょう。
ですが、 ひとまず API 発火のところまでは、このままの構成で進めたいと思っています。

ちなみに、kintone プラグイン開発の初期状態から存在するこの jQuery 依存。特別必須というわけでもなく、
Chrome( or MS Edge)、Safari、FireFox さえ最新であれば、別の方法で、初期状態で払い出されたソースコードと同等の操作を実現できます。
今となっては、IE も駆逐され、ブラウザのバージョンを古いもので固定するケースは非常に稀なため、次回の修正でついでに外してみます。

ひとまず、ここまでの作業で、最初の壁であるアプリの動作確認まで進めることができました。
次は、API 発火周りの作業を進めていきます。

おわりに

再度の紹介となりますが、先日、弊社から「EDITROOM」という BtoB 向けの文書作成クラウドサービスをリリースしました。
特に、定期的に文書を作る人的コストや作業にかかる拘束時間の長さを改善するのに、このサービスが大きな一助になると自負しております。

もし、ご興味がありましたら、トライアルをご利用いただければ幸いです。

次回

Discussion