Workiva サポートセンター

背景

チェーンは、統合するシステムのREST APIを活用することで、Workivaプラットフォームだけでなく、様々なサードパーティシステムと相互作用します。  多くのREST APIレスポンスは、様々なWorkiva API を含むJSON書式である。  JSONのレスポンスはドキュメント化され、一貫した構造になっているかもしれないが、この書式設定のデータを操作するのは難しい。  JSON コネクターのArray to CSV コマンドは、Workiva プラットフォーム内で使用するために、JSON ペイロードを表（行＆列）書式に変換する便利な方法です。 

この記事では、JSONペイロードから必要な結果のみを返却するために、このコマンドのフィルター機能を使用する方法を探ります。  ペイロードは一般的に開発者によって決定され、エンドポイントのエンドユーザーは返されるデータのスコープを制限する能力を持っていないことが多いため、REST APIレスポンスは必要以上の情報を含むことが多いため、これは必要になることがあります。 

例として、Workiva Connector のList Files Command は、Workiva Wdata API からのRetrieve a List of Files エンドポイントを使用して、Wdata テーブルに関連付けられたすべてのファイルのリストを返します。  このエンドポイントのJSONレスポンスには以下の情報が含まれる：

 [ 
 { 
 "created": "2024-01-24T12:01:53.000Z", 
 "id": "89b34ac927fe499abf944571ded77983", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2024-01.csv", 
 "numRecords": 108808, 
 "originalFileSize": 26226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2024-01-24T12:02:03.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 },
 { 
 "created": "2023-12-18T15:06:56.000Z", 
 "id": "62f3d0b79b724776a4fae8bf25f711f1", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2023-12.csv", 
 "numRecords": 101789, 
 "originalFileSize": 24226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2023-12-18T15:06:56.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 }
]

Array to CSVコマンドでは、JSONレスポンスから取得できるフィールドのみを選択できます。  例えば、id、name、statusフィールドをコマンドの列入力セクションで選択することができます。  コマンドは、JSONレスポンスからすべてのファイルID、名称、ステータスを抽出し、JSONレスポンスに各ファイルの行を作成します。  

上記のリストファイルの例に引き続き、Workivaプラットフォーム内での一般的なユースケースは、Wdataテーブルのデータ（ファイル）を更新する必要があることです。  更新されたデータセット（ファイル）をインポートするには、既存のデータセットをテーブルから削除する必要があります。なぜなら、Wdataは同じ名称の複数のファイルを許可していないからです。  既存ファイルの削除を行うには、既存ファイルのIDとステータス（ステージング済みまたはインポート済み）を取得する必要があります。 

この情報を取得する1つのアプローチは、Array to CSVコマンドを使用してList Files JSONペイロードを表書式に変換することです。  次へ、Tabular TransformationSmart Filter Rows コマンドを使って、ファイル情報のある個々の行を分離する。  次に、Tabular TransformationExtract Value コマンドを使用して、ファイル ID と Status を取得する。  この記事では、これをレガシー・アプローチと呼ぶことにする。   

フィルターの使用

フィルター入力は、選択するフィールド（列）だけでなく、JSONペイロードから取得するアイテム（行）という用語でJSONレスポンスをフィルタリングすることができます。  これは、必要な特定のデータを選択する強力なメカニズムであり、統合プロセスの効率を向上させる。  フィルターは、JSONペイロードの1つまたは複数の要素、取得されるアイテム（行）の数を制限するために使用することができます。 

フィルター条件には、要素パス、比較値、演算子の3つの要素がある。  条件は真か偽の値に解決済みでなければなりません。  フィルター条件が真の値を返すと、コマンド列定義に従ってJSONペイロードからレコードが抽出され、結果のCSV出力に行として作成されます。  例：

• ファイルのステータスはステージングと同じですか？

この例では、ファイルステータスが要素パス、イコールが演算子、ステージングが比較値です。  JSONペイロードのファイルステータスがステージングのレコードは、CSVにコマンド構成で定義された列を含む行が作成されます。  この例では、ID、名称、ステータスである。

要素パス

フィルターを指定するには、要素へのパスがわかっていなければならない。  たとえば、List Files レスポンスでは、Status 要素へのパスは次のようになります：

ステータス

要素に関連付けられた値は、コマンド実行中に取得されます。  上記のペイロードの例では、status要素の値IMPORTEDとなる。 

注：要素パスは、 (@) 記号で始めなければなりません。

比較値

比較値は、要素パス値が比較される値です。  比較値は、コマンド構成で定義された静的な値にすることも、実行時に決定される変数や出力値を利用することもできる。  

演算子

演算子は、データをフィルターするために実行される評価のタイプを決定する。 

メモ： 要素パスと演算子の間（）と、演算子と比較値の間（）には間隔が必要である。

対応オペレーター

演算子を指定する際には、要素パスに存在する値のタイプを考慮することが重要である。  例えば、より大きい（>）演算子を使用すると、テキスト値を含む要素を評価するときに空白の出力が生成される可能性があります。テキスト値の数値評価は非論理的だからです。

フィルター構文とフィルター例

フィルターはすべてクエスチョンマーク(?)で始まり、括弧の中に含まれなければなりません。  

単一条件

単一の条件フィルターの条件は、以下の構文を使用する：

?(Element_Path Operator Comparison_Value)

?(@.name == "executions_2023-12.csv")

このフィルターは、名称要素がexecutions_2023-12.csv と等しいすべてのレコードを返却する。

複数の条件

複数条件フィルターは以下の構文を使う：

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")

このフィルターは、名称要素がexecutions_2023-12.csv に等しく、ステータス要素がIMPORTED に等しいすべてのレコードを返却します。

コマンド構成例

この例では、フィルター入力は、JSONペイロードの名称 要素を評価するように構成されている。  フィルターは、この例ではランタイム入力値である「年」と「月」に変数を使用している。  これにより、チェーン実行時に指定された年と月を動的にフィルターにアカウントさせることができる。  

フィルターの値

フィルターは、JSON レスポンスから必要な行だけを取得できるようにします。  これにより、コマンドによって生成される出力ファイルのサイズを小さくすることができ、チェーンのパフォーマンスを向上させることができる。 

さらに、JSONレスポンスから1行を分離しようとする場合、Dynamic Outputs を使用して、フィルターされたペイロードから特定の値を抽出し、チェーンの後続ノードで使用できるようにすることができます。 

下記はダイナミック出力の定義例を表示したものです。

その結果、レガシー・アプローチで必要な4つのノードのオペレーションを1つのノード（Array to CSV）で実行できるようになり、チェーンはより合理化された。  この合理化されたチェーンは、実行されるコマンドの数が少なく、結果として得られる出力も小さくなるため、より効率的に実行される。