ルックアップの自動取得

kintone のルックアップフィールドは、別のアプリのデータを参照して現在のレコードにコピーする便利な機能です。通常はユーザーが「取得」ボタンをクリックして参照データを取り込みますが、JavaScript カスタマイズを使えば、画面を開いた時点で自動的にルックアップを実行 させることができます。

しかし、ルックアップの自動取得にはいくつかの注意点や、利用できるイベントの制約があります。

この記事では、ルックアップの自動取得の仕組みから、実践的な実装パターン、よくある問題の解決方法まで解説します。

lookup プロパティによる自動取得

kintone の JavaScript API では、ルックアップフィールドに対して lookup プロパティ を設定することで、自動的にルックアップの取得処理をトリガーできます。

基本的な使い方

(() => {
  'use strict';

  const events = [
    'app.record.create.show',
    'mobile.app.record.create.show',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;

    // ルックアップフィールドに値を設定
    record['顧客コード'].value = 'C001';

    // lookup プロパティを true に設定して自動取得をトリガー
    record['顧客コード'].lookup = true;

    return event;
  });
})();

lookup プロパティが使えるイベント

lookup プロパティによる自動取得は、レコードの作成・編集画面の表示イベント でのみ使用できます。

実践パターン

パターン 1: URL パラメータからルックアップを自動取得

他のアプリからリンクでレコードの新規作成画面を開き、URL パラメータの値でルックアップを自動取得するパターンです。

(() => {
  'use strict';

  const events = [
    'app.record.create.show',
    'mobile.app.record.create.show',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;

    // URL パラメータから顧客コードを取得
    const urlParams = new URLSearchParams(window.location.search);
    const customerCode = urlParams.get('customerCode');

    if (customerCode) {
      record['顧客コード'].value = customerCode;
      record['顧客コード'].lookup = true;
    }

    return event;
  });
})();

リンク元のアプリでは、以下のようなリンクを生成します。

const url = `https://{subdomain}.cybozu.com/k/{appId}/edit?customerCode=${customerCode}`;

パターン 2: ログインユーザーの情報でルックアップを自動取得

ログインユーザーの情報をもとに、担当者マスタからデータを自動取得するパターンです。

(() => {
  'use strict';

  const events = [
    'app.record.create.show',
    'mobile.app.record.create.show',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;
    const loginUser = kintone.getLoginUser();

    // ログインユーザーのログイン名で担当者マスタを参照
    record['担当者コード'].value = loginUser.code;
    record['担当者コード'].lookup = true;

    return event;
  });
})();

パターン 3: 編集画面でルックアップを再取得

レコード編集画面を開いた際に、ルックアップの参照先データが更新されている可能性がある場合、自動的に最新のデータを再取得するパターンです。

(() => {
  'use strict';

  const events = [
    'app.record.edit.show',
    'mobile.app.record.edit.show',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;

    // 既にルックアップフィールドに値がある場合、再取得をトリガー
    if (record['顧客コード'].value) {
      record['顧客コード'].lookup = true;
    }

    return event;
  });
})();

lookup を使用できない場面での代替手段

change イベントや submit イベントなど、lookup プロパティが使えない場面では、REST API を使って参照先アプリのデータを直接取得する方法があります。

フィールド変更イベントでの参照先データ取得

(() => {
  'use strict';

  const LOOKUP_APP_ID = 10; // 参照先アプリのID

  const events = [
    'app.record.create.change.顧客コード',
    'app.record.edit.change.顧客コード',
  ];

  kintone.events.on(events, async (event) => {
    const record = event.record;
    const customerCode = record['顧客コード'].value;

    if (!customerCode) {
      // 値がクリアされた場合、関連フィールドもクリア
      record['顧客名'].value = '';
      record['電話番号'].value = '';
      return event;
    }

    try {
      // REST API で参照先アプリから直接取得
      const result = await kintone.api(
        kintone.api.url('/k/v1/records.json', true),
        'GET',
        {
          app: LOOKUP_APP_ID,
          query: `顧客コード = "${customerCode}"`,
          fields: ['顧客名', '電話番号', '住所'],
        }
      );

      if (result.records.length > 0) {
        const srcRecord = result.records[0];
        record['顧客名'].value = srcRecord['顧客名'].value;
        record['電話番号'].value = srcRecord['電話番号'].value;
        record['住所'].value = srcRecord['住所'].value;
      }
    } catch (error) {
      console.error('参照先データの取得に失敗しました', error);
    }

    return event;
  });
})();

lookup = “CLEAR” でルックアップをクリアする

lookup プロパティに "CLEAR" を設定すると、ルックアップフィールドとそのコピー先フィールドの値をクリアできます。

(() => {
  'use strict';

  const events = [
    'app.record.create.show',
    'mobile.app.record.create.show',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;

    // ルックアップフィールドとコピー先フィールドをクリア
    record['顧客コード'].lookup = 'CLEAR';

    return event;
  });
})();

よくあるトラブルと解決策

「ルックアップの取得に失敗しました」エラー

ルックアップのコピー先にデータが反映されない

lookup = true を設定しても、コピー先フィールドにデータが反映されない場合は、以下を確認してください。

1. ルックアップの設定 でコピー元・コピー先のフィールドが正しく設定されているか
2. イベント が create.show または edit.show であるか
3. return event を忘れていないか

まとめ

• ルックアップの自動取得は record['フィールドコード'].lookup = true で実現できる
• lookup プロパティは create.show と edit.show イベントでのみ使用可能
• change イベントや submit イベントでは REST API を使って参照先データを直接取得する
• lookup = "CLEAR" でルックアップのコピー先フィールドを含めてクリアできる
• URL パラメータやログインユーザー情報を組み合わせることで、実務に即した自動取得が実現できる

練習問題