はじめに

エクセルで作られたアプリ設計書をもとに、kintoneに新しくアプリを作る必要がありました。
アプリ間連携(ルックアップ/関連レコード/アクション)を含む場合に一工夫が必要だったので、備忘録として残しておきます。

なお、本記事では 具体的なコードは記載していません。
どのAPIをいつ使うか 、という流れのみの紹介になります。

やってみた

アプリ構成

以下のような構成のアプリを作成します。

アプリ1:

アプリ2を参照先とするルックアップフィールドを保有

アプリ2:

アプリ1へのアクション設定を保有
アプリ1を参照先とする関連レコードフィールドを保有

1. アプリを作成する

まずはアプリを作ります。アプリ1と2両方を一気に作ります。
動作テスト環境にアプリを作成するAPIを利用します。

この時パラメータとして指定できるのは

アプリ名
スペースID
スレッドID

のみです。
この段階ではフィールドは指定できません。
あとから追加していくことになります。

2. アプリを運用環境に反映する

まだ運用開始前（仮作成）なので、運用環境に反映します。
アプリの設定を運用環境へ反映するAPIを利用します。

このタイミングで運用環境に反映するワケ（今回少しハマったポイント）

今の段階ではまだアプリの中身は空っぽで、この後フィールドの追加等を行っていきます。
「フィールド追加等の設定が全部終わってからでいいんじゃ」と思いますが、運用開始前では アプリ間連携機能の連携先として指定できません。
運用開始前でもアプリIDは発行されてるのでできるだろう 、と思ってたんですがダメみたいです。

ルックアップの連携先に運用開始前のアプリIDを指定しフィールドを追加するAPIを利用すると、以下のようなエラーが出ます。

[404] [GAIA_AP01] 指定したアプリ（id: 100）が見つかりません。削除されている可能性があります。

kintoneのGUIから設定する場合でも、運用開始前のアプリは「関連付けるアプリ」の一覧に表示されません。

3. 運用環境への反映状況を監視する

手順2で利用したアプリの設定を運用環境へ反映するAPIは非同期です。
レスポンスが返ってきても、その時点で反映が完了しているわけではありません。
そこで、アプリの設定の運用環境への反映状況を確認するAPIを利用し、監視する必要があります。

参考）GitHub Copilotにサクッと書いてもらった監視用コード

import { KintoneRestAPIClient } from "@kintone/rest-api-client";
const client = new KintoneRestAPIClient({})

// ~~手順1,2の処理~~

let isDeployed = false;
for (let i = 0; i < 600; i++) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  const status = await client.app.getDeployStatus({ apps: [100, 101, 102] });
  if (status.apps.every((app: { status: string }) => app.status === "SUCCESS")) {
    isDeployed = true;
    break;
  }
}

if (!isDeployed) {
  throw new Error("timed out");
}

// ~~手順3以降の処理~~

すべてのアプリのステータスがSUCCESSになるまで、最大10分(+数秒)間毎秒チェックしています。
粗削りではありますがいったんこれでやりたいことはできそうです。

4. アプリにフィールドを追加する

フィールドを追加する準備が整いました。
フィールドを追加するAPIを利用します。

今回、アプリ1とアプリ2は相互に依存している為、依存関係を読み解いて順番にフィールドを作成していく必要がありそうですが、この段階では

ルックアップフィールドは 通常の文字列1行または数値 で追加する
関連レコードは 追加しない

とし、まずはフィールドを作り後から連携設定を追加していこうと思います。

5. ルックアップ/関連レコードの設定を追加する

手順4ですべてのアプリに、すべてのフィールド（関連レコードは除く）を追加できました。
手順1の際に返却されたアプリIDを使って連携設定していきましょう。

ルックアップは既存のフィールドに対しての変更となる為、フィールドの設定を変更するAPIを利用しルックアップ設定を追加します。

関連レコードについては新たにフィールド追加となる為、手順4で利用したフィールドを追加するAPIを再度利用します。

6. アクション設定を追加する

続いてアクション設定を追加します。
アクションに関するAPIについては、フィールド系の様に追加・変更・削除と分かれてはおらず、すべてアプリのアクション設定を変更するAPIで行うことになります。

ここでも手順1の際に返却されたアプリIDを使ってアクション先のアプリを指定していきましょう。

7. 運用環境に反映する

今の時点で運用環境に反映されているのは空っぽのアプリなので、
手順4~6の変更内容を反映する為、手順2と同様に運用環境に反映を行います。

さいごに

設計書をJSONに変換して丸投げドーンでいけるかなと思ってましたが、そんなわけはありませんでした。
手順2の、運用開始前のアプリは連携先として指定できない、という点に若干はまりました。思い込みはよくないですね。
手順4~5についてはもっといいやり方があるような気がしています。またの機会に考えてみようと思います。