KintoneAppBuilder/plugin/kintone-addins

kintone自動化開発ツールのアクションのアドイン開発手順

1. アクションの登録

アクションプラグインをシステムに登録するためには、以下の情報をデータベースのaction表に挿入する必要があります。

列名	項目	説明
name	名前	アクションプラグイン名（ユニークな名前が必要）
title	タイトル	タイトル （20文字以内）
subtitle	サブタイトル	サブタイトル
outputpoint	出力ポイント	出力値に分岐がある場合の接続点
property	プロパティ	アクションプラグインの属性（json形式）

登録の例

以下は「表示／非表示」アクションプラグインを登録する例です。

• name: "表示／非表示"
• title: "指定項目の表示・非表示を設定する"
• subtitle: "表示／非表示"
• outputpoint: "[]"
• property:

[
  {
    "component": "FieldInput",
    "props": {
      "displayName": "フィールド",
      "modelValue": {},
      "name": "field",
      "placeholder": "対象項目を選択してください"
    }
  },
  {
    "component": "SelectBox",
    "props": {
      "displayName": "表示／非表示",
      "options": ["表示", "非表示"],
      "modelValue": "",
      "name": "show",
      "placeholder": ""
    }
  },
  {
    "component": "ConditionInput",
    "props": {
      "displayName": "条件",
      "modelValue": "",
      "name": "condition",
      "placeholder": "条件式を設定してください"
    }
  }
]

プロパティ属性設定画面

属性UIコンポーネントの共通属性

属性	設定値の例	説明
component	InputText	コンポーネントの種類を示しており、この場合は選択リストを意味します。 使用可能なコンポーネントを参照
displayName	表示／非表示	ユーザーに対して表示されるコンポーネントの名前です。
options	["表示", "非表示"]	ユーザーが選択できるオプションの配列です。 SelectBoxのみ使用可能
modelValue	空文字	コンポーネントの初期値を設定します。 初期設定ないの場合は空文字で設定する。
name	field	属性の設定値の名前です。
placeholder	対象項目を選択してください	入力フィールドに表示されるプレースホルダーのテキストです。この場合は設定されていません。
hint	説明文	長い説明文を設定することが可能です。（markdown形式サポート予定、現在HTML可能）
selectType	single or multiple	フィールド選択・他のアプリのフィールド選択の選択モードを設定する

使用可能なコンポーネント

No.	コンポーネント名	コンポーネントタイプ	説明
1	テキストボックス	InputText	一行のテキスト入力が可能なフィールドです。
2	テキストボックス（改行可能）	MuiltInputText	複数行のテキスト入力が可能なテキストエリアです。
3	日付	DatePicker	日付を選択するためのカレンダーコンポーネントです。
4	フィールド選択	FieldInput	システムのフィールドを選択するための入力コンポーネントです。
5	選択リスト	SelectBox	複数のオプションから選択するためのドロップダウンリストです。
6	条件式設定	ConditionInput	条件式やロジックを入力するためのコンポーネントです。
7	イベント設定	EventSetter	ボタンイベント設定のコンポーネントです。
8	色選択	ColorPicker	色を設定する（追加予定中）
9	他のアプリのフィールド選択	AppFieldPicker	他のアプリのフィールドを選択する（追加予定中）
10	ユーザー選択	UserPicker	ユーザーを選択する（追加予定中）

2.アクションアドインの開発

1. Action pluginファイルの追加

アクションプラグインを作成するためには、以下のディレクトリ構造にTypeScriptファイルを追加します。

KintoneAppBuilder
└─ plugin
    └─ kintone-addins
        └─ src
            └─ actions
                └─ your-action.ts // ここにアクションプラグインのtsファイルを追加

2. アクションクラスの実装手順

IAction インターフェースに従ってアクションクラスを実装します。

/**
 * アクションのインターフェース
 */
export interface IAction{
  // アクションのユニークな名前
  name:string;
  //属性設定情報
  actionProps: Array<IActionProperty>;
  //アクションのプロセス実行関数
  process(prop:IActionNode,event:any,context:IContext):Promise<IActionResult>;
  //アクションの登録関数
  register():void;
}

サンプルコード

// アクションの属性定義
interface IShownProps{
    field:IField;
    show:string; 
    condition:string;
}

// 表示／非表示アクション
export class FieldShownAction implements IAction{
    name: string;
    actionProps: IActionProperty[];
    props:IShownProps;
    constructor(){
        this.name="表示／非表示";　// DBに登録したアクション名一致する必要があり
        this.actionProps=[];
        //プロパティ属性の初期化
        this.props={
            field:{code:''},
            show:'',
            condition:''
        }
        //アクションの自動登録
        this.register();
    }
     /**
     * アクションの実行を呼び出す
     * @param actionNode 
     * @param event 
     * @returns 
     */
    async process(actionNode:IActionNode,event:any,context:IContext):Promise<IActionResult> {
        // ... (アクション処理の実装)
    }
 
    register(): void {
        actionAddins[this.name]=this;
    }
}
new FieldShownAction();

アクションプラグインを実装するには、IActionインターフェースの定義に従って、必要なメソッドとプロパティをクラスに実装します。 以下に、IActionインターフェースを用いて表示／非表示アクションを実装する手順を説明します。

1. アクションの属性定義

2. アクションクラスの作成:

   • IActionインターフェースを実装する新しいクラスFieldShownActionを作成します。

3. コンストラクタの定義:

   • アクション名や初期プロパティを設定します。
   • このクラスのインスタンスが作成された際に、自動的にアクションが登録されるように、コンストラクタ内でregisterメソッドを呼び出します。

4. プロセス実行関数の実装 (process):

   • processメソッドは、アクションの主要なロジックを含み、アクションの実行時に呼び出されます。

• • 以下はprocess関数のパラメータとその用途を説明します。

パラメータ名	型	用途
actionNode	IActionNode	Kintone自動化ツールのアクションの設定やプロパティ情報を保持します。
event	kintoneのイベント情報	レコードやエラー制御で使用します
context	IContext	現在のレコード情報や変数など、実行に必要なデータへのアクセスを提供します。

• このメソッド内で、アクションに必要な処理を行います。
• 1. アクションプロパティの取得:
     Kitone自動化ツールを設定したプロパティの値を取得する

//プロパティ設定を取得する
this.actionProps=actionNode.actionProps;
//プロパティ設定のデータ型は必要な情報が含めますか
if (!('field' in actionNode.ActionValue) && !('show' in actionNode.ActionValue)) {
    return result
}
//既定のプロパティのインターフェースへ変換する
this.props = actionNode.ActionValue as IShownProps;

• 2. 条件式の評価 getConditionResult関数を呼び出して条件式を評価します。この関数は、現在のコンテキストに基づいて条件式が真か偽かを返します。

//条件式の計算結果を取得
const conditionResult = this.getConditionResult(context);
    /**
 * 
    * @param context 条件式を実行する
    * @returns 
    */
getConditionResult(context:any):boolean{
    //プロパティ`condition`から条件ツリーを取得する
    const tree =this.getCondition(this.props.condition);
    if(!tree){
        //条件を設定されていません
        return true;
    }
    return tree.evaluate(tree.root,context);
}

• 3. Kintone APIを使用して、フィールドの表示／非表示の制御

    //条件式の計算結果を取得
    const conditionResult = this.getConditionResult(context);
    if(conditionResult){
        if(this.props.show==='表示'){
            kintone.app.record.setFieldShown(this.props.field.code,true);
        }else if (this.props.show==='非表示'){
            kintone.app.record.setFieldShown(this.props.field.code,false);
        }
    }

5. 登録関数の実装 (register):

   • アクションをアドインシステムに登録するためのregisterメソッドを実装します。

6. アクションプロセスActionProcessに参照追加

import { actionAddins } from "../actions";
import '../actions/must-input';
import '../actions/auto-numbering';
import '../actions/field-shown'; 
import '../actions/your-action'; //ここに新規のアクションの参照を追加する
...

3. デプロイ

1. プロジェクトをビルドする

• 本番環境にデプロイする場合

cd plug\kintone-addins\
npm install
npm run build

• 開発環境にデプロイする場合（ソースマップ出力ます）

cd plug\kintone-addins\
npm install
npm run build:dev

2. Azureにデプロイする

• Azure 拡張機能のインストール:
  VSCode の拡張機能ペインでAzure Toolsを検索し、インストールします。

• Azure にログイン:

  • Azure Account 拡張機能を使用して Azure にログインします。

• Azure へのデプロイ:

  • 「Deploy to Web App」オプションを使用し、デプロイするファイルやフォルダを指定します。

• デプロイの確認:

  • Azure App Service 拡張機能でデプロイが完了したことを確認します。
  • ka-addin の URL にアクセスしてアプリケーションが正常に動作しているか確認します。

3. ローカルでプラグインをテストする
4. kintone-addinsをPreviewで起動する

yarn build:dev
yarn preview
#またはyarn devは　yarn build:dev + yarn preview　と同じです
yarn dev

2. ngrokをインストールする
   1. ngrok の公式ウェブサイトにアクセスします。
   2. 「Sign up」をクリックしてアカウントを登録するか、既存のアカウントにログインします。
   3. 登録またはログイン後、ダッシュボードに進み、ダウンロードリンクが表示されます。操作システム（Windows、macOS、Linux）に応じて、適切なバージョンを選択してダウンロードします。
   4. ダウンロード後、.zip ファイルを解凍します。
   5. ngrok を設定する
      1. ngrok ダッシュボードにログインし、ホームページで認証トークンを見つけます。
      2. ターミナル（またはコマンドプロンプト）を開き、以下のコマンドを実行して認証トークンを追加します：

      ngrok config add-authtoken <認証トークン>
      

   6. ngrok を起動する

      ngrok https http://localhost:4173/