変換マップ ​

変換マップは、システム間でデータを整形およびマッピングするロジックを一元化するプロジェクトアセットです。この作業は、通常はレシピステップ、Formulaモード、カスタムコードに分散しています。 保存する前に、エディターでマッピングをエンドツーエンドで直接テストし、同じロジックを複数のレシピで再利用できます。

Workato Expression Language（WEL）のFormulaノードを使用してデータを変換するか、入力を出力に直接マッピングして、変換せずに値を渡します。

プロジェクトビューを開き、作成 > 変換マップを選択して新しい変換マップを作成します。 既存の変換マップを選択して、その場所、作成時刻と変更時刻、アセットタグ、説明、依存レシピ、最近のアクティビティを表示します。

変換マップの概要

入力スキーマと出力スキーマの定義 ​

変換マップの入力スキーマと出力スキーマを定義するには、エディターで次のいずれかの方法を選択します。

フィールドのマッピングと変換 ​

変換マップエディターでは、次の方法でスキーマ値をマッピングできます。

• 入力フィールドを出力フィールドに直接接続して、変換せずに値を渡します。
• コネクションまたは入力フィールドでFormulaを追加をクリックして、Formulaを使用してフィールドの値を変換します。 Formula変換ノードは、入力スキーマと出力スキーマの間の変換領域に保存されます。 設定手順については、Formula変換を参照してください。
• 出力フィールドで値を設定をクリックして、他のフィールドに依存しない静的式を使用して値を設定します。 設定手順については、静的値の設定を参照してください。

フィールドをマッピング

マッピングパターン ​

ほとんどのマップは、次のパターンを組み合わせます。

• 1対1: 値を変更する必要がない場合は、単一の入力フィールドを単一の出力フィールドに直接接続します。
• 多対1: 複数の入力フィールドを1つの出力フィールドに結合します。 Formulaを追加をクリックし、Formula内の各入力を参照します。 たとえば、first_nameとlast_nameを単一のfull_nameフィールドに連結したり、明細項目を合計に集計したりします。 Formulaの結果が出力フィールドに送られます。 例については、リストの整形を参照してください。
• 1対多: 単一の入力フィールドまたはFormula出力を複数の出力フィールドに接続します。 たとえば、同じfull_nameの結果を使用して、full_nameフィールドとdisplay_nameフィールドの両方に入力します。

ノードとコネクションの削除 ​

Formulaノードまたはコネクションにカーソルを合わせると、それらのツールバーが開きます。

• コネクションツールバー: Formulaを追加と、コネクションを削除するオプションが含まれます。 チェーン内の各コネクションは個別に削除する必要があります。
• ノードツールバー: Formulaを編集（鉛筆アイコン）と、ノードを削除するオプションが含まれます。

コネクションツールバー

Formula変換 ​

WELを使用してフィールドの値を変換するFormulaノードを追加するには、次の手順を実行します。

Formulaのチェーン ​

Formulaノードは、入力フィールドまたは出力フィールドに直接接続する必要はありません。 複数のノードを接続して、複雑なロジックを1つの大きな式ではなく、読みやすいステージに分割します。 アップストリームノードの出力スキーマは、ダウンストリームノードの使用可能な入力リストに表示されます。参照が競合しないように、アップストリームノードのFormula名がプレフィックスとして付加されます。 正確な参照を挿入するには、コピーをクリックします。 チェーンされたFormulaの例についてはフィルターとソートを使用した変換のチェーンを参照し、参照の詳細についてはFormula名と参照ルールを参照してください。

Formula名と参照ルール ​

Formulaは、値の由来に応じて、次の2つの方法のいずれかで値を参照します。

• コネクションからの値: ノードに接続されたすべての入力フィールドとアップストリームノード出力は、スキーマ内の深さに関係なく、使用可能な入力に単一のフラットな名前として表示されます。 入力フィールドは、_.の後にフィールド名を続けて参照します。

• Formulaからの値: 値がラムダパラメーターやletバインディングなどの名前にバインドされたら、ドットを使用してその中をたどります。 ドット表記は、すでに取得している構造内を移動します。 コネクションをまたぐことはありません。

Workatoは、アップストリームノードの出力からの参照にそのノードのFormula名をプレフィックスとして付加するため、2つのノードが同じ出力フィールド名を使用していても、異なるノードからの参照が競合することはありません。 WorkatoがFormula名の後に追加する内容は、ノードに宣言済みの出力スキーマがあるかどうかによって異なります。

• 定義済みの出力スキーマを持つノード: Workatoは各出力フィールド名をFormula名に追加するため、複数の出力フィールドを持つノードは複数の参照を生成します。

• 出力スキーマのないノード: スカラーFormulaには出力フィールド名がないため、Workatoは代わりにvalueをFormula名に追加します。

WorkatoはFormula名を正規化しますが、フィールド名は正規化しません。 参照はFormula名を取得し、各スペースをアンダースコア（_）に置き換え、その他すべての特殊文字を削除し、結果を小文字に変換します。 名前のどの部分も切り捨てられません。 出力フィールド名は、大文字小文字の区別を含め、定義したとおりに使用されます。

ノード出力参照はFormula名とフィールド名を連結するため、両方の名前が長いと長い参照になります。 参照を読みやすくするには、Formula名を短くします。

正規化された形式の誤りを避けるため、手入力ではなく、使用可能な入力セクションでコピーをクリックして正確な参照を挿入します。

出力スキーマを定義するタイミング ​

Formulaに出力スキーマが必要かどうかは、Formulaが返す内容によって異なります。

FormulaがString、Number、Integer、Date、Time、Booleanなどの単一のスカラー値を返す場合、出力スキーマを定義する必要はありません。 Workatoはスカラー結果をFormula名の後に_valueを付けて参照します。これはスカラー出力フィールドに直接接続できます。 参照の構築方法については、Formula名と参照ルールを参照してください。 Formulaが複雑なオブジェクトまたは配列を返す場合、または複数の名前付き値を返す場合は、出力スキーマを定義します。 宣言済みスキーマにより、WorkatoはFormulaが生成する構造を検証し、型付きフィールドをダウンストリームのFormulaとノードに公開できます。 これがないと、Workatoは非スカラー結果を検証したり渡したりできません。

Formulaの出力は、他のFormulaを含む1つ以上のダウンストリームターゲットに送ることができます。 マップは循環コネクションをサポートしていません。

静的値の設定 ​

出力フィールドで値を設定をクリックして、入力に接続せずにその値を設定します。 次のいずれかのアプローチを使用します。

• 値をハードコードします。 たとえば、signup_formの定数sourceを設定します。
• 入力フィールドに依存しないWEL式を入力します。 たとえば、ランタイム時にタイムスタンプを生成します。

出力フィールドは、静的値または着信コネクションのいずれか一方を保持し、両方を保持することはありません。 すでに静的値があるフィールドにコネクションを描画すると、その静的値はクリアされます。

ポートと検証 ​

フィールドとノードは、ポートと呼ばれるコネクションポイントを公開します。 コネクションを開始すると、キャンバスは有効なポートを強調表示し、循環コネクションや、互換性のないネストレベルまたはデータ型間のコネクションなど、無効なコネクションをブロックします。

互換性のないデータ型: 宣言済みの出力スキーマがないFormulaは単一のスカラー値を返すため、オブジェクトまたは配列のターゲットには接続できません。 詳細については、出力スキーマを定義するタイミングを参照してください。

互換性のないネストレベル: オブジェクトや配列などの非スカラーフィールドへのアクセスはトップレベルから始まり内側に向かって機能するため、コネクションはネストされたレベルからトップレベルにのみ実行でき、その逆はできません。 別の配列内にネストされた配列の値を使用するには、まずFormulaで構造をフラット化します。 フラット化の方法については、内側の配列の反復処理を参照してください。

未完了または無効な状態でも、変換マップを保存できます。たとえば、ぶら下がっているFormulaノード、切断されたFormulaノード、不足しているFormulaノード、またはFormulaが返す内容と一致しない出力スキーマがある状態です。 Workatoは保存をブロックするのではなく、これらの状態に警告でフラグを付けます。これにより、作業中の内容を保存し、後で戻ることができます。 マップを有効に保つには、ぶら下がっているノードまたは切断されたノードを削除し、各ノードの出力が定義済みスキーマと一致することを確認します。

ランタイムエラーは、保存時ではなくレシピのジョブ履歴に表示されます。

配列 ​

リストを運ぶコネクションは、配列コンテキストで動作していることを示すために二重線で表示されます。 たとえば、次のLinesリスト間のコネクションは配列コンテキスト内にあります。

Linesリスト間のコネクションは配列コンテキスト内にあります

内側の配列の反復処理 ​

内側の配列とは、linesリストの各要素にあるunitsリストなど、別の配列内にネストされた配列です。 アクセスはトップレベルから始まり内側に向かって機能するため、内側の配列を直接接続または参照することはできず、外側の配列を内側の配列に接続することもできません。

外側の配列をノードに接続し、Formula内でルートから内側の要素までフラット化します。 ノードは外側の配列を受け取り、各要素をたどり、その要素の内側の配列をたどって、結果を単一のリストにフラット化します。 内側の要素を処理している間に、外側の要素から必要な値を読み取ります。そうしないと、フラット化されたリストには親に関する情報が保持されません。 例については、ネストされた配列のフラット化を参照してください。

フラット化により、内側の各要素に対して1行が生成され、データの形状が変わります。

マップのテスト ​

テストタブではライブプレビューを利用できます。 サンプル入力を入力すると、エディターを離れたりマップを先に保存したりすることなく、Workatoが出力を即座に表示します。 これにより、構築しながらマッピングを確認できます。

変換マップをテストするには、次の手順を実行します。

テストケースを履歴タブに追加するには、入力を保存をクリックします。 保存したテストケースは、履歴タブから再実行または削除できます。

履歴タブ

レシピで変換マップを使用 ​

保存済みの変換マップをレシピに適用するには、Mapper by Workatoコネクターを使用します。 スキーマの取得元を決定するには、コネクターのマッピング方法入力フィールドで次のいずれかのオプションを選択します。

• Common data model > オブジェクトスキーマ: Common data modelオブジェクトスキーマを選択します。 ワークスペースにマッピング方法フィールドが表示されない場合は、これが唯一のオプションです。
• 変換マップ > 変換マップ: 保存済みの変換マップを選択します。

Workatoは、選択したスキーマに基づいて追加の入力フィールドを生成します。 これらのフィールドを使用して、スキーマにデータを入力します。

例 ​

次の例は、一般的な連携パターンの完全な変換マップを示しています。 欠落フィールドが含まれる可能性のあるプロダクションデータには、これらの例にnull処理を追加してください。

リストの整形 ​

インバウンドシステムがある形状の項目リストを送信し、ターゲットシステムが各項目に別の形状を必要とする場合に、このパターンを使用します。たとえば、異なるフィールド名に加えて、各項目について計算する必要がある値がある場合です。

この例では、eコマース注文webhookがsku、qty、unit_priceを含む注文行を送信します。 ERPでは、product_code、quantity、行ごとのamountを含む項目が必要です。

リストの整形

{
  "order_id": "SO-1001",
  "lines": [
    { "sku": "A-100", "qty": 2, "unit_price": 9.5 },
    { "sku": "B-220", "qty": 1, "unit_price": 40 }
  ]
}

{
  "order_number": "SO-1001",
  "items": [
    { "product_code": "A-100", "quantity": 2, "amount": 19.0 },
    { "product_code": "B-220", "quantity": 1, "amount": 40.0 }
  ]
}

_.unit_price * _.qty

この整形では、リスト全体に対するFormulaは必要ありません。 order_id、sku、qtyは変更されずに渡される名前変更であるため、計算されるamountフィールドだけにFormulaが必要です。

totalノードは、数量に単価を掛けて、行ごとの合計を生成します。 単一のスカラー値を返すため、ノードに出力スキーマは必要ありません。 IntegerにNumberを掛けると、Numberが返されます。

group-byによる集計 ​

行単位のコピーではなくサマリーが必要な場合に、このパターンを使用します。たとえば、リストをキーでグループ化し、各グループの件数または合計を計算する場合です。

この例では、同じ注文行にcategoryが含まれています。 ターゲットでは、カテゴリごとに行数と合計金額を含む1行が必要です。

group-byによる集計

{
  "order_id": "SO-1001",
  "lines": [
    { "sku": "A-100", "category": "hardware", "qty": 2, "unit_price": 9.5 },
    { "sku": "B-220", "category": "hardware", "qty": 1, "unit_price": 40 },
    { "sku": "C-050", "category": "service", "qty": 3, "unit_price": 15 }
  ]
}

{
  "order_number": "SO-1001",
  "totals_by_category": [
    { "category": "hardware", "line_count": 2, "total_amount": 59.0 },
    { "category": "service", "line_count": 1, "total_amount": 45.0 }
  ]
}

{
  totals_by_category: _.lines
    >> group_by(line ~> line.category)
    >> entries
    >> map_by(g ~> {
         category: g.key,
         line_count: count(g.value),
         total_amount: g.value >> map_by(l ~> l.qty * l.unit_price) >> sum
       })
}

order_idは、1対1の名前変更と同様に、変更されずにorder_numberに直接接続されます。 集計に必要なフィールドはlinesだけであるため、linesだけがsummarize by categoryノードに送られます。

summarize by categoryノードは、3つのステージで集計を実行します。 group_byは、カテゴリごとに行を1つのバケットに収集します。これにより、リストではなくマップが生成されます。 entriesは、そのマップをキーと値のペアのリストとして再表現し、反復処理できるようにします。 その後、map_byは各ペアに対して1つのオブジェクトを返します。このオブジェクトには、カテゴリ名、グループ内の行数、行合計の合計が含まれます。

ノードはオブジェクトのリストを返すため、出力スキーマが必要です。 出力スキーマを定義するタイミングを参照してください。

フィルターとソートを使用した変換のチェーン ​

変換を複数のステージで実行する場合に、このパターンを使用します。 チェーンにより、各ステージが独自のノードに保持されるため、キャンバスから変換を読み取り、各ステージを個別にテストできます。

この例では、注文行にsku、qty、unit_priceが含まれています。 マップは行ごとの合計を計算し、しきい値を下回る行を除外し、残った行を合計でソートします。各ステージは独自のノードにあります。

フィルターとソートを使用した変換のチェーン

{
  "order_id": "SO-1001",
  "lines": [
    { "sku": "A-100", "qty": 2, "unit_price": 9.5 },
    { "sku": "B-220", "qty": 1, "unit_price": 40 },
    { "sku": "C-050", "qty": 3, "unit_price": 15 },
    { "sku": "D-410", "qty": 2, "unit_price": 60 }
  ]
}

{
  "high_value_lines": [
    { "sku": "D-410", "amount": 120.0 },
    { "sku": "C-050", "amount": 45.0 },
    { "sku": "B-220", "amount": 40.0 }
  ]
}

{
  lines: _.lines
  >> map_by(l ~> {
   sku: l.sku,
   amount: l.qty * l.unit_price
  })
}

{
  filtered: _.line_totals_lines >> filter_by(t ~> t.amount >= 20)
}

{
  high_value_lines: _.filter_filtered >> sort_by(f ~> 0 - f.amount)
}

マップは3つのノードを使用し、それぞれが1つのステージを処理します。

• line_totalsは、qtyにunit_priceを掛けて行ごとの合計を計算します。
• filterは、合計が20以上の行のみを保持します。
• sortは、残りの行を合計の高い順から低い順に並べ替えます。

各ノードは、_.line_totals_linesや_.filter_filteredなど、アップストリームFormula名によって前のノードの出力を参照します。 チェーン内のすべてのノードはリストを返すため、それぞれに独自の出力スキーマが必要です。 出力スキーマを定義するタイミングを参照してください。

4行から4つの合計が生成され、フィルターによって19のA-100が削除され、ソートによって120のD-410が45のC-050と40のB-220より前に配置されます。

3つのステージすべてを1つのノード内の単一のFormulaとして記述できます。これにより同じ結果が生成され、必要な出力スキーマは1つだけです。 各ステージを個別にテストしたい場合、または単一のFormulaが読みにくくなる場合は、代わりにステージをチェーンします。

ネストされた配列のフラット化 ​

必要な値が別の配列内にネストされた配列にある場合に、このパターンを使用します。 内側の配列には直接アクセスできないため、変換はトップレベルの配列から開始し、内側の要素までフラット化します。 詳細については、配列を参照してください。

この例では、linesはオブジェクトのリストであり、各行には独自のオブジェクトのunitsリストがあります。 ターゲットでは、各ユニットに対して、そのユニットの元となった行のskuを含む1行が必要です。

ネストされた配列のフラット化

{
  "order_id": "SO-1001",
  "lines": [
    {
      "sku": "A-100",
      "units": [
        { "serial_number": "SN-1", "condition": "new" },
        { "serial_number": "SN-2", "condition": "refurbished" }
      ]
    },
    {
      "sku": "B-220",
      "units": [
        { "serial_number": "SN-3", "condition": "new" }
      ]
    }
  ]
}

{
  "units": [
    { "sku": "A-100", "serial_number": "SN-1", "condition": "new" },
    { "sku": "A-100", "serial_number": "SN-2", "condition": "refurbished" },
    { "sku": "B-220", "serial_number": "SN-3", "condition": "new" }
  ]
}

{
  units: _.lines
    >> map_by(l ~> l.units >> map_by(u ~> {
         sku: l.sku,
         serial_number: u.serial_number,
         condition: u.condition
       }))
    >> flatten
}

flatten unitsノードは各行をたどり、その行のunitsリストをたどって、結果を単一のリストにフラット化します。 合計3つのユニットを含む2行から、3行が生成されます。

Formulaは各ユニットを処理している間に親行からskuを読み取ります。これにより、すべての行が元の行から値を保持します。 これがない場合でもノードはフラット化しますが、結果にはユニットフィールドのみが含まれ、各ユニットがどの行から来たかを示す情報は含まれません。

ノードはオブジェクトのリストを返すため、出力スキーマが必要です。 出力スキーマを定義するタイミングを参照してください。

2つの配列の結合 ​

ペイロードに、注文行と製品カタログなど、共有キーで関連付ける必要がある2つのリストが含まれている場合に、このパターンを使用します。

この例では、linesにはskuと数量が含まれ、productsには各skuの名前と価格が含まれます。 ターゲットでは、各行に対して1つのエンリッチされた項目が必要です。

2つの配列の結合

{
  "lines": [
    { "sku": "A-100", "qty": 2 },
    { "sku": "B-220", "qty": 1 }
  ],
  "products": [
    { "sku": "A-100", "name": "Widget", "unit_price": 9.5 },
    { "sku": "B-220", "name": "Gadget", "unit_price": 40 }
  ]
}

{
  "items": [
    { "sku": "A-100", "name": "Widget", "qty": 2, "amount": 19.0 },
    { "sku": "B-220", "name": "Gadget", "qty": 1, "amount": 40.0 }
  ]
}

let catalog = _.products >> map_by(p ~> [p.sku, p]) >> from_pairs do

{
  items: _.lines >> map_by(l ~>
    let p = catalog[l.sku] do
      {
        sku: l.sku,
        name: p.name,
        qty: l.qty,
        amount: l.qty * p.unit_price
      })
}

join productsノードは、行を処理する前に、skuをキーとしてproductsからルックアップを一度構築します。 その後、各行は、行ごとに製品リストを再検索するのではなく、そのルックアップから製品を直接読み取ります。 ノードは各行に対して1つの項目を返し、行の数量と一致した製品の名前、およびその価格から計算された金額を組み合わせます。

ノードはオブジェクトのリストを返すため、出力スキーマが必要です。 出力スキーマを定義するタイミングを参照してください。

この変換では、lines内のすべてのskuがproducts内に存在する必要があります。 ルックアップに存在しないキーを検索すると、空の値を返すのではなく、Cannot access fieldエラーでマッピングが失敗します。そのため、ソースデータに一致しないキーが含まれる可能性がある場合は、フォールバックを追加します。 productsに同じskuが複数回含まれる場合、ルックアップはそのキーの最後のエントリを保持し、それ以前のエントリを破棄します。

制限事項 ​

変換マップには現在、次の制限があります。

• Formulaの位置は保存されません。 Workatoは、マップを開くたびにFormulaを自動的に配置します。
• Formulaエディターはオートコンプリートまたはデータピルをサポートしていません。
• ジョブ履歴エラーは、そのエラーを生成した特定の変換マップバージョンにリンクされません。

変換マップには、マップごとに次のクォータも適用されます：