会員積立の残高管理をZoho CRMで自動化した事例の、実装解説編です。前提となる全体像は導入編の記事で紹介しています。この記事では、モジュール設計、残高計算のDeluge関数、CSV取込からの自動化までを具体的に解説します。フィールド名やAPI名はすべて例です。実際の環境では自動で振られるAPI名(例:field1)に読み替えてください。

モジュール構成

会員台帳には標準の連絡先モジュールを使い、次のフィールドを追加します。会員コード(重複を許可しない)、現在残高(通貨)、入金累計(通貨)、出金累計(通貨)です。会員コードはCSVと突き合わせるキーなので、重複禁止が必須です。残高系の3つは関数が書き込む値なので、読み取り専用にして手作業による事故を防ぎます。

入出金履歴は専用のカスタムモジュールを作ります。会員へのルックアップ、取引種別(入金/出金の選択リスト)、金額(通貨)、振替結果コード(選択リスト。成功=0、失敗=1以降)を持たせます。CSVを加工せず取り込むなら、CSVの他の列を受けるテキストフィールドも用意しておきます。

会員コードで紐づける

入出金明細を連絡先に紐づけるキーは会員コードです。CSVインポート時に、CSVの会員コード列を「会員(ルックアップ)」にマッピングし、照合先を連絡先の会員コードに指定します。これで各明細行が、その会員コードを持つ連絡先に自動でぶら下がります。紐付けを一意に保つため、連絡先の会員コードは重複禁止にしておくことが前提です。

残高を計算する関数

残高計算の核は、ある会員の入出金明細を全件集めて合計し、連絡先に書き戻すDeluge関数です。引数として会員のレコードIDを受け取ります。処理の流れは、会員に紐づく明細を検索し、1件ずつ入金・出金を判定して合計し、最後に連絡先を更新する、というものです。

ポイントが2つあります。1つは、入金と出金を取引種別で見分け、入金は加算・出金は減算すること。もう1つは、入金のうち振替結果コードが成功のものだけを合計し、失敗した行は除外することです。これにより、CSVを加工せずとも失敗した引き落としが残高に含まれなくなります。

擬似コードで示すと、次のような判定です。取引種別が出金なら出金累計に加算する。そうでなければ(入金なら)、振替結果コードが空または成功のときだけ入金累計に加算する。最後に、現在残高=入金累計-出金累計を計算して書き戻します。

なお、金額は入金・出金ともプラスの値で保持します。符号は関数が取引種別を見て付けるので、入力時にマイナスを打つ必要はありません。

大量データを検索するときの注意

会員の明細を検索するときは、ページングに気をつけます。1回の検索で取得できる件数には上限があるため、ページ番号を回しながら全件を取得します。環境によっては無限ループの構文が使えないので、あらかじめ決めた回数のループで回し、取得件数が上限未満になったら抜ける、という書き方にします。

CSV取込からの自動化

残高計算の関数ができたら、CSV取込をきっかけに自動で走らせます。仕組みはこうです。入出金明細が作成または編集されたときに発火するワークフローを作り、そこから関数を呼びます。CSVインポート時にワークフローを実行する設定にしておけば、取り込んだ明細1件ごとにワークフローが発火します。

ここで1つ、Zho特有の制約があります。ワークフローが渡してくるのは、発火した明細レコードのIDであって、会員IDではありません。また、Delugeでは別の関数を関数名で直接呼び出せません。そこで、ワークフローから呼ぶ関数は、明細IDを受け取って、そこから会員IDを取り出し、残高計算のロジックまで一気に実行する形にまとめます。

処理の流れは、渡された明細IDでレコードを取得し、ルックアップから会員のIDを取り出し、その会員の明細を集計して連絡先に書き戻す、というものです。1件の発火につきその会員1人だけを再計算するので、大量取込でも処理は現実的な範囲に収まります。集計は冪等なので、同じ会員が複数回再計算されても結果は常に正しくなります。

運用上のポイント

いくつか実運用で押さえるべき点があります。CSVインポート時は、最後の画面でワークフローを実行する設定を有効にしないと、取込レコードに発火せず残高が更新されません。会員コードは、CSVと連絡先で桁数やゼロ埋めまで完全に一致させる必要があります。会員コードは合成値(分類+番号+枝番など)であることが多いので、この一致は特に注意が必要です。出金は、取引種別を出金にして履歴を手入力すれば、金額はプラスのままで残高から自動的に差し引かれます。

まとめ

会員積立の残高管理は、連絡先を台帳にし、入出金を別モジュールで記録し、集計を関数に任せる、という構成で自動化できました。失敗した引き落としの除外や、CSVを加工しない前提での自動化など、実際の運用に耐えるための工夫を関数側に寄せているのが要点です。同じような積立・前受金・ポイント残高の管理にも応用が利く設計です。