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

## 1. アクションの登録

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

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

### 登録の例

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

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

```json
[
  {
    "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": "条件式を設定してください"
    }
  }
]
```

### プロパティ属性設定画面
![プロパティ属性設定画面](../../document/action-property.png)


### 属性UIコンポーネントの共通属性
| 属性          | 設定値の例                  | 説明                                                                         |
|-------------|--------------------|----------------------------------------------------------------------------|
| component   | InputText  | コンポーネントの種類を示しており、この場合は選択リストを意味します。<br>使用可能なコンポーネントを参照|
| displayName | 表示／非表示         | ユーザーに対して表示されるコンポーネントの名前です。                                         |
| options     | ["表示", "非表示"]   | ユーザーが選択できるオプションの配列です。<br>SelectBoxのみ使用可能 |
| modelValue  | 空文字             | コンポーネントの初期値を設定します。<br>初期設定ないの場合は空文字で設定する。
| name        | field              | 属性の設定値の名前です。   |
| placeholder | 対象項目を選択してください| 入力フィールドに表示されるプレースホルダーのテキストです。この場合は設定されていません。          |
| hint        | 説明文| 長い説明文を設定することが可能です。（markdown形式サポート予定、現在HTML可能）          |
| selectType  |`single` or `multiple`| フィールド選択・他のアプリのフィールド選択の選択モードを設定する         |
| required  | boolean | 必須チェックするかどうか         |
| requiredMessage  | string | 必須チェック時のエラーメッセージ。（未設定の場合「XXXX」が必須です。になります）        |
| rules  |"[val=>val<=100 && val>=1 \|\| '1-100の範囲内の数値を入力してください']"| 必須チェック以外のルールを設定する  |

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

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

### 1. Action pluginファイルの追加
アクションプラグインを作成するためには、以下のディレクトリ構造に`TypeScript`ファイルを追加します。
```
KintoneAppBuilder
└─ plugin
    └─ kintone-addins
        └─ src
            └─ actions
                └─ your-action.ts // ここにアクションプラグインのtsファイルを追加
```
### 2. アクションクラスの実装手順
`IAction` インターフェースに従ってアクションクラスを実装します。
```typescript

/**
 * アクションのインターフェース
 */
export interface IAction{
  // アクションのユニークな名前
  name:string;
  //属性設定情報
  actionProps: Array<IActionProperty>;
  //アクションのプロセス実行関数
  process(prop:IActionNode,event:any,context:IContext):Promise<IActionResult>;
  //アクションの登録関数
  register():void;
}
```
#### サンプルコード
```ts
// アクションの属性定義
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自動化ツール`を設定したプロパティの値を取得する

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

- 2. 条件式の評価
    getConditionResult関数を呼び出して条件式を評価します。この関数は、現在のコンテキストに基づいて条件式が真か偽かを返します。
```ts
//条件式の計算結果を取得
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を使用して、フィールドの表示／非表示の制御
```ts
    //条件式の計算結果を取得
    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`に参照追加**
```ts
import { actionAddins } from "../actions";
import '../actions/must-input';
import '../actions/auto-numbering';
import '../actions/field-shown'; 
import '../actions/your-action'; //ここに新規のアクションの参照を追加する
...
```
### 3. デプロイ
1. **プロジェクトをビルドする**
- 本番環境にデプロイする場合
```bash
cd plug\kintone-addins\
npm install
npm run build
```
- 開発環境にデプロイする場合（ソースマップ出力ます）
```bash
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. **ローカルでプラグインをテストする(ZCCの導入ため、廃止する)**
1. kintone-addinsをPreviewで起動する
```bash
yarn build:dev
yarn preview
#またはyarn devは　yarn build:dev + yarn preview　と同じです
yarn dev
```
2. **ngrokをインストールする(ZCCの導入ため、廃止する)**
    1. [ngrok の公式ウェブサイト](https://ngrok.com/)にアクセスします。
    2. 「Sign up」をクリックしてアカウントを登録するか、既存のアカウントにログインします。
    3. 登録またはログイン後、ダッシュボードに進み、ダウンロードリンクが表示されます。操作システム（Windows、macOS、Linux）に応じて、適切なバージョンを選択してダウンロードします。
    4. ダウンロード後、`.zip` ファイルを解凍します。
    5. ngrok を設定する
        1. ngrok ダッシュボードにログインし、ホームページで認証トークンを見つけます。
        2. ターミナル（またはコマンドプロンプト）を開き、以下のコマンドを実行して認証トークンを追加します：
        ```bash
        ngrok config add-authtoken <認証トークン>
        ```
    6. ngrok を起動する
        ```bash
        ngrok https http://localhost:4173/
        ```
3. kintone-addinsをビルドする
```bash
yarn build:dev　#開発モード
#またはyarn devは　yarn build:dev + yarn preview　と同じです
yarn build      #本番リリースモード
```