Zenn
Septeni Japan Tech BlogPublicationへの投稿
📝

Kintoneの設定管理システムを作ってみた

oshiman
2024/12/26に公開
TypeScript
kintone
tech

こんにちは！Septeni Japan 株式会社のエンジニアの大志万といいます。

今回は、TerraformなどのIaCのように、Kintoneの設定をファイルで管理し、必要に応じてデプロイできるようなシステムを作ったので、そのシステムについて紹介します。

背景

私の会社ではKintoneを契約しており、社内システムのいくつかにKintoneを利用しています。
今までは、Kintoneを使ったシステム開発を行う際、毎回アプリをコピーして開発環境を作成していましたが、下記のような問題がありました。

  • 開発環境で行った変更を本番環境に反映する際、手動で設定を変更する必要がある。
  • 複数のアプリをルックアップで連携したシステムの場合、コピーを行うとルックアップ先が本番環境のままになってしまい修正が必要である。
  • チームで開発している場合、意図しない変更が入ってしまう可能性がある。

私は普段TerraformやCDKを使ってAWSの設定を管理しており、Kintoneの設定も同じように管理できたら便利だと思ったので、今回のシステムを作りました。

システムの概要

KintoneにはアプリのフィールドやレイアウトをAPI経由で取得・設定する機能があります。
今回はそれを使ってKintoneのアプリのフィールドの設定をファイルで管理し、自動で差分を反映させるKintoneの管理システムを考えました。
具体的には下記の機能を実装しています。

  • Kintoneのフィールド情報をダウンロードしてローカルに保存する
  • ローカルに保存してあるフィールドの状態とKintoneの状態を比較して差分を表示する
  • ローカルに保存してあるフィールドの状態になるようにKintoneにフィールドをデプロイする

作成したコード

公式がサポートしているKintoneRestAPIのクライアントがあるTypescriptを使ってシステムを構築しました。下記のGithubにコードを公開しています。あくまで、私のチーム向けに作成したものなので、使い方や改善点があれば、適宜変更を行ってください。

https://github.com/septeni/kintone-manage-system-sample

以降は上記のコードを元に運用している方法や使い方を説明します。
もし、同じような問題を抱えている方がいれば、参考にしていただければ幸いです。

Setup

bin/appsディレクトリにアプリ単位でディレクトリを作成し、config.tsファイルを作成します。
config.tsファイルには、defineAppConfig関数を使ってアプリの設定を記述します。

import path from "path";
import { defineAppConfig } from "../../bin";

export default defineAppConfig({
  appId: "1234",
  requireRecordExistsCheck: true,
  fieldsPath: `${path.resolve(__dirname)}/fields.json`,
  layoutsPath: `${path.resolve(__dirname)}/layouts.json`,
  fieldOverwrites: [
    {
      fieldCode: "lookup_field",
      field: {
        lookup: {
          relatedApp: {
            app: "1234",
            code: "",
          },
        },
      },
    },
  ],,
});

各設定について説明します。

  • appID： KintoneのアプリID。
  • requireRecordExistsCheck： レコードが存在する場合、フィールドの削除を行わずにエラーを出力するオプション。
  • fieldsPath： フィールドの設定を保存するjsonファイルのパス。
  • layoutsPath： レイアウトの設定を保存するjsonファイルのパス。
  • fieldOverwrites： フィールドの上書きを行うオプション。fieldCodeキーに上書きしたいフィールドコードを指定し、fieldキーに上書きしたいフィールドの設定を記述します。設定はこちらの公式APIと同じ形式でオブジェクトの作成を行います。

上記のconfig.tsは、本番用(_prod_config.ts)と開発用(config.ts)で二つ作成を行い、デプロイ時に切り替えることで、デプロイ先や設定を変更することができます。

複数のアプリをルックアップで連携したシステムの場合は、上記のようにルックアップ先のアプリIDを開発用と本番用のfieldOverwritesに記述することで、開発環境と本番環境のルックアップ先を切り替えることが可能です。

コマンド

download

npm run download -- -t <アプリのディレクトリ名>

config.tsに設定しているアプリのフィールドとレイアウトをダウンロードする機能です。
実行すると、fieldsPathとlayoutsPathにjsonファイルが作成されます。

jsonファイルの中身は、下記のKintone APIから取得した内容になります。

diff

npm run diff -- -t <アプリのディレクトリ名>

実行すると下記のような感じで、差分が表示されます。

追加するフィールド
add_field
変更するフィールド
update_field

削除するフィールド
delete_field

deploy

npm run deploy -- -t <アプリのディレクトリ名>

diffで差分を表示した後に、Yes/Noの質問が出るので、Yesを入力するとデプロイが実行されます。
deploy

運用している使い方

実際に私が運用している使い方を紹介します。

1. 開発用のアプリを作成しフィールドやレイアウトを変更する。

Kintoneの編集画面で、フィールドやレイアウトを変更します。

2. 開発用のアプリからフィールド・レイアウト情報をjsonファイルとして保存する。

downloadコマンドを実行し、フィールド・レイアウト情報をjsonファイルとして保存します。

3. jsonファイルを反映した開発ブランチをpushし、本番環境との差分を確認する

Github Actionsを使って、pushされた際に差分を確認するジョブを実行します。

Github Actionsの設定はこちらのファイルをご覧ください。
設定完了すると、pushされた際に、差分を確認するジョブが実行され、PRに差分の結果をコメントするようにしています。
diff_ci

4. デプロイ

差分が問題なければ、マージを行います。
Github Actionsを使って、マージされた際にデプロイを行うジョブを実行します。
Github Actionsの設定はこちらのファイルをご覧ください。

デプロイ後、もし他の人が変更を行った場合、ローカルで、npm run deployを実行することで、開発環境に差分を反映することができます。

運用してみた感想

よかった点

  • Github Actionsなどで差分を表示させることができるため、開発環境と本番環境の変更を把握しやすくなり、安心して開発を行うことができました。
  • 他の人が行った変更も自分の環境にコマンド一つで反映できるので、チームで開発を行う際にも便利だなと思いました。
  • requireRecordExistsCheckオプションを使うことで、フィールドの削除を行う際にエラーを出力することができるので、意図しない削除を防ぐことができました。

改善点

  • フィールドコードの変更を検知できない

差分の抽出方法にフィールドコードを使っているためフィールドコードを変更した場合に、「古いフィールドコードを削除」し「新しいフィールドコードを追加」するという判定がされてしまいます。

上記の場合、古いフィールドコードを削除した時点で、古いフィールドコードに保存されているデータが消えてしまうという問題が発生します。

そのため、フィールドコードの変更を行う際は、本番環境のKintoneの設定画面で手動でフィールドコードを変更する必要があります。

  • ドロップダウンの選択肢を変更した場合に、既存のレコードに反映されない

dropdown

例えば、上記のドロップダウンの選択肢をsample1からsample3に変更した場合、アプリの設定画面上で変更を行った場合は、既存のレコードにも反映されますが、APIから変更を行った場合は、既存のレコードに反映されません。

そのため、ドロップダウンの選択肢を変更する際も、本番環境のアプリの設定画面上で変更する必要があります。

最後に

上記のような改善点はありますが、やはり開発環境と本番環境の設定を一元管理できることはとても便利だと感じました。

今回のシステムは私のチーム向けに作ったものなので、時間があるときに上記の改善点を解消し、より使いやすくしたものをパッケージ化して公開したいと思います。

もし、Kintoneの開発環境と本番環境の管理でお困りの方がいれば、参考にしていただければ幸いです。
最後までお読みいただき、ありがとうございました。質問やフィードバックがありましたら、ぜひコメント欄でお知らせください。

Septeni Japan Tech Blog
Septeni Japan Tech BlogPublication

Discussion