Future Tech Blog
フューチャー技術ブログ
Infrastructureカテゴリ

Zuora連載 Vol.4 Workflowの話

はじめに

こんにちは。TIGの町田です。

Zuora Central Platform（Zuora社が提供するサブスクリプションプラットフォーム名の正式名称/以降 Zuora と記載いたします）の連載の第4回はWorkflowです。

Workflowは前回の記事で説明した通知機能と同じく、業務フローを設計する際に必ず理解する必要があります。また、Workflowは通知機能との組み合わせることが多いです。

他のZuora記事はこちらを参照ください。

目次

概要

Workflowの概要はWorkflow - Zuoraから引用します。

Zuora Workflow is a Zuora product for designing, configuring, and deploying business workflows in Zuora. With Workflow, you can automate a set of business processes that otherwise need to be performed manually and repetitively.
訳：Zuoraワークフローは、Zuoraでビジネスワークフローを設計、構成、および展開するためのZuora製品です。ワークフローを使用すると、手動で繰り返し実行する必要がある一連のビジネスプロセスを自動化できます。

とあるように、Zuoraに実際の業務に合わせた制御を加えるために必須の機能です。業務プロセスの自動化や業務フローの設計には必ずWorkflowを利用することになるでしょう。

Workflow開発方法

  1. Zuoraログイン後のサイドメニューにてプラットフォーム > ワークフロー を選択。 WorkflowのTOP画面であるOVERVIEWタブに遷移する。ここではWorkflowの実行状況やサマリを確認できる。
  2. WORKFLOWタブをクリックで、Workflow一覧画面に遷移する。右上の表示切替ボタンをクリックするとリスト形式の一覧にできます。編集したいWorkflowのEditボタンをクリックすることで、Workflow編集画面へと遷移する。
  3. Workflow編集画面: WorkflowはTaskと呼ばれる個々の機能を繋げ合わせることで完成する。
  4. ▶ボタンがあるTaskが開始Taskとなっている+ボタンをクリックすることで後続Taskを追加することができる。


  5. 開始Task移行のTask
  • 🖊ボタン：Taskの設定・編集
  • xボタン：Taskの削除
  • +ボタン：後続Taskを追加


  1. Taskの追加: 各Taskの+をクリック後、Task成功時はOn Success、Taskエラー時はOn Failureを選択して追加したいTaskを選択する。各Taskの機能についてはWorkflow - Zuoraを参照。

Workflow設定

  1. Workflowの設定にはWorkflow全体の設定を、Workflowごとの設定がある
    • Workflow全体設定：SETTINGSタブをクリック: Workflowのメンテナンスをするためのユーティリティ、Workflow開発ユーザの設定、外部SMTPサーバの設定が可能。初期設定以外で触ることはほとんどないと思われる。
    • Workflowごとの設定：各Workflow編集画面でSETTINGSタブをクリック
    • Workflow Information: Workflow名、説明の設定
    • Workflow Triggers: Workflowを実行する方法を選択
      • On Demand: チェックするとWorkflow一覧画面や編集画面から実行することができるようになる。
      • Callout: チェックするとAPIによるWorkflowの実行ができるようになる。
      • Scheduled: Cron形式でスケジュール実行の設定ができる。
    • Workflow Email Notifications: メールアドレスを設定することで、Workflow成功時、エラー時等にメールによる通知ができる。複数アドレス可。
    • Execution Priority: Workflowの優先度を設定。同時に実行中のWorkflowがあった場合には、優先度が高いWorkflowが優先して実行される。
    • Workflow Configuration: 設定不可
    • Callout Config: WorkflowをコールアウトAPIで実行する場合の情報について確認できる。
    • Mapped Input Fields and Params: Workflow内で利用可能な変数はここで定義する。
      コールアウトAPIによって呼ばれた際に、ここで設定したパラメータをリクエストBodyに設定することで値の受け渡しができる。

Workflow実行方法

Workflowの実行方法は以下3通りです。

  1. オンデマンド実行
  2. コールアウト実行
  3. スケジュール実行

Workflow設定のWorkflowごとの設定のWorkflow Triggersにてチェックした実行方法が有効となります。

（1）オンデマンド実行

  • Workflow一覧画面にて、実行したいWorkflowの▶Runをクリック
  • またはWorkflow編集画面で開始Taskの▶をクリック

（2）コールアウト実行

こちらのAPIによる実行。 Workflow設定のWorkflowごとの設定のCallout ConfigにてURLやRequest情報が確認できます。

Request例
curl --location --request POST 'https://workflow.apps.zuora.com/api/v1/workflows/{workflow_id}/run' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'API-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-raw '{
    "{params}":"xxxxxx"
}'

Bodyに設定するパラメータはWorkflow設定のWorkflowごとの設定のMapped Input Fields and Paramsにて設定したパラメータを設定します。

--data-raw '{
    "SubscriptionId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

※Workflow内では、'{{ Data.Workflow.SubscriptionId }}'のように取得する。

（3）スケジュール実行

Workflow設定のWorkflowごとの設定のWorkflow TriggersにてScheduledにチェックすると、Scheduled Config項目が表示されます。

設定はInterval欄にてcron形式で設定が可能だが、設定項目の各プルダウン項目を選択することでも設定が可能です。

Task

WorkflowはTaskの組み合わせて開発する。TaskについてはWorkflow - Zuoraに各Taskの機能説明あります。よく使うと思われるTaskを紹介します。

  1. Object Query
  2. Data Query
  3. CSVTranslator
  4. Callout

（1）Object Query

https://knowledgecenter.zuora.com/Central_Platform/Workflow/Workflow_tasks/AB_Query

Zuoraオブジェクトを選択してデータの取得を行うTaskです。

  • 選択

  • FIELDSタブで、選択したオブジェクトで取得したいフィールドを選択
* ```CONDITIONS```タブで、取得条件を設定する

（2）Data Query

https://knowledgecenter.zuora.com/Central_Platform/Workflow/Workflow_tasks/AC_data_query

SQL(ZOQLというらしい)によるデータのエクスポートを行うTask。Object Queryより柔軟なデータ取得ができます。

SQLを書くだけで、取得した結果はCSV、TSV、DSV、JSONにフォーマットして後続Taskに渡すことが可能です。

超えることはそうそうないとは思うが、Data Queryには制限があるため注意しましょう。

LIMIT(制限) VALUE(閾値)
Max Execution Time(最大実行時間) 120分
Max Number of Input Records(入力レコード最大数) 500K
Max Number of Output Records(出力レコード最大数) 100K
Number of Concurrent Queries(同時クエリ数) 5
Max Memory per Query(1クエリ毎の最大メモリ数) 2G

（3）CSVTranslator

Data Queryなどで取得した結果をJSON構造やXML構造に変換するためのTaskです。

変換だけでなく、取得したデータをFilterしたり、Mergeができます。

**JSONTransform**という、Data Queryなどで取得した結果をJSON構造に変換するためのTaskです。

クエリで取得した結果のデータをネストしたJSON構造などにする際にはこちらを利用する。主にJSONataという式を駆使して実装することになる。

JSONata式による実装は若干とっつきにくいが、JSONata Exerciserという便利ツールを利用することで、結果を確認しながら実装が可能です。

（4）Callout

https://knowledgecenter.zuora.com/Central_Platform/Workflow/Workflow_tasks/IC_Notifications_Callout

Workflow内で取得・加工した結果をCalloutAPIを呼び出して連携するためのTaskです。

  • BODYタブでRequest.Bodyに設定する値を定義する。こちらはLiquid式を利用して設定する。(HELPタブ参照)
  • AUTHENTICATIONタブで、Callout呼び出し時の認証について設定する。認証方式はBasic認証、OAuth2.0やhmacなど利用可能です。

Swimlane

Workflow開発時にデバッグをしたい場合に利用する機能です。詳細はこちら参照ください。

  • Workflow編集画面のTASKSタブを開くと、各タスクの実行履歴一覧が表示されるので、デバッグしたいTaskの行の一番左のメニューカラムをクリックしてSwimlaneをクリックする。
  • Swimlaneは一度でもWorkflowを実行してTask履歴が存在しないと確認できない。
  • Swimlane画面では、各タスクの実行状況と、Workflow内の各パラメータ値やデバッグが行える。
  • Workflow内で扱うパラメータ値。選択したTask時点のパラメータが表示される。
  • エラーが発生しているTaskは赤い表示


  • エラーの内容はInfoで確認できる。Workflow Task ConfigやInstance Configで設定変更してRerunで、そのTaskから再実行ができる。
  • Data QueryやCalloutによるWorkflow内でのAPI実行の結果は、API CallsでRequestやResponse内容が確認できる。

最後に

予期せぬ動きをさせないためには、Workflow全体の動きや個々のTaskの動作をよく理解した上で使いこなす必要はありますが、WorkflowはZuoraとの連携を行ったシステム構築や、Zuoraの基本機能から外れた制御を行う場合には、必ず必要となる機能になります。

Workflow開発リンク集

開発に役立つリンクです。

Workflow開発に便利なリンク集:

  • Liquid template language
    • Workflowの一部のTaskの設定ではLiquid式というテンプレート言語を利用してロジックを書くことになる
  • JSONata Exerciser
    • Workflowの一部のTaskでJSONata式でJSONフォーマットを行うことができます。上記はJSONataのテスターとして利用可能