トランスフォーメーションマップを作成する
プロジェクトビューを開き、作成 > 変換マップを選択して新しい変換マップを作成します。マップを設定およびテストするには、次のセクションを参照してください:
入力スキーマと出力スキーマの定義
変換マップの入力スキーマと出力スキーマを定義するには、エディターで次のいずれかの方法を選択します。
フィールドのマッピングと変換
変換マップエディターでは、次の方法でスキーマ値をマッピングできます。
- 入力フィールドを出力フィールドに直接接続して、変換せずに値を渡します。
- コネクションまたは入力フィールドでFormulaを追加をクリックして、Formulaを使用してフィールドの値を変換します。 Workatoは、Formulaノードを入力および出力スキーマ間のトランスフォーメーション領域に保存します。設定手順については、Formula変換を参照してください。
- 出力フィールドで Set value をクリックし、他のフィールドに依存しない静的式を使用して値を設定します。設定手順については、静的値の設定を参照してください。
フィールドをマッピング
マッピングパターン
ほとんどのマップは、次のパターンを組み合わせます。
- 1対1: 値を変更する必要がない場合は、単一の入力フィールドを単一の出力フィールドに直接接続します。
- 多対1: 複数の入力フィールドを1つの出力フィールドに結合します。 Formulaを追加をクリックし、Formula内の各入力を参照します。たとえば、
first_nameとlast_nameを単一のfull_nameフィールドに連結したり、明細項目を合計に集計したりします。 Formulaの結果が出力フィールドに送られます。例については、Reshape a listを参照してください。 - 1対多: 単一の入力フィールドまたはFormula出力を複数の出力フィールドに接続します。たとえば、同じ
full_nameの結果を使用して、full_nameフィールドとdisplay_nameフィールドの両方に入力します。
ノードとコネクションの削除
Formulaノードまたはコネクションにカーソルを合わせて、そのツールバーを表示します。
- コネクションツールバー: Formulaを追加と、コネクションを削除するオプションが含まれます。チェーン内の各コネクションは個別に削除する必要があります。
- ノードツールバー: Edit formula(鉛筆アイコン)と、ノードを削除するオプションが含まれます。
コネクションツールバー
Formula変換
Workato Expression Language (WEL) を使用してフィールドの値を変換するFormulaノードを追加するには、次の手順を実行します。
参照する前に接続
Formulaは、それに接続した入力にしかアクセスできません。ノードの Available inputs セクションに、これらの入力が一覧表示されます。 Formulaで入力フィールドを参照する前に、そのフィールドをノードに接続する必要があります。
コネクションまたは入力フィールドでFormulaを追加をクリックします。 Formulaを適用モーダルが開きます。
Formulaを適用モーダル
一意のFormula名を入力します。下流のノードは、このノードの出力を正規化された名前の形式で参照します。 Workatoが参照をどのように構成するかについては、Formula name and reference rulesを参照してください。
FormulaエディターにFormulaを入力します。 Available inputs セクション内のフィールドをクリックするか、Formulaエディタにドラッグ&ドロップして、参照を挿入できます。 Formulaは、表示名ではなく参照によってフィールドを参照します。たとえば、first_nameの参照は_.first_nameです。
ネストされた値の参照
Formulaは、ノードに接続したスカラー、オブジェクト、配列などのトップレベル要素にしか直接参照できません。オブジェクトや配列内のキーなどのネストされた要素も、スキーマを確認できるように Available inputs に表示されますが、親要素を通じてアクセスする必要があります。
入力を挿入
任意。出力スキーマセクションを使用して、Formulaノードの出力フィールドを定義します。設定手順については入力スキーマと出力スキーマの定義を参照し、このFormulaに出力定義が必要かどうかを判断するには出力スキーマを定義するタイミングを参照してください。
定義済みの出力スキーマを持つFormulaは、出力フィールド名と完全に一致するキーを持つハッシュを返す必要があります。リストを生成するFormulaは、スキーマのルートで配列を宣言できないため、ベア配列としてではなく、名前付きキーの下にそのリストを返す必要があります。
設定を完了するには、適用をクリックします。
Formulaのチェーン
Formulaノードは、入力フィールドまたは出力フィールドに直接接続する必要はありません。複数のノードを接続して、複雑なロジックを1つの大きな式ではなく、読みやすいステージに分割します。上流のノードの出力スキーマは、下流のノードのAvailable inputsリストに表示され、参照が競合しないように、その前に上流のノードのFormula名が付きます。フィールドをクリックするかドラッグして、正確な参照を挿入します。 Formulaをチェーンする例についてはChain a transformation with filter and sortを、参照の詳細についてはFormula name and reference rulesを参照してください。
Formula名と参照ルール
Formulaは、値の由来に応じて、次の2つの方法のいずれかで値を参照します。
コネクションからの値: ノードに接続されているすべての入力フィールドと上流のノード出力は、スキーマ内でどれだけ深い位置にあっても、Available inputs内では単一のフラットな名前として表示されます。入力フィールドは、
_.の後にフィールド名を続けて参照します。Formulaからの値: ラムダパラメータや
letバインディングなどで値が名前にバインドされた後は、ドットを使ってその内部を走査します。ドット表記は、すでに取得している構造内を移動します。これはコネクションをまたいで伝播しません。
Workato は、上流のノードの出力からの参照にそのノードの Formula 名を接頭辞として付与することで、ノードが同じ出力フィールド名を使用している場合でも、異なるノードからの参照が衝突しないようにします。 WorkatoがFormula名の後に追加する内容は、ノードに宣言済みの出力スキーマがあるかどうかによって異なります。
定義済みの出力スキーマを持つノード: Workatoは各出力フィールド名をFormula名に追加するため、複数の出力フィールドを持つノードは複数の参照を生成します。
出力スキーマがないノード: スカラ型Formulaには出力フィールド名がないため、WorkatoはFormula名の末尾に
valueを付加します。
WorkatoはFormula名を正規化しますが、フィールド名は正規化しません。参照では、Formula名内のスペースをアンダースコア(_)に置き換え、その他の特殊文字をすべて削除し、小文字に変換します。名前のどの部分も切り捨てられません。 Workatoは、出力フィールド名を定義どおりに、大文字と小文字も含めてそのまま保持します。
| ソース | リファレンス |
|---|---|
linesという名前の入力フィールド | _.lines |
出力フィールドlinesを持つノードline totals | _.line_totals_lines |
出力スキーマのないノードtotal | _.total_value |
出力スキーマのないノードnet-total | _.nettotal_value |
出力フィールドtotalAmountを持つノードSummarize By Category | _.summarize_by_category_totalAmount |
出力スキーマのないノードa@@@b!!@@@sasD@@! | _.absasd_value |
ラムダパラメーターlのフィールド | l.sku |
ノード出力参照はFormula名とフィールド名を連結するため、両方の名前が長いと長い参照になります。参照を読みやすくするには、Formula名を短くします。
正規化された形式でのミスを防ぐため、Available inputs セクション内のフィールドをクリックまたはドラッグして、正確な参照を挿入します。
出力スキーマを定義するタイミング
Formulaに出力スキーマが必要かどうかは、Formulaが返す内容によって異なります。
FormulaがString、Number、Integer、Date、Time、Booleanなどの単一のスカラー値を返す場合は、出力スキーマを定義する必要はありません。 Workatoはスカラー結果をFormula名の後に_valueを付けて参照します。これはスカラー出力フィールドに直接接続できます。参照の構築方法については、Formula名と参照ルールを参照してください。 Formulaが複雑なオブジェクトまたは配列を返す場合、または複数の名前付き値を返す場合は、出力スキーマを定義します。宣言されたスキーマによって、WorkatoはFormulaが生成する構造を検証し、下流のFormulaやノードに型付きフィールドを公開できます。これがないと、Workatoは非スカラー結果を検証したり渡したりできません。
Formulaの出力は、他のFormulaを含む複数の下流ターゲットに渡すことができます。マップは循環コネクションをサポートしていません。
静的値の設定
出力フィールドで値を設定をクリックして、入力に接続せずにその値を設定します。次のいずれかのアプローチを使用します。
- 値をハードコードします。たとえば、
signup_formの定数sourceを設定します。 - 入力フィールドに依存しない WEL 式を入力します。たとえば、ランタイム時にタイムスタンプを生成します。
出力フィールドには、固定値か入力側からのコネクションのどちらか一方のみを保持でき、両方を同時には保持できません。フィールドにコネクションを描画すると、Workatoはそのフィールドの静的値をクリアします。
ポートと検証
フィールドとノードは、ポートと呼ばれるコネクションポイントを公開します。キャンバスは、コネクションの開始時に有効なポートをハイライト表示し、循環コネクションや、ネストレベルやデータ型が互換でないコネクションなどの無効なコネクションをブロックします。
互換性のないデータ型: 宣言済みの出力スキーマがないFormulaは単一のスカラー値を返すため、オブジェクトまたは配列のターゲットには接続できません。詳細については、出力スキーマを定義するタイミングを参照してください。
非互換のネストレベル: オブジェクトや配列などの非スカラーフィールドへのアクセスはトップレベルから内側に向かって行われるため、コネクションはネストされたフィールドからトップレベルへのみ実行でき、その逆方向には実行できません。別の配列内にネストされた配列の値を使用するには、まずFormulaで構造をフラット化します。フラット化の方法については、内側の配列の反復処理を参照してください。
未完了または無効な状態でも、変換マップを保存できます。たとえば、ぶら下がっているFormulaノード、切断されたFormulaノード、不足しているFormulaノード、またはFormulaが返す内容と一致しない出力スキーマがある状態です。 Workatoは保存をブロックするのではなく、これらの状態に警告でフラグを付けます。これにより、作業中の内容を保存し、後で戻ることができます。マップを有効に保つには、ぶら下がっているノードまたは切断されたノードを削除し、各ノードの出力が定義済みスキーマと一致することを確認します。
ランタイムエラーは、保存時ではなくレシピのジョブ履歴に表示されます。
配列
リストを運ぶコネクションは二重線で表示され、配列を運んでいることを示します。たとえば、次のLinesリスト間のコネクションは配列コンテキスト内にあります。
Linesリスト間のコネクションは配列コンテキスト内にあります
内側の配列の反復処理
内側の配列とは、linesリストの各要素にあるunitsリストなど、別の配列内にネストされた配列です。アクセスはトップレベルから始まり内側に向かって機能するため、内側の配列を直接接続または参照することはできず、外側の配列を内側の配列に接続することもできません。
外側の配列をノードに接続し、Formula内でルートから内側の要素までフラット化します。ノードは外側の配列を受け取り、各要素をたどり、その要素の内側の配列をたどって、結果を単一のリストにフラット化します。内側の要素を処理している間に、外側の要素から必要な値を読み取ります。そうしないと、フラット化されたリストには親に関する情報が保持されません。例については、Flatten a nested arrayを参照してください。
フラット化により、内側の各要素に対して1行が生成され、データの形状が変わります。
マップのテスト
テストタブではライブプレビューを利用できます。サンプル入力を入力すると、エディターを離れたりマップを先に保存したりすることなく、Workatoが出力を即座に表示します。これにより、構築しながらマッピングを確認できます。
変換マップをテストするには、次の手順を実行します。
テストタブをクリックします。
サンプル入力JSONを入力します。
テストタブ
出力パネルで結果を確認します。パネルには、出力値、またはマッピングが失敗した場合はエラーメッセージが表示されます。
最終更新日:
...をクリックして入力スキーマメニューを表示
スキーマを生成するためのサンプルを指定
フィールドを手動で追加