最終更新日: 2025年8月28日
ワークフローでは、「カスタムコード」アクションを使用して、JavaScriptまたはPython(ベータ版)を作成し、実行します。カスタムコードアクションを使用すると、HubSpot内でもHubSpot外でもワークフロー機能を拡張できます。一般的なカスタムコードアクションの例は、HubSpotのプログラマブルオートメーションのユースケースで確認できます。 カスタムコードアクションでは、JavaScriptをサポートするためにNode.jsランタイムフレームワーク(英語)が使用されます。カスタムコードアクションにPythonを使用する場合、カスタムコードアクションではPythonランタイムフレームワーク(英語)が使用されます。アクションが実行されると、HubSpotとAWS Lambda(英語)によるサーバーレス機能によって、ランタイム計算が管理されます。 カスタムコードアクションの実装で一般的な問題が発生した場合は、HubSpotのヘルプをご利用ください。ただし、ご自分で記述したカスタムコードで問題が発生した場合は、HubSpot開発者フォーラムで問題について検索、投稿して、コードのトラブルシューティングに関するサポートを受けることをお勧めします。

Node.js対応ライブラリー

Node.jsを使用する場合、コードアクション内で次のライブラリーを使用できます。これらのライブラリーを読み込むには、コードの先頭で通常のrequire()関数を使用します。
  • @hubspot/api-client ^10
  • async ^3.2.0
  • aws-sdk ^2.744.0
  • axios ^1.2.0
  • lodash ^4.17.20
  • mongoose ^6.8.0
  • mysql ^2.18.1
  • redis” ^4.5.1
  • request” ^2.88.2
  • bluebird ^3.7.2
  • random-number-csprng ^1.0.2
  • googleapis ^67.0.0

注:

V4 Associations APIは、NodeJS HubSpot Clientのバージョン9.0.0以降、およびNodeJS HubSpot Clientのバージョン8でサポートされています。

Python対応ライブラリー

Pythonを使用する場合、コードの先頭でインポートステートメントを使用して、次のライブラリーを読み込むことができます。インポートステートメントは、from [libraryname] import [item]の形式にする必要があります(例:from redis.client import redis)。
  • requests 2.28.2
  • @hubspot/api-client ^8
  • google-api-python-client 2.74.0
  • mysql-connector-python 8.0.32
  • redis 4.4.2
  • nltk 3.8.1
標準ライブラリーから何らかの要素を取り込んで使用する場合は、importを使用できます(例:import os)。

使い始めるには

カスタム コード ワークフロー アクションを使用するには、以下のサンプルコードを使用します。

コード サンプル

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

exports.main = async (event, callback) => {

  /*****
    How to use secrets
    Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code
    Each secret needs to be defined like the example below
  *****/

  const hubspotClient = new hubspot.Client({
    accessToken: process.env.SECRET_NAME
  });

  let phone;
  try {
    const ApiResponse = await hubspotClient.crm.contacts.basicApi.getById(event.object.objectId, ["phone"]);
    phone = ApiResponse.properties.phone;
  } catch (err) {
    console.error(err);
    // We will automatically retry when the code fails because of a rate limiting error from the HubSpot API.
    throw err;
  }

  /*****
    How to use inputs
    Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data.
    Each input needs to be defined like the example below
  *****/

  const email = event.inputFields['email'];

  /*****
    How to use outputs
    Outputs are a way for you to take data from your code and use it in later workflows actions

    Use the callback function to return data that can be used in later actions.
    Data won't be returned until after the event loop is empty, so any code after this will still execute.
  *****/

  callback({
    outputFields: {
      email: email,
      phone: phone
    }
  });
}

// A sample event may look like:
{
  "origin": {
    // Your portal ID
    "portalId": 1,

    // Your custom action definition ID
    "actionDefinitionId": 2,
  },
  "object": {
    // The type of CRM object that is enrolled in the workflow
    "objectType": "CONTACT",

    // The ID of the CRM object that is enrolled in the workflow
    "objectId": 4,
  },
  "inputFields": {
    // The property name for defined inputs
  },
  // A unique ID for this execution
  "callbackId": "ap-123-456-7-8"
}
import os
from hubspot import HubSpot
from hubspot.crm.contacts import ApiException

def main(event):

# How to use secrets

# Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code

# Each secret needs to be defined like the example below

hubspot = HubSpot(access_token=os.getenv('SECRET_NAME'))

phone = '' try: ApiResponse = hubspot.crm.contacts.basic_api.get_by_id(event.get('object').get('objectId'), properties=["phone"]) phone = ApiResponse.properties.get('phone') except ApiException as e: print(e)

# We will automatically retry when the code fails because of a rate limiting error from the HubSpot API.

raise

# How to use inputs

# Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data.

# Each input needs to be defined like the example below

email = event.get('inputFields').get('email')

# How to use outputs

# Outputs are a way for you to take data from your code and use it in later workflows actions

# Use the callback function to return data that can be used in later actions.

# Data won't be returned until after the event loop is empty, so any code after this will still execute.

return { "outputFields": { "email": email, "phone": phone } }

# A sample event may look like:

# {

# "origin": {

# # Your portal ID

# "portalId": 1,

# # Your custom action definition ID

# "actionDefinitionId": 2,

# },

# "object": {

# # The type of CRM object that is enrolled in the workflow

# "objectType": "CONTACT",

# # The ID of the CRM object that is enrolled in the workflow

# "objectId": 4,

# },

# "inputFields": {

# # The property name for defined inputs

# },

# # A unique ID for this execution

# "callbackId": "ap-123-456-7-8"

# }

カスタムコードアクションを作成する

カスタムコードアクションをワークフローに追加するには、次の手順に従ってください。
  • HubSpotアカウントで、[自動化]>[ワークフロー]に移動します**。 **** **
  • ワークフローの名前をクリックするか、新しいワークフローを作成します。
  • +**プラス**アイコンをクリックし、ワークフローアクションを追加します。
  • 左側のパネルで「カスタムコード」を検索して選択します**。 **
カスタムコードアクションの選択
  • デフォルトでは、カスタムコードアクションはNode.jsを使用します。Pythonベータ版でPythonを使ってアクションを作成する場合は、[言語]ドロップダウンメニューをクリックし、[Python]を選択します。
  • [説明]フィールドに、カスタムワークフローアクションの説明を入力します。_ _この説明は対応するワークフローアクションのカードに表示されます。
  • カスタムコードアクションでは、非公開アプリのアクセストークンなどのシークレットを使用できます。アプリには、contactsformsなど、HubSpotから取得しようとしているデータのスコープを含める必要があります。詳しくは、HubSpotの非公開アプリに関するぺージをご確認ください。
    • 既存のシークレットを使用するには、[シークレットを追加]をクリックします**。 次に、追加するシークレットの横にあるチェックボックス**をオンにします。
    • 新しいシークレットを追加する場合は、[シークレットを追加]をクリックします**。 **ダイアログボックスの[シークレット名]と[シークレット値]に値を入力します。次に、保存をクリックします。これで、以降のカスタムコードアクションでこのシークレットを選択できるようになります。
    • 既存のシークレットを編集または削除する場合は、[シークレットを管理]をクリックします**。 **
  • カスタムコードにプロパティーを含めるには、次の手順に従います。
    • [プロパティーを選択]をクリックし、データパネルからプロパティーを選びます**。 ワークフローでは、既存のプロパティーまたは以前に書式設定されたプロパティー値を使用できます。プロパティーを選択したら、コード内で使用するプロパティー名**を入力します。こちらで、カスタムコードでプロパティーを参照する方法をご確認いただけます。
    • 別のプロパティーを追加するには、[プロパティーを追加]をクリックします**。 **各プロパティーは1回のみ追加できます。また、プロパティーには固有の[変数ID]が割り当てられている必要があります。カスタムコードでは最大50個のプロパティーを使用できます。
    • プロパティーを削除するには、削除アイコンをクリックします。
  • コードフィールドにJavaScriptまたはPythonを入力します。
  • 例えば[レコードを編集]アクションなどで、後にワークフローにて入力として使用できるデータ出力を定義するには、次のようにします:
    • [データ出力]で**[出力を追加]**をクリックします。
    • [データタイプ]ドロップダウンメニューをクリックし、データのタイプを選択します。
    • [名前]フィールドに、データ出力の名前を入力します。
    • 複数の出力を追加する場合は、**[出力を追加]**をクリックします。
  • 上部にある**[保存]**をクリックします。
ワークフロー カスタム コード

注:

Pythonを使用している場合、コードフィールドにリントエラーは表示されません。
カスタムコードアクションを作成する際は、次の点に留意してください。
  • コードスニペットのアクションが実行されると、def main(event):関数が呼び出されます。
  • Event引数は、ワークフロー実行の詳細を含むオブジェクトです。
  • ワークフローにデータを返すには、callback()関数を使用します。この関数は、exports.main関数内で呼び出す必要があります。これは、Node.jsでのみ使用できます。
eventオブジェクトには、以下のデータが格納されます。
//example payload
{
  "origin": {
    // Your portal ID
    "portalId": 1, // Your custom action definition ID
    "actionDefinitionId": 2
  },
  "object": {
    // The type of CRM object that is enrolled in the workflow
    "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow
    "objectId": 4
  },
  // A unique ID for this execution.
  "callbackId": "ap-123-456-7-8"
}

アクションのレート制限を設定する(ベータ)

レート制限を設定して、カスタムコードアクションの実行頻度を決定します。レート制限は、カスタムコードアクションに続く、ワークフロー内のすべての後続アクションにも影響します。
  • ワークフローのタイムラインで、カスタムコードアクションをクリックします。
  • 下部にあるレート制限を設定をクリックして、レート制限セクションを展開します。
  • [レート制限をオンにする]スイッチをクリックしてオンに切り替えます**。 **デフォルトでは、この設定はオフになっています。
  • レート制限を設定します。
    • アクションの実行: 1期間あたりの最大実行回数を設定します。
    • 期間: レート制限の期間を設定します。この期間は、「秒」、「分」、または「時間」に設定できます。
レート制限のためにアクションが一時停止されている場合、アクションは実行されず、ワークフローのアクションログに次のエラーが表示されます:_設定されたレート制限内に収まるように、このアクションは一時停止されています。「日時」に再開されます。[ _
ワークフローレート制限セクション

アクションのテストを行う

ワークフローにカスタムコードアクションを追加する際は、ワークフローを有効にする前に、コードが想定どおりに実行されることを確認するために、アクションのテストが行えます。 カスタムコードアクションをテストするには、まず、コードのテストで使用するレコードを選択してから、コードを実行します。このテストでは、カスタムアクションのコードのみが実行され、ワークフローの他のアクションは実行されません。コードの実行が完了したら、コードの出力とテストのログを表示できます。

注:

カスタムコードをテストすると、コードが実行され、選択したテストレコードにあらゆる変更が適用されます。ライブレコードの更新を避けたい場合は、テスト専用のレコードを作成することをお勧めします。
カスタムコードアクションをテストするには、以下の手順に従ってください。
  • ワークフローのプレビューで、[カスタムコードアクション]をクリックします**。 **
  • 下部にある[アクションをテスト]をクリックしてテストセクションを展開します**。 **
  • [オブジェクト]ドロップダウンメニューをクリックし、テストするレコードを選択します**。 **
  • ワークフローで過去に書式設定されたプロパティー値を使用する場合は、書式設定されたデータのテスト値を入力します。
カスタムコードアクションをテスト
  • コードを実行するには、[テスト]をクリックします**。 **
  • 表示されるダイアログボックスで、[テスト]をクリックして、選択したレコードに対してコードをテストすることを確認します**。 **
  • コードの実行が完了すると、テストの結果が表示されます。
    • ステータス: カスタムコードアクションの成功または失敗のステータス。
    • データ出力: 定義されたデータ出力に対して得られた値。コードによって生成された、[データ出力]セクションでもコードエディターでも定義されていない出力の横にはアラートが表示されます。ワークフローで後で使用するには、これらの出力を追加する必要があります。
    • ログ: テスト自体に関する情報(アクションで使用されたメモリーの量、合計実行時間など)。
  • アクションのテストが完了したら、[保存]をクリックして変更を保存します**。 **
ワークフロー-カスタム-コード-アクション-テストの結果

シークレット

広く共有すべきではないものをコードに参照させなければならないこともあります。これは多くの場合、非公開アプリのアクセストークンなどの認証手段です。ワークフローアクションの定義で直接、関数がアクセスするシークレットを管理できます。カスタムコード内で複数のシークレットを使用する場合、全てのシークレット値の合計長は1,000文字以下でなければなりません。
ワークフロー-カスタム-コード-非公開
追加されたシークレットは環境変数として使用可能になり、以下に示すように、カスタムコードでその環境変数にアクセスできます。
const hubspot = require('@hubspot/api-client');
exports.main = (event, callback) => {
return callback(processEvent(event));
};
function processEvent(event) {
// secrets can be accessed via environment variables
const hubspotClient = new hubspot.Client({
accessToken: process.env.secretName,
});
hubspotClient.crm.contacts.basicApi
.getById(event['object']['objectId'], ['email', 'phone'])
.then((results) => {
let email = results.body['properties']['email'];
let phone = results.body['properties']['phone'];
// ...
})
.catch((err) => {
console.error(err);
});
}

カスタムコードにHubSpotプロパティーを追加する

場合によって、カスタムコードアクションでオブジェクトのプロパティーを取得しなければならないことがあります。その際にはHubSpotのAPIを使用する代わりに、必要なオブジェクトのプロパティーをワークフローアクション定義に直接追加できます。 プロパティーを追加して、コード内でプロパティーを参照するためのプロパティー名を設定します。プロパティーを追加すると、カスタムコードで参照できるようになります。カスタムコードアクションごとに最大50個のプロパティーの追加が可能です。
カスタムコードアクションのプロパティーを使用
const email = event.inputFields['email'];

ログ記録

開発者にとって重要なツールは、コードによる出力データを表示する機能です。問題をデバッグし、エンドユーザーへのサポートを改善するのに役立ちます。ログの出力を確認するには、ワークフローの アクションログのレビュー方法をご参照ください。

出力の定義方法

ワークフローの後半で使用する出力フィールドを関数で定義します。次に、出力するデータの型(数値、文字列、ブール値、日時、列挙、日付、電話番号など)を選択し、出力するフィールドを入力します。 出力フィールドは、使用されている言語に応じて書式設定された、JSONオブジェクトの一部にする必要があります。
callback({
outputFields: {
email: email,
phone: phone,
},
});
カスタム-コード-出力
コードアクションからの出力は、[レコードを編集]アクションへの入力として使用できます。これにより、値をオブジェクトのプロパティーとして保存するために別のAPI呼び出しを行う必要がなくなります。 出力を定義する際は、以下の点に留意してください。
  • 出力するデータの型が文字列形式の場合、文字列の出力値の上限は65,000文字です。この制限を超えると、OUTPUT_VALUES_TOO_LARGEエラーが発生します。
  • [レコードを編集]アクションを使用している場合は、対応するソースプロパティーとターゲットプロパティーにご注意ください。
  • 日付プロパティーを更新する場合
    • 出力を使用して日時プロパティーを更新する場合、出力はUNIXミリ秒形式である必要があります。
    • 日時プロパティーではなく日付プロパティーの更新に出力を使用する場合、出力はUNIXミリ秒形式である必要があり、かつ、日付の時刻が真夜中(UTC時間)に設定されている必要があります。
currentDate.setUTCHours(0,0,0,0)
カスタムコードアクションの出力の使用状況

制限事項

カスタムコードアクションは20秒以内に実行を完了する必要があり、使用できるメモリーは最大128 MBです。これらの制限に違反すると、エラーが発生します。

再試行

HubSpot APIを使用してオブジェクトのプロパティーを取得するか、カスタムコードアクションで別のHubSpot APIエンドポイントを呼び出す必要がある場合があります。他のAPI呼び出しと同様に、HubSpot APIのレート制限に従う必要があります。
  • Node.jsを使用している場合、レート制限エラーが発生してもHubSpotに呼び出しを再試行させるには、カスタムコードアクションのcatchブロックでエラーをスローする必要があります。
catchエラー
  • Pythonを使用している場合、レート制限エラーが発生してもHubSpotに呼び出しを再試行させるには、カスタムコードアクションのexceptブロックでエラーを報告する必要があります。
exceptエラー

注:

レート制限エラー、またはaxiosあるいは@hubspot/api-clientからの429もしくは5XXエラーにより呼び出しが失敗すると、HubSpotはエラー発生の1分後から最大3日間、そのアクションを再試行します。以降のアクション再試行が失敗した場合、徐々に間隔を延ばしてアクションが再試行されます。再試行の間隔は最大で8時間です。

注意事項

カスタムコードにNode.jsを使用している場合は、次の注意事項に留意してください。
  • 乱数の生成: 乱数を生成するにはMath.randomを使用するのが一般的ですが、異なる実行で同じ数値が生成される場合があります。これは、Math.randomは現在の時刻でシードされるためです。HubSpotは、多数のオブジェクトを同時にワークフローに登録し、実行ごとに状態をクリアするため、異なる実行でMath.randomへのシードが同じように行われる結果になります。代わりに、random-number-csprng 1.0.2(英語)ライブラリーを使用すると、暗号論的疑似乱数の生成が保証されます。
  • **変数の再利用:**メモリーを節約するには、exports.main関数の外部で宣言した変数を、カスタムコードアクションの以降の実行で再利用できます。これは、データベースなどの外部サービスに接続する場合に便利ですが、カスタムコードアクションの実行ごとに一意でなければならないロジックや情報は、exports.main関数に含める必要があります。
カスタムコードにPythonを使用している場合は、次の注意事項に留意してください。
  • 変数の再利用: 上記と同様に、def main関数の外部で宣言した変数は、カスタムコードアクションの以降の実行で再利用できます。
    • def main関数の外部で変数を宣言した場合、その変数に対するアラートを計画していないとしても、変数を直接参照できます。
    • 変数のアラートを計画する場合、その変数を参照する前にグローバルキーワードを使用したdef main関数内で変数を宣言できます。
a = 1
def main(event):
  global a
  a += 1