拡張アプリ

あるアプリ（基本アプリ）のレコード 1 件に、別のアプリ（拡張アプリ）のレコードを1 件だけ結びつける機能です。データは 2 つのアプリに分かれたままですが、利用者から見ると1 つのレコードにタブが増えただけのように扱えます。

どんなときに使うか

「同じ人・同じ物の情報だが、管理する部署も項目数も違う」ものを 1 つのアプリに詰め込まずに済ませたいときに使います。たとえば全社共通の社員マスタ（社員番号・氏名・所属）に対して、経理部門だけが使う経費プロフィール（振込先口座・立替の上限額・仕訳の部門コード）を拡張アプリとして結びつけます。

• 社員マスタは 1 つのまま。業務パックを追加しても「社員マスタが 2 つできる」ことがありません
• 経費プロフィールのアクセス権は経理部門だけに閉じられます（拡張アプリは普通のアプリのままなので、権限・ビュー・履歴・通知はそのアプリの設定に従います）
• 社員マスタのレコードを開くと「経費」タブが増え、そこで直接入力・保存できます
• 実例: アプリストアの勤怠パッケージは、この形で「勤怠プロフィール」（勤務区分・第一〜第四承認者・基準時給・週所定労働日数）を社員マスタの「勤怠」タブとして追加します。社員マスタ自体はパックに含まれず、導入時に接続先として選んだアプリを使うため、勤怠と経費が同じ名簿を共有できます。「勤怠」タブを入力するまで拡張レコードは作られないので、パック側では「勤怠タブを入力した社員 = 勤怠の対象者」という定義になっています

設定手順

1. 基本アプリのアプリ設定 > 拡張機能で「拡張アプリ」を ON にします（拡張機能のトグルは表示整理のためだけのもので、OFF のままでも宣言済みの拡張は動き続けます。設定タブはトグルが ON のときだけ表示されるので、画面から宣言を作るにはこの ON が先に必要です。バックアップの復元・パッケージの導入・API からの宣言では自動で ON になります）
2. 拡張アプリ側に、基本アプリを参照するルックアップ項目を作ります（例: 経費プロフィールに「社員」ルックアップを作り、社員マスタの「社員番号」を参照する）。この項目がキー項目になります。基本アプリ側の参照先（社員番号）には重複禁止の設定が必要です
3. 基本アプリのアプリ設定 > 拡張アプリを開き、「拡張を追加」から拡張にするアプリとキー項目、タブの表示名を選びます
4. 追加すると、キー項目に重複禁止が自動で付きます（1 対 1 を保証するため）。すでにキーが重複しているレコードがあると追加できないので、先に重複を解消してください

• 追加には基本アプリと拡張アプリの両方のアプリ管理権限が必要です。解除は基本アプリの管理権限だけで行えます（結びつきを外すだけで、拡張アプリ側の設定もデータも変えないため）
• 解除しても拡張アプリのレコードは残ります（普通のアプリに戻るだけ）。キー項目の重複禁止も外れません
• 追加・解除・並び替え・表示名の変更はアプリの設定変更履歴と監査ログに残ります

レコード画面での見え方

• 基本アプリのレコード詳細・編集画面に、拡張ごとにタブが 1 枚増えます。タブの中身は拡張アプリのフォーム（セクション・表示条件・入力ルール・項目のアクセス権）がそのまま適用されます
• まだ拡張レコードが作られていない場合はタブに「未入力」と表示されます。拡張タブに何か入力して保存した時点で拡張レコードが作られます（基本レコードを作っただけでは作られません）
• 拡張アプリのレコード閲覧権が無い利用者には、タブ自体が表示されません。閲覧はできるが編集権が無い場合は読み取り専用で表示されます。判定に使うのはレコードの閲覧・追加・編集の権限で、アプリの設定管理権限だけでは中身を見られません（システム管理者に自動で付く権限もこれに含まれます）
• 拡張アプリ側にレコードごとのアクセス権（例: 作成者だけが閲覧・編集できる）を設定している場合、その判定も効きます。見られない拡張レコードはタブごと表示されず、更新もできません。CSV 出力では該当のセルが空になります
• 基本レコードと拡張レコードは同じ保存操作（1 つのトランザクション）で書き込まれます。拡張側の入力に誤りがあれば基本側の更新も取り消されます
• 拡張レコードのコメント・変更履歴は拡張アプリ側のレコード画面で確認します

ルックアップの「写す項目」に使う

基本アプリを参照するルックアップ項目では、「写す項目」の候補に拡張アプリの項目も並びます（拡張名 › 項目名 と表示されます）。たとえば経費申請アプリの「申請者」ルックアップ（社員マスタ参照）から、経費プロフィールの「振込先口座」を写せます。

• 拡張レコードがまだ無い社員を選んだ場合は空欄が写ります
• テーブル・グループ・複合項目は候補に出ません
• 公開フォームでは、フォーム上の入力欄へ拡張アプリの項目を写す設定は使えません（匿名の来訪者に拡張アプリのデータを配れないため）。写し先がフォームに置かれていない項目であれば、送信時にサーバー側で値が入ります

CSV / Excel の出力・取り込み

基本アプリの出力・取り込みで、拡張アプリの項目を同じ 1 行として扱えます。列見出しは拡張名:項目名の形式です（例: 経費:振込先口座）。

取り込みは 1 リクエストで大量の行を扱うため、拡張レコードの更新でもWebhook は送信されません（通知はまとめて送られます）。これは基本アプリ側の一括取り込みと同じ方針です。

API

読み取り

レコード 1 件取得に include=extensions を付けると、拡張レコードが一緒に返ります。

GET /api/apps/{appId}/records/{recordId}?include=extensions

{
  "record": { ... },
  "extensions": {
    "<拡張の id>": {
      "extension": { "id": "...", "label": "経費", "keyFieldCode": "employee", "baseKeyFieldCode": "employee_no" },
      "record": { ... },          // 拡張レコード (未作成なら null)
      "fields":  [ ... ],          // 拡張アプリの項目定義
      "permissions": { "canEdit": true, "canCreate": true }
    }
  }
}

新規作成画面などレコードがまだ無い場合はGET /api/apps/{appId}/extensions?withDefinitions=1で宣言と項目定義だけを取得できます。

書き込み

レコードの作成・更新の本文に $extensions を添えると、基本レコードと同じトランザクションで拡張レコードも保存されます。

PUT /api/apps/{appId}/records/{recordId}

{
  "data": { "name": "田中" },
  "$extensions": {
    "<拡張の id>": { "data": { "bank": "みずほ" } }
  }
}

• API トークンで呼ぶ場合、基本アプリに対するトークンの権限に加えて、トークンを発行した利用者が拡張アプリに対して持つ権限で判定されます
• 一括系（bulk / batch / bulk-individual）では $extensions を使えません。指定するとエラーになります
• レコード作成（POST）の応答には拡張レコードは含まれません。作成後の状態が必要な場合はGET /api/apps/{appId}/records/{recordId}?include=extensionsで取り直してください（更新（PUT）の応答には含まれます）
• 拡張側の入力エラーは extensionErrors として返りますが、最初に見つかった 1 件だけです（保存はそこで中止されるため）

AI アシスタント（MCP）から設定する

• get_extensions: 基本アプリに宣言されている拡張アプリの一覧を取得します
• set_extensions: 宣言を全量置換します。既存の宣言を消す変更では確認フラグが必要です。拡張アプリ側のアプリ管理権限と、そのアプリへの接続許可が必要なため、単一アプリに固定した接続では利用できません

制約

• 1 つの基本アプリにつき拡張は 5 個まで。1 つのアプリが拡張になれるのは 1 つの基本アプリに対してだけで、拡張アプリをさらに拡張する（入れ子）ことはできません
• 一覧ビュー・検索・絞り込み・並び替えでは拡張アプリの項目を使えません（レコード画面・ルックアップ・CSV・API で扱えます）
• 一括更新・一括削除では拡張アプリのデータを扱えません
• 拡張アプリではワークフローを有効にできません。すでに有効なアプリは拡張にできず、拡張にした後で有効化することもできません
• テストレコードには拡張レコードを保存できません
• 基本レコードのキー項目が空のままでは拡張レコードを作れません
• 削除は連動します。基本レコードをゴミ箱に入れると拡張レコードもゴミ箱へ、元に戻すと拡張レコードも戻り、完全に削除すると拡張レコードも完全に削除されます。この連動による削除では通知・Webhook は発生しません（利用者が操作したのは基本レコード 1 件だからです）
• 基本レコードのキーの値を変更すると、拡張レコードのキーも自動で新しい値に追随します（追随しないと拡張レコードがどこからも引けなくなるため）。レコード画面での編集・API・一括更新・CSV 取り込みが対象です。次の場合は追随しません（いずれも基本レコードの更新自体は成功し、拡張レコードは元のキーのまま残ります）
  • キーを空にしたとき（拡張レコードのキーまで空にすると、その拡張レコードを二度と探せなくなるため。基本のキーを元の値に戻せば、また結びつきます）
  • 新しいキーがすでに別の拡張レコードで使われているとき（拡張アプリ側のキーは重複できないため。サーバーのログに警告が残ります）
  • 拡張レコードがゴミ箱にあるとき（元に戻したときは古いキーのままになります）
  • スキャン（バーコード読み取り）による更新と変更履歴からの巻き戻し（巻き戻しは「当時の値をそのまま戻す」操作のため、追随させていません）
• 拡張のキー項目（基本アプリを参照するルックアップ）に「写す項目」を設定すると、その値は基本レコードから自動で入ります。写しが入るのはキーを選び直したとき（拡張レコードを保存し直したときを含む）だけで、その後に基本レコードを編集しても写しはひとりでに追随しません。写し元と写し先の型が合わない設定はその項目だけ写されません
  • 古くなった写しは、拡張レコードを開いて保存し直せば引き直されます（キーを選び直さなくても、同じキーのまま保存するだけで、編集を許可していない写しは基本レコードの現在の値に揃います）
  • 基本レコードの編集にいつも追随させたい項目は、「写す項目」ではなく「参照値」を使ってください。参照値は基本レコードの値をそのまま表示する項目で、基本レコードを編集すると（少し遅れて）自動で反映されます。人が手で書き換えることはできません
  • 参照値の反映による書き換えでは更新日時・更新者は変わらず、通知・Webhook も発生しません（値の元は基本レコードで、拡張レコードの内容を人が変えたわけではないため）
• 拡張アプリをゴミ箱に入れると宣言は解除されます（基本アプリをゴミ箱に入れた場合は、復元できるように宣言が残ります）
• 宣言している間は、キー項目の定義を変更できません（削除・重複禁止の解除・型の変更・ルックアップ参照先の変更）。変更したい場合は先に拡張の宣言を解除してください
• 基本アプリのキー項目が数値の場合、ゴミ箱の中での連動（元に戻す・完全に削除する）だけは値の表記が一致する必要があります（例: 1 と 1.0 は別の値として扱われます）。通常の保存・読み取りには影響しません
• バックアップやパッケージから復元すると、キー項目の重複禁止が外れた状態になることがあります。復元時に自動で付け直しますが、キーが重複しているレコードがあると付け直せず警告として報告されます（その場合は重複を解消してから、アプリ設定でキー項目に重複禁止を設定してください）
• 新規の宣言はスタンダードコースでのみ行えます（ライトコースでは「拡張を追加」が失敗します）。すでにある宣言はコースを問わず動き続けます
• 宣言が 1 件でもある間、基本アプリの拡張機能トグルは OFF にできません（拡張の結びつきに「無効」の状態は無く、解除は宣言の削除で行うため）