ワークフロー基盤機能
1. ワークフロー基盤とは
ワークフロー基盤は、WebSAM Cloud の各製品から共通して利用できるワークフロー実行エンジンです。
事前に定義したフローに沿って HTTP リクエストや条件分岐などの処理を自動実行することができます。
ワークフロー基盤は以下の機能から利用できます。
| 対象 | 機能詳細 | 参照先 |
|---|---|---|
| WebSAM Cloud 通報サービス | パターンマッチ後にワークフローを実行し、通報の可否を制御する | 通報前ワークフロー |
| WebSAM Cloud ITサービスマネジメント | 承認完了後のリクエストチケットに対する作業を自動実行する | 作業の自動化 |
2. ワークフローの管理
ワークフローの登録・編集・削除は各製品の該当機能画面より行います。
ワークフロー選択ボタンを押下するとワークフロー設定画面（ワークフロー一覧画面）が開きます。
2-1. ワークフロー一覧画面
プロジェクトにて作成済みのワークフローが一覧として表示されます。
新しいワークフローを作成する場合は、ワークフロー一覧テーブルの右上にある＋ボタンを押下すると登録画面に移動します。
作成済みのワークフローの編集を行う場合は、ワークフローの名前を押下して編集画面に移動します。
 |
|---|
2-2. ワークフロー登録・編集画面
ワークフロー登録・編集画面は「基本情報」、「YAML」、「ワークフロー」の3つのタブで構成されます。
2-2-1. 基本情報
基本情報タブではワークフローの以下の情報を設定します。
 |
|---|
| 項目名 | 説明 | 補足 |
|---|---|---|
| 名前 | ワークフローの名前を入力します。 | 後から変更することが可能です。 |
2-2-2. YAML
YAMLタブではワークフローの定義をYAML形式のテキストで入力することができます。 ここで入力した内容はワークフロータブと連動します。
 |
|---|
ワークフローの定義内容にエラーがある場合、他のタブへ切り替えることはできません。
2-2-3. ワークフロー
ワークフローの定義をGUI編集する画面です。
ここで定義した内容はYAMLタブと連動します。
フローの設定方法についてフローの登録方法を参照してください。
 |
|---|
ワークフローの定義内容にエラーがある場合、他のタブへ切り替えることはできません。
3. ワークフロー実行結果の確認方法
3-1. ワークフロー実行結果詳細
ワークフロー実行結果詳細は「ワークフロー」タブと「詳細情報」タブから構成されます。
 |
|---|
「ワークフロー」タブではワークフロー図として実行結果を表示します。ワークフローに分岐が存在する場合、どの分岐で処理が実行されたかを確認することができます。 処理が正常終了したノードは緑、エラーが発生したノードは赤、実行されていないノードはグレーの線で表示されます。
 |
|---|
「詳細情報」タブではワークフローへのインプットパラメータや出力を参照することができます。
実行結果のサイズが大きい場合、詳細情報タブに実行結果が表示されず「実行結果をダウンロード」ボタンが表示されます。
ボタンを押下すると、実行結果をJSON形式のファイルとしてダウンロードできます。
 |
|---|
4. フローの登録方法
4-1. フロー登録画面のレイアウト
 |
|---|
| 項番 | 項目名 | 説明 |
|---|---|---|
| (1) | ワークフロー図 | ワークフローを描画するエリアです。余白領域をマウスドラッグするとスクロール、マウスホイールでズームイン・ズームアウトが行えます。 |
| (2) | ノードメニュー | ワークフロー図に配置可能な部品の一覧です。部品をワークフロー図側へドラッグ＆ドロップすることでノードとして配置できます。 |
| (3) | コントロールパネル | 各種操作を行うためのパネルです。ワークフロー図の拡大・縮小、表示領域の自動調整、編集ロック、ノードの自動配置を行うことができます。 |
| (4) | ノード | ワークフロー中で実行するタスクに対応する部品を矩形で表現したものです。部品の種類に応じて表示が異なります。 |
| (5) | 接続ライン | ノード間の接続です。タスクの実行順序や分岐を表現します。 |
4-2. ノードの編集方法
 |
|---|
| 項番 | 項目名 | 説明 |
|---|---|---|
| (1) | アイコン | 部品の種別を表すアイコンです。 |
| (2) | ノード名 | ノードの名前です。クリックすると編集することができます。 |
| (3) | 設定ボタン | クリックするとノードの設定画面を表示します。パス部品のように設定項目の存在しないノードの場合は表示されません。 |
ノードをワークフロー図に配置した際に Node_1, Node_2 のような名前が自動的に設定されますが、処理内容が把握しやすいように任意の名前を設定してください。 また、部品種別ごとに設定する項目があるので、設定ボタンをクリックして設定を行ってください。部品種別ごとの設定項目については各部品の説明を参照してください。
- ノード名はフロー全体で一意となる名前を設定してください
- ノード名の長さは 1 文字以上 64 文字以下で指定してください
- ノード名として利用可能な文字は以下の通りとなります
- 半角英数字
-および_
4-3. 接続ラインの編集方法
各ノードにはノード間を接続するためのハンドルが存在します。ハンドルは丸印で表現されます。また、ハンドルは入力用と出力用に分かれており、ノード上部に配置されているハンドルが入力用、下部に配置されているハンドルが出力用です。出力ハンドル同士や入力ハンドル同士での接続はできません。 出力/入力ハンドルをドラッグして接続先の入力/出力ハンドル上でドロップすることでノード間の接続ラインが作成されます。
 |
|---|
すでに接続されているラインについてはラインの端から接続先ハンドルへドラッグ＆ドロップを行うことで接続ラインを付け替えることができます。
 |
|---|
特定の接続ラインを削除したい場合は、接続ラインをクリックして選択した後にDeleteキーまたはBackspaceキーを押下してください。
- ひとつのハンドルに接続可能なラインの数は部品ごとに決まっています。分岐部品のBranchハンドル以外では1つのラインのみ接続可能です。
- フローの先頭である開始ノードは入力ハンドルを持ちません。
- フローの終端である終了部品のノードは出力ハンドルを持ちません。
5. JSONPath式
ワークフローの各ノードの設定項目ではJSONPath式を利用することができます。
JSONPath式は以下のような形式の文字列として記述します。
$.input$.results.<ノード名>.status$.output(<ノード名>)
ワークフロー実行時のインプットパラメータを参照する場合は $.input.<入力パラメータ名> の形式で、
先行ノードの実行結果（HTTPステータスコード）を参照する場合は$.results.<ノード名>.status 、実行結果（HTTPレスポンスボディ）を参照する場合は $.output(<ノード名>).<出力パラメータ名> の形式で記述します。
参照可能な値はワークフローの実行状況によって変わります。以下の図はワークフロー中で参照可能な値がどのように更新されるかを示しています。
初期状態では input 以外は何もありませんが、ワークフローの実行状態に応じて参照可能な値が results 配下に追加されていきます。
 |
|---|
実行されていないノードについては results に値が格納されませんので、ワークフローに分岐を作成した場合はJSONPath式で存在しない値を参照しないように注意してください。
5-1. JSONPath式の記述方法
JSONPath式には以下の2つの記述方法があります。
単体での使用
JSONPath式を単体で使用する場合は、そのまま記述します。
$.results.health_check.status
$.output(api_call).items[0].id
この形式は、値全体をJSONPath式の評価結果で置き換える場合に使用します。
文字列への埋め込み
JSONPath式を文字列の一部として埋め込む場合は、{{}} で囲んで記述します。
https://example.com/api/{{$.output(Node_1).user_id}}/profile
"User: {{$.output(api_call).name}}, Age: {{$.output(api_call).age}}"
この形式は、固定文字列とJSONPath式の評価結果を組み合わせる場合に使用します。複数のJSONPath式を1つの文字列内に埋め込むこともできます。
Key,Value形式でのJSONPath式の使用
Key,Value形式のJSON設定項目でJSONPath式を使用する場合は、Keyに .$ サフィックスを付与する必要があります。
{
"status.$": "$.results.health_check.status",
"first_item.$": "$.output(api_call).items[0]"
}
この形式は、終了部品の出力やリクエストヘッダなど、Key,Value形式で値を設定する項目で使用します。
5-2. 部品別 JSONPath式対応表
各部品の設定項目で使用できるJSONPath式は以下の通りです。
HTTPリクエスト部品
| 設定項目 | JSONPath式の使用 | 使用可能な形式 | 備考 |
|---|---|---|---|
| メソッド | ○ | GET/POST/PUT/DELETE$.input.* | 固定値またはJSONPath式で指定可能 |
| URL | ○ | http(s)://~ 形式$.input.*$.output(<ノード名>).<キー>※ | 固定値またはJSONPath式で指定可能 |
| リクエストヘッダ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
| リクエストクエリ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
| リクエストボディ | ○ | JSON形式: Key,Value形式 $.input.*$.output(<ノード名>).<キー>※x-www-form-urlencoded形式: key=value形式$.input.*$.output(<ノード名>).<キー>※ | JSON形式: Key: 英数字、 -、_、参照形式(.$)が利用可能Value: 固定値またはJSONPath式を指定可能 x-www-form-urlencoded形式: 固定値またはJSONPath式を指定可能 |
※ <キー> 部分には以下を指定可能:
- ドット(
.)と英数字、ハイフン(-)、アンダースコア(_)の組み合わせ - または上記と
[数値](配列インデックス)の組み合わせ
例: $.output(Node_1).response.items[0].id, $.output(api_call).data.users[5].name
HTTPステータスチェック部品
| 設定項目 | JSONPath式の使用 | 使用可能な形式 | 備考 |
|---|---|---|---|
| URL | ○ | http(s)://~ 形式$.input.*$.output(<ノード名>).<キー>※ | 固定値またはJSONPath式で指定可能 |
| リクエストヘッダ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
| リクエストクエリ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
※ <キー> 部分には以下を指定可能:
- ドット(
.)と英数字、ハイフン(-)、アンダースコア(_)の組み合わせ - または上記と
[数値](配列インデックス)の組み合わせ
例: $.output(Node_1).response.items[0].url, $.output(api_call).data.endpoints[2].path
HTTPポーリング部品
| 設定項目 | JSONPath式の使用 | 使用可能な形式 | 備考 |
|---|---|---|---|
| メソッド | ○ | GET/POST/PUT/DELETE$.input.* | 固定値またはJSONPath式で指定可能 |
| URL | ○ | http(s)://~ 形式$.input.*$.output(<ノード名>).<キー>※ | 固定値またはJSONPath式で指定可能 |
| リクエストヘッダ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
| リクエストクエリ | ○ | Key,Value形式$.input.*$.output(<ノード名>).<キー>※ | Key: 英数字、 -、_、参照形式(.$)のみ利用可能Value: 固定値またはJSONPath式を指定可能 |
| リクエストボディ | ○ | JSON形式: Key,Value形式 $.input.*$.output(<ノード名>).<キー>※x-www-form-urlencoded形式: key=value形式$.input.*$.output(<ノード名>).<キー>※ | JSON形式: Key: 英数字、 -、_、参照形式(.$)が利用可能Value: 固定値またはJSONPath式を指定可能 x-www-form-urlencoded形式: 固定値またはJSONPath式を指定可能 |
| ポーリング終了条件(変数名) | ○ | $.self.body.<キー>※$.self.status$.input.*$.results.<ノード名>.status$.output(<ノード名>).<キー>※ | ポーリング専用の$.self.*が使用可能 |
※ <キー> 部分には以下を指定可能:
- ドット(
.)と英数字、ハイフン(-)、アンダースコア(_)の組み合わせ - または上記と
[数値](配列インデックス)の組み合わせ
例: $.self.body.response.items[0].status, $.output(Node_1).data.user_name
ポーリング終了条件の変数名について
HTTPポーリング部品の終了条件では、通常のJSONPath式に加えて以下の特殊な変数が使用できます:
$.self.body.<キー>- 現在のレスポンスボディの特定の値を参照$.self.status- 現在のレスポンスのHTTPステータスコードを参照
分岐部品
| 設定項目 | JSONPath式の使用 | 使用可能な形式 | 備考 |
|---|---|---|---|
| 分岐条件(変数名) | ○ | $.input.*$.results.<ノード名>.status$.output(<ノード名>).<キー>※ | 条件評価に使用する変数を指定 |
※ <キー> 部分には以下を指定可能:
- ドット(
.)と英数字、ハイフン(-)、アンダースコア(_)の組み合わせ - または上記と
[数値](配列インデックス)の組み合わせ
例: $.output(Node_1).response.data[0].value, $.output(api_check).result.error_code
終了部品
| 設定項目 | JSONPath式の使用 | 使用可能な形式 | 備考 |
|---|---|---|---|
| 出力 | ○ | Key,Value形式 | Key: 英数字、 -、_、参照形式(.$)が利用可能Value: 固定値またはJSONPath式を指定可能 |
終了部品の出力について
JSONPath式で値を取り込む場合、Keyに .$ サフィックスを付与する必要があります。
例:
{
"status.$": "$.results.health_check.status",
"first_item.$": "$.output(api_call).items[0]"
}
パス部品
JSONPath式は使用しません(設定項目なし)。
6. ワークフロー部品
6-1. HTTPリクエスト
 |
|---|
任意のURLに対してHTTPリクエストを実施し結果を取得します。
アクセス先のURL等はパラメータとして設定が必要です。
各設定項目ではJSONPath式の使用可否については、部品別 JSONPath式対応表を参照してください。
 |
|---|
| 項目名 | 説明 | 補足 |
|---|---|---|
| メソッド | GET/POST/PUT/DELETEのいずれかを指定します。 | JSONPathによる指定も可能 |
| URL | アクセス先のURLを http(s)://～ 形式で指定します。 | JSONPathによる指定も可能 |
| リクエストヘッダ | リクエストヘッダをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
| リクエストクエリ | クエリパラメータをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
| リクエストボディ | リクエストボディを指定します。 | JSONPathによる指定も可能 |
HTTPリクエスト部品は出力ハンドルをひとつしか持たないため、レスポンスに応じて処理を分岐したい場合は分岐部品と合わせて利用する必要があります。 GETリクエストのステータスコードに応じて分岐したい場合はHTTPステータスチェック部品を、レスポンスが特定の条件を満たすまで繰り返しリクエストを実行したい場合はHTTPポーリング部品を利用できます。
この部品は以下の出力を持ちます。
| 項目名 | 説明 |
|---|---|
$.results.<ノード名>.status | HTTPステータスコード |
$.output(<ノード名>) | レスポンスボディ |
6-2. HTTPステータスチェック
 |
|---|
任意のURLに対してHTTP GETリクエストを実施し、レスポンスのステータスコードに応じて処理を分岐します。
アクセス先のURL等はパラメータとして設定が必要です。
各設定項目ではJSONPath式の使用可否については、部品別 JSONPath式対応表を参照してください。
 |
|---|
| 項目名 | 説明 | 補足 |
|---|---|---|
| URL | アクセス先のURLを http(s)://～ 形式で指定します。 | JSONPathによる指定も可能 |
| リクエストヘッダ | リクエストヘッダをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
| リクエストクエリ | クエリパラメータをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
ステータスコードが200番台の場合はSuccessブランチへ、それ以外の場合はFailureブランチへ分岐します。
HTTPステータスチェック部品は1回のリクエストでステータスコードを確認します。繰り返しリクエストを実行して条件を満たすまで待機したい場合は、HTTPポーリング部品を利用してください。
この部品は以下の出力を持ちます。
| 項目名 | 説明 |
|---|---|
$.results.<ノード名>.status | HTTPステータスコード |
$.output(<ノード名>) | レスポンスボディ |
6-3. HTTPポーリング
 |
|---|
任意のURLに対してHTTPリクエストを一定間隔で繰り返し実施し、レスポンスが指定した条件を満たすまでポーリングを継続します。
アクセス先のURL等はパラメータとして設定が必要です。
各設定項目ではJSONPath式の使用可否については、部品別 JSONPath式対応表を参照してください。
 |
|---|
| 項目名 | 説明 | 補足 |
|---|---|---|
| メソッド | GET/POST/PUT/DELETEのいずれかを指定します。 | JSONPathによる指定も可能 |
| URL | アクセス先のURLを http(s)://～ 形式で指定します。 | JSONPathによる指定も可能 |
| リクエストヘッダ | リクエストヘッダをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
| リクエストクエリ | クエリパラメータをJSONのKey,Value形式で指定します。 | JSONPathによる指定も可能 |
| リクエストボディ | リクエストボディを指定します。 | JSONPathによる指定も可能 |
| ポーリング終了条件 | ポーリングを終了する条件を設定します。 | 下記の説明を参照 |
| ポーリング回数 | ポーリングを実行する最大回数を指定します(1〜100)。 | |
| ポーリング間隔時間(分) | ポーリング間隔を分単位で指定します(1〜300)。 | ポーリング回数×ポーリング間隔時間の上限は1440分(1日) |
ポーリング終了条件
ポーリング終了条件はSimple条件、AND条件、OR条件を組み合わせて表現します。
Simple条件では、レスポンスの特定の値と比較値を評価する条件を設定できます。
評価方法として以下の演算子が利用可能です。
- 存在する - 指定した変数が存在するかを評価
- = (文字列) - 指定した変数と指定した値が文字列で一致するかを評価
- = (数値) - 指定した変数と指定した値が数値で一致するかを評価
- > (数値) - 指定した変数の値が指定した値より大きいかを評価
- ≥ (数値) - 指定した変数の値が指定した値以上かを評価
- < (数値) - 指定した変数の値が指定した値より小さいかを評価
- ≤ (数値) - 指定した変数の値が指定した値以下かを評価
AND条件、OR条件は複数の条件を組み合わせて評価します。また、NOT条件を設定することで条件を反転させることもできます。
ポーリング終了条件を満たした場合はSuccessブランチへ、最大ポーリング回数に達しても条件を満たさなかった場合はFailureブランチへ分岐します。
ポーリング終了条件で指定できる変数については、JSONPath式のHTTPポーリング部品を参照してください。
この部品は以下の出力を持ちます。
| 項目名 | 説明 |
|---|---|
$.results.<ノード名>.status | HTTPステータスコード |
$.output(<ノード名>) | レスポンスボディ |
6-4. 分岐
 |
|---|
ワークフローへの入力または先行部品の出力を参照して処理を分岐します。
分岐条件で使用できるJSONPath式については、部品別 JSONPath式対応表を参照してください。
分岐部品はDefaultハンドルとBranchハンドルの2つの出力ハンドルを持ちます。
Branchハンドルは複数のノードと接続することができ、接続したノードの数だけ分岐が追加されます。 Branchハンドルと接続しているノードが存在する場合、ノードの設定ボタンから分岐条件を設定することができます。 Defaultハンドルと接続したノードは分岐条件のいずれにも該当しない場合の分岐先となります。
分岐条件の設定画面は以下のような構成となります。
 |
|---|
| 項番 | 項目名 | 説明 |
|---|---|---|
| (1) | 分岐先ノード名 | 分岐先ノードの名前が表示されます。 |
| (2) | 分岐条件 | (1)に表示されたノードへ分岐する条件を設定するエリアです。 |
(1)と(2)のセットがBranchハンドルへ接続されたノードの数だけ表示されます。表示順はBranchハンドルへ接続した順番となります。 また、分岐条件は上から順番に評価されるため、複数の分岐条件が満たされた場合はその中で最も上に記述されているノードへ分岐します。
分岐条件の記述方法
分岐条件はSimple条件、AND条件、OR条件を組み合わせて表現します。
Simple条件では、変数の特定の値と比較値を評価する条件を設定できます。
評価方法として以下の演算子が利用可能です。
- 存在する - 指定した変数が存在するかを評価
- = (文字列) - 指定した変数と指定した値が文字列で一致するかを評価
- = (数値) - 指定した変数と指定した値が数値で一致するかを評価
- > (数値) - 指定した変数の値が指定した値より大きいかを評価
- ≥ (数値) - 指定した変数の値が指定した値以上かを評価
- < (数値) - 指定した変数の値が指定した値より小さいかを評価
- ≤ (数値) - 指定した変数の値が指定した値以下かを評価
AND条件、OR条件は複数の条件を組み合わせて評価します。また、NOT条件を設定することで条件を反転させることもできます。
6-5. パス
 |
|---|
何も処理を行わない部品です。
パス部品はワークフローの開始ノードとしての利用を想定しており、それ以外の用途はありません。
6-6. 終了
 |
|---|
フローの終了を表す部品です。フローの終端には必ず終了部品を配置する必要があります。
終了部品ではワークフローの出力を設定できます。
出力でのJSONPath式の使用方法については、部品別 JSONPath式対応表を参照してください。
 |
|---|
| 項目名 | 説明 | 補足 |
|---|---|---|
| 出力 | ワークフローの出力をKey,Value形式のJSONフォーマットで指定します。 | 下記の説明を参照 |
出力に指定した値はワークフローの実行結果として参照可能な値となります。
ValueとしてJSONPath式を記述することで先行ノードの実行結果を取り込むことができます。
ただし、ValueにJSONPath式を記述する場合はKeyにはサフィックスとして .$ を付与する必要があります。
例えば、ノード名が health_check であるHTTPステータスチェック部品の出力項目 status を取り込む場合は以下のように記述します。
{
"status.$": "$.results.health_check.status"
}
JSONPath式で指定しているノード名が存在しない場合や存在しない出力項目を参照しようとした場合、ワークフロー実行時にエラーとなります。
7. 注意事項
- ワークフローのノード数やポーリング回数には上限があります。ノードや分岐が多い場合、処理が失敗することがあります。失敗した場合は、ポーリング回数や分岐、ノード数を減らすなど、フローの見直しを行ってください。