Deep Knowledge（DeepThrive）

HubSpotカスタムコードによる一括関連付けで一歩進んだ効率化へ！

作成者: 原田 将寛｜May 8, 2026 11:46:04 AM

 

カンマ区切りのテキストからカスタムオブジェクトを自動関連付けする方法

HubSpotを運用していると、「1つのプロパティに入力された複数の管理番号をもとに、関連するレコードを自動で紐付けたい」という場面に遭遇することがあります。

例えば、取引レコードにある「12345,67891」といったテキストデータを読み取り、該当する契約オブジェクト（カスタムオブジェクト）を自動で関連付けるケースです。

しかし、HubSpotの標準機能（ワークフロー）だけでは、テキストに含まれるIDを個別に判別して関連付けることは困難です。

解決できる課題

  • 基幹システムからインポートした「カンマ区切りの管理番号」を手動で関連付けし直している。
  • 管理番号（一意のプロパティ値）はあるが、HubSpot内部の「レコードID」ではないため、インポート機能での一括関連付けが手間。
  • 関連付け作業の漏れやミスが発生し、データ整合性が保てない。

カスタムコードアクションを活用することで、「プロパティ内の値を検索キーとして、一致する別オブジェクトを自動で探し出し、一括で関連付ける」という高度な自動化が実現します。


実装手順：ステップ・バイ・ステップ

以下の手順で、取引プロパティから契約オブジェクトへの自動関連付けを設定します。

手順1. プライベートアプリのスコープ設定

まず、API操作のための権限（スコープ）を設定します。

  1. 「旧アプリ」＞「旧アプリを作成」＞「非公開」を選択します。


  2. 適当な名前を設定し、スコープを下記に設定し、アプリを作成します。
    crm.objects.deals.read
    crm.objects.deals.write
    crm.objects.custom.read（契約オブジェクト用）
    crm.objects.custom.write（契約オブジェクト用）
     補足: 関連付け専用のスコープは存在しません。関連付けを行う「両方のオブジェクト」に対して、readおよびwrite権限が必要です。 


  3. アプリの名前をクリックし、認証のタブからアクセストークンをコピーします

手順2. ワークフローの設定

 「取引ベース」のワークフローを作成し、アクションに「カスタムコード」を選択します。 

カスタムコード内でアクセストークンを安全に使用するため、ワークフロー設定画面の「シークレット」セクションに以下を追加します。

  • シークレット名: 任意の文字列
  • シークレット値: 手順1でコピーしたアクセストークン（pat-から始まる文字列）

3. カスタムコードの記述

コードで実施している流れは下記です。
①特定のプロパティが「12345」の契約レコードを検索
②見つかったレコードIDで取引と関連付け
※エラー時1件失敗しても残りの処理を継続

入力プロパティに、カスタムコード内で利用するプロパティを選択し、以下のようなコードを貼り付けます。 

■コード例
---------------------------------------------------------------------------------------

const hubspot = require('@hubspot/api-client');

exports.main = async (event, callback) => {
  const hubspotClient = new hubspot.Client({
    accessToken: process.env.hs_access_token
  });

  // ===== 設定項目（ここを変更してください） =====
  const CUSTOM_OBJECT_TYPE_ID = 'YOUR_OBJECT_TYPE_ID'; // 例: '2-223104391'
  const SEARCH_PROPERTY_NAME  = 'your_search_property'; // 例: 'id'
  const INPUT_FIELD_NAME      = 'your_input_field';     // 例: 'id_input'
  // =============================================

  const fromObjectType = 'deals';
  const fromObjectId   = event.object.objectId;
  const rawIds         = event.inputFields[INPUT_FIELD_NAME];

  if (!rawIds) {
    console.log(`${INPUT_FIELD_NAME} が空のため終了`);
    return callback({ outputFields: { processed_count: 0 } });
  }

  const idArray = rawIds.split(',')
    .map(id => id.trim())
    .filter(id => id.length > 0);

  console.log(`fromObjectId: ${fromObjectId}`);
  console.log(`検索値一覧: ${idArray}`);

  let successCount = 0;

  for (const searchValue of idArray) {
    try {
      // ① カスタムオブジェクトをプロパティ値で検索
      const searchResult = await hubspotClient.crm.objects.searchApi.doSearch(
        CUSTOM_OBJECT_TYPE_ID,
        {
          filterGroups: [
            {
              filters: [
                {
                  propertyName: SEARCH_PROPERTY_NAME,
                  operator: 'EQ',
                  value: searchValue
                }
              ]
            }
          ],
          properties: [SEARCH_PROPERTY_NAME],
          limit: 1
        }
      );

      if (!searchResult.results || searchResult.results.length === 0) {
        console.log(`${SEARCH_PROPERTY_NAME}=${searchValue} のレコードが見つかりませんでした`);
        continue;
      }

      const toObjectId = searchResult.results[0].id;
      console.log(`${SEARCH_PROPERTY_NAME}=${searchValue} → レコードID: ${toObjectId}`);

      // ② 関連付けを実行
      await hubspotClient.apiRequest({
        method: 'PUT',
        path: `/crm/v4/objects/${fromObjectType}/${fromObjectId}/associations/default/${CUSTOM_OBJECT_TYPE_ID}/${toObjectId}`,
      });

      console.log(`関連付け完了: ${fromObjectType}=${fromObjectId} → ${CUSTOM_OBJECT_TYPE_ID}=${toObjectId}`);
      successCount++;

    } catch (err) {
      console.error(`${SEARCH_PROPERTY_NAME}=${searchValue} の処理中にエラー:`, err.message);
    }
  }

  callback({ outputFields: { processed_count: successCount } });
};
 --------------------------------------------------------------------------------

変更が必要なのは下記です。

変数名 設定内容
CUSTOM_OBJECT_TYPE_ID 関連付け先オブジェクトのタイプID
SEARCH_PROPERTY_NAME 検索に使うプロパティの内部名
INPUT_FIELD_NAME ワークフローの入力フィールド名

プロパティーに情報を入れたうえでワークフローを動かすと一括で紐づけることができます。

 

導入後の変化

この設定を適用することで、取引レコードのプロパティに「12345,67891」と入力されるだけで、システムが自動的に背後で契約レコードを特定し、関連付けを完了させます。

データ入力の手間がなくなるだけでなく、常に最新の関連付け状態が維持されるため、レポート作成や売上予測の精度が向上します。

技術的な設定に不安がある場合は、まずはテスト用レコードで1件ずつ動作を確認することをお勧めします。
完全な記事を表示