> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 將 EDI 850 採購訂單對映為 CSV
> 使用知行之橋的對映工具將 X12 850 採購訂單轉換為扁平 CSV 檔案。
export const siteNameShort = "知行之橋";
export const siteName = "知行之橋";
## 概觀
{siteName} 包含強大的資料轉換工具，支援將 EDI 文件（如 X12、EDIFACT 等）對映到扁平檔案結構，如逗號分隔值 (CSV) 檔案。本指南重點介紹如何將 X12 850 文件（採購訂單）對映為 CSV 格式。本文描述的方法同樣適用於其他 EDI 文件的對映；但對映值之間的具體關係可能會有所不同。
本指南首先概觀 {siteNameShort} 如何處理 EDI 對映，然後逐步講解工作流程的每個步驟。請參閱 [範例檔案](#範例檔案) 檢視本指南中使用的 X12 850 輸入和 CSV 輸出文件。
### 影片資源
觀看此影片，瞭解 {siteNameShort} 中的資料轉換概覽。
## {siteName} 中的 EDI 對映
### 與 XML 之間的相互轉換
{siteNameShort} 使用 XML 作為資料轉換和操作的中間格式。大多數對映專案的第一步是將來源檔案格式（本例中為 X12）轉換為 XML，最後一步是將 XML 轉換為目標格式（本例中為 CSV）。
由於與 XML 之間的轉換是資料轉換中至關重要的一步，{siteNameShort} 包含了許多專門用於 XML 轉換的端口。本指南使用 [X12 端口](../connectors/x12) 和 [CSV 端口](../connectors/csv)。這些端口會自動將其檔案格式轉換為 XML。使用這些端口，源格式（X12 850 採購訂單）和目標格式（具有所需列的 CSV 檔案）都可以建模為 XML。
### 轉換 XML
一旦源格式和目標格式都被建模為 XML，任務就是將一種 XML 結構轉換為另一種。這透過 [XML Map 端口](../connectors/xml-map/xml-map) 來完成。
XML Map 端口需要範例 **源** 和 **目標** 範本檔案，分別代表起始和結束的 XML 結構。指定這些檔案後，XML Map 端口的視覺化設計器將填充這兩個 XML 結構。
在 XML Map 端口的視覺化設計器中，可以從源結構中拖放元素到目標結構中的元素上，以建立它們之間的對映關係。此對映步驟需要了解來源檔案資料，以便在輸出檔案中包含適當的元素。
XML Map 端口包含值格式化器、條件邏輯，甚至支援自定義指令碼，以便在對映過程中操作和計算資料。
建立對映關係後，XML Map 端口可以自動將任何匹配源 XML 結構的檔案轉換為具有目標 XML 結構的檔案。在本範例中，這意味著 X12 850 文件的 XML 模型會自動轉換為 CSV 檔案的 XML 模型。最後一步是使用 CSV 端口取得此 XML 模型並將其轉換為實際的 CSV 檔案。
### 扁平化採購訂單
將 850 採購訂單對映到 CSV 時，一個特定的概念挑戰是需要 *扁平化* 採購訂單。單個 850 文件可以包含多個訂單，每個訂單可以包含不同數量的行專案。相比之下，CSV 檔案具有用於儲存資料的靜態列數。
由於 CSV 列數無法擴充套件以適應 850 中變化的訂單數量，因此無法將一個 850 對映到 CSV 檔案中的單條記錄（行）。同樣，由於 CSV 列數無法擴充套件以適應訂單中變化的行專案數量，因此無法將一個訂單對映到單行 CSV。CSV 中的每一行必須儲存訂單中單個行專案的資料，因為無論 850 中的行專案和訂單數量多少，單個行專案都可以表示為一組靜態值。扁平化 850 會將其多層且多變的結構簡化為一組靜態行專案。
XML Map 端口使用 `Foreach` 迴圈關係的概念在對映期間扁平化結構。在這種情況下，會 *為每一個* 850 中的行專案建立一個新的 CSV 行。在 XML Map 端口中建立這種關係，只需在視覺化設計器中將一個元素（代表行專案的 `PO1` 元素）拖動到另一個元素（代表 CSV 記錄的元素）上即可。使用 XML Map 端口扁平化結構很容易，但必須瞭解源和目標 XML 結構，以便建立適當的 Foreach 關係。
### 摘要
在 {siteNameShort} 中建立對映需要以下步驟：
* 使用特定於輸入格式的端口（本例中為 X12 端口）將範例輸入檔案（如 X12 850 文件）轉換為 XML
* 使用特定於輸出格式的端口（本例中為 CSV 端口）將範例輸出檔案（如具有所需列的 CSV 檔案）轉換為 XML
* 將生成的 XML 檔案用作 XML Map 端口的來源檔案和目的檔案
* 在 XML Map 端口的視覺化設計器中拖放元素，以建立源和目標 XML 結構之間的關係
結果是一個自動化工作流程，它接受 X12 文件作為輸入並傳回 CSV 檔案作為輸出。
## 建立對映工作流程
本節描述了在 {siteNameShort} 中建立一個工作流程，將範例 850 採購訂單對映到扁平 CSV 檔案所需的步驟。
### 第 1 步：X12 端口
此對映工作流程的第一步是將範例源文件（X12 850）轉換為 XML。
這由 X12 端口完成，它將 X12 文件轉換為 XML，並可以在轉換期間選擇性地驗證 X12 交換頭。在 X12 端口之前是一個觸發端口（在以下範例中為 AS2），它接收 X12 850 文件並將其直接傳遞給 X12 端口。用例可能需要不同的觸發端口，例如 SFTP。有關可能適合用例的端口型別的詳細資訊，請參閱 [端口類別](../connectors/connectors#categories)。
點選導覽列上的 **工作流程**，然後將觸發端口（本例中為 AS2）和 X12 端口新增到工作區畫布（參見 [設計工作流程](../flows/designing-a-flow) 瞭解說明）。最佳實踐是在 **端口 ID** 欄位中包含傳送 X12 文件的交易夥伴名稱（下圖中為 Amazon）。連線 AS2 和 X12 端口。
#### 配置 X12 端口
在 X12 端口的 [設定頁面](../connectors/x12#settings-tab) 上，將 **轉換型別** 設定為 `X12-to-XML`。這使 X12 端口在將 X12 文件轉換為 XML 格式時驗證 X12 交換頭（以確保 X12 文件已傳送至預期方並被其接收）。
預設情況下，勾選了 **動態處理夥伴**。這意味著端口會自動從 EDI 交易中識別並跟蹤交易夥伴關係。在這種情況下，不需要手動配置夥伴，因為端口會在許可限制內動態管理所有夥伴。端口還會根據配置的設定填充交換和功能群組值。本指南使用預設設定。請參閱 [X12 端口設定](../connectors/x12#connector-configuration) 瞭解取消勾選該項後需要執行的操作。
如果 **使用指示符** 設定為 `T-Test Data`，則不執行驗證。
在本指南範圍內無需進一步配置，但具體的用例可能需要。請檢視 [X12 文件](../connectors/x12) 瞭解完整詳情。
#### 上傳測試檔案
導航到 X12 端口的 **交易** 頁面，點選 **更多 > 上傳測試檔案**。
瀏覽包含對映所需 X12 段的範例 850 文件。可能需要聯絡交易夥伴以取得範例 X12 文件。用於編寫本指南的 850 文件在 [此處](#x12-850)。
**上傳測試檔案** 會指示 X12 端口在內部儲存上傳文件的 XML 模型（而不是將 XML 作為輸出檔案推送到 **交易** 頁面）。此 XML 模型稍後將由 XML Map 端口使用。
### 第 2 步：CSV 端口
下一步是將範例目標文件（具有適當列的 CSV 檔案）轉換為 XML。這使用 CSV 端口完成，它在 XML 和 CSV 之間轉換檔案。
在工作流程中新增一個 CSV 端口例項。**不要** 將其連線到 X12 端口。另外新增一個終結端口例項（本例中為 [File](../connectors/file)）。它充當工作流程中的最後一個端口。連線 CSV 和 File 端口。
#### 配置 CSV 端口
開啟 CSV 端口的 [設定](../connectors/csv#connector-settings) 頁面。此對映工作流程所需的唯一 CSV 端口配置屬性是 **包含列標題**。如果對映工作流程生成的 CSV 檔案頂部應有一行列標題名稱，請啟用此項。
#### 生成或上傳範例檔案
導航到 CSV 端口的 **範例檔案** 頁面，然後點選 **新增範例檔案**。如果已經有一個包含適當列（以及標題，如果啟用了 **包含列標題**）的範例 CSV 檔案，請選擇 **檔案上傳** 並瀏覽檔案。或者，選擇 **手動建立** 直接在應用程式中建立 CSV 檔案。如果選擇 **手動建立**，請為範例檔案命名。點選 **下一步**。
如果瀏覽了現有檔案，**檢視檔案** 頁面將填充其內容。如果選擇手動建立檔案，請在此頁面輸入範例資料。
點選 **下一步**。**轉換和預覽** 會顯示轉換為 XML 的範例資料預覽。對範例滿意後，點選 **新增**。
用於編寫本指南的 CSV 檔案在 [此處](#csv)。
上傳測試檔案後，CSV 端口會儲存其 XML 模型。此 XML 模型將在下一步中使用。
### 第 3 步：XML Map 端口
現在 X12 端口和 CSV 端口已經生成了源文件和目標文件的 XML 模型，使用 XML Map 端口將一種 XML 結構轉換為另一種。
在工作流程中新增一個 XML Map 端口例項，然後將 X12 端口連線到 XML Map 端口，將 XML Map 端口連線到 CSV 端口。
#### 配置 XML Map 端口
在 XML Map 端口的 **XML 對映** 頁面上，端口應預先從 X12 端口測試檔案填充 **源**，並從 CSV 端口範例檔案填充 **目標**。
如果未顯示，請驗證測試檔案是否已正確上傳，以及端口是否已在工作流程畫布中連線。有關如何使用對映編輯器的詳細說明，請參閱 [對映](../mapping/mapping) 文件中的 [配置對映](../mapping/mapping-config)。
#### 理解 XML 結構
在 XML Map 端口中建立正確的對映關係需要理解源結構和目標結構在 XML 中是如何表示的。
結構中有兩種型別的 XML 元素（節點）。*父* 節點和 *葉* 節點定義了 XML 資料的層級結構，其中父節點對相關元素進行分組，葉節點代表要對映的實際資料值。使用父節點旁邊的展開和收起按鈕可以顯示或隱藏其葉節點。有關更多資訊，請參閱 [對映節點](../mapping/mapping-config#mapping-nodes)。
* 在 850 XML 中，每個 EDI *迴圈* 和 *段* 都是父節點。每個單獨的 EDI *元素* 都是葉節點。
* 在 CSV XML 中，根 *Items* 元素的每個直接子元素被稱為 *記錄* 元素：它代表 CSV 中的一個不同行。每個 *記錄* 元素都是父節點，*記錄* 元素的子元素都是 *列* 元素：它們各自代表一條記錄的一個欄位或一列。每個 *列* 元素都是葉節點。
在 XML Map 端口中，父節點只能對映到其他父節點，葉節點只能對映到其他葉節點。將 EDI 對映到 CSV 時的主要挑戰是選擇正確的 *迴圈* 或 *段* 元素（來自 EDI 源）拖動到 *記錄* 元素（在 CSV 目標中）。然後，可以將 EDI *元素* 節點拖動到 *列* 節點上，以便用 EDI 文件中的特定值填充 CSV。
## 建立對映
在為 XML Map 端口配置了源和目標結構後，透過在設計器中拖放節點來建立對映。
對映主要透過兩個步驟建立：
1. 在父節點之間建立 Foreach 迴圈關係
2. 在已建立的 Foreach 迴圈中對映葉節點之間的值
有關處理迴圈的更多詳情和其他範例，請參閱 [對映迴圈](../mapping/mapping-config#mapping-loops)。
### 建立 Foreach 迴圈
Foreach 關係意味著每當源中出現一個元素時，就應在目標中建立一個新的 XML 結構。例如，如果源中的 *ElementA* 對映到目標中的 *ElementB*，則輸入檔案中每次出現 *ElementA* 都會導致輸出檔案中產生一個 *ElementB* 例項（及其所有子元素）。
在本例中（如 [扁平化採購訂單](#扁平化採購訂單) 一節所述），源 850 中的每個行專案都應在目標 CSV 中生成一條新記錄。要建立此關係，請將代表行專案的 **源** 元素拖動到代表 CSV 記錄的 **目標** 元素上。在本例中，源元素是 *TX-00401-850*，目標元素是 *customers*：
如上圖所示，*customers* 目標元素顯示了對映到它的源 xpath。每當 XML 剖析器在輸入檔案中找到與該 xpath 匹配的元素時，就會向輸出檔案中新增一個新的 *customers* 元素（包括 *customers* 元素的所有子元素，如果有）。
此 Foreach 迴圈是此對映所需的唯一迴圈。其他對映專案可能需要多個迴圈，包括巢狀迴圈或其他形式。
### 對映葉節點
建立 Foreach 關係後，可以對映迴圈中葉節點的值。對映葉節點決定了填充由 Foreach 迴圈建立的 XML 結構的值。
#### 簡單葉節點對映
當源中的值應直接插入生成的輸出時，只需將葉節點從源拖動到目標中的葉節點即可對映這些值。例如，*BEG03* 元素儲存了 *PONumber* 的值，它對應於目標中的 *PONumber* 屬性：
這些元素的 xpath 是相對於 Foreach xpath 的。
#### 使用 Lookahead 語法的條件對映
850 文件包含多個 *N1Loop1* 元素，代表交換中的參與方及其角色（例如，收貨方或付款方）。對於每個 *N1Loop1*，*N1Loop1/N1/N104* 元素儲存標識該參與方的值（參與方名稱或 ID），因此必須將這些值對映到輸出 CSV。然而，無論參與方的角色如何，每個 *N104* 元素的 xpath 都是相同的，因此僅靠指向 *N104* 元素的 xpath 不足以對映正確的值。
參與方的角色儲存在 *N1Loop1/N1/N101* 中，因此對映需要在將 *N104* 元素值對映到輸出 CSV 之前檢視 *N101* 元素。換句話說，*BillToPartyCode* 需要對映到：
`N1Loop1/N1/N104 WHERE N1Loop1/N1/N101 = 'BT'`
這種條件對映可以使用 `Lookahead` 語法完成。
首先，將包含源值的元素拖動到目標元素 (*BillToPartyCode*) 上：
然後，將滑鼠懸停在已對映的 *BillToPartyCode* 元素上，點選平板和鉛筆圖示以開啟 **節點值** 編輯器：
請注意，當前對映的 xpath 是 *N1Loop1/N1/N104*，要檢視的 xpath 是 *N1Loop1/N1/N101*。Lookahead 語法的指定如下：
* 在當前 xpath 中找到作為要檢視元素的最近父元素的元素（在本例中為 *N1* 元素）
* 在方括號 `[ ]` 中指定要檢視元素的 xpath（在本例中為 `[N101]`）
* 新增一個等號運算式 `=` 以指示要檢查此元素的值（在本例中為 `BT`）
* 用反斜槓轉義方括號，使其不被作為 xpath 運算式的一部分進行評估
生成的 Lookahead 運算式如下所示：
對其餘目標元素重複相同的過程。
#### 使用節點值編輯器進行修改和計算
除了 xpath 操作外，節點值編輯器還支援在對映期間修改或操作值的 [格式化器](../scripting/value-formatters/formatters)。*ItemTotalCost* 元素需要對映為行專案的總成本，這在源元素中無法直接獲得，但可以透過將專案數量乘以專案價格輕鬆計算得出。
作為起點，將專案價格對映到 *ItemTotalCost* 元素並開啟節點值編輯器。
可以使用 *multiply* 格式化器將此起始值（單價）與專案數量相乘。格式化器語法的運作方式如下：
* 序列包含在方括號中（如當前 *ItemTotalCost* 運算式中所示）
* 序列從左到右進行評估
* 序列由豎線字元分隔（例如，`[value | formatter1() | formatter2() | formatter3()]`）
將源節點拖動到目標節點時生成的 *xpath()* 語法本身就是一種特殊的格式化器。
在 xpath 運算式右端（閉方括號內）新增一個豎線分隔符號，為格式化器建立一個新空間。在此空間中，手動輸入 *multiply()* 格式化器，或導航到節點值編輯器中的 **格式化器** 頁面，搜尋 'multiply'，然後點選相應的格式化器將其新增到運算式中。為了將起始值（專案價格）與專案數量相乘，需要將專案數量值指定為 *multiply* 格式化器的參數。由於此值需要從輸入的 850 中取得，因此需要另一個 *xpath* 運算式，其 xpath 對應於專案數量 (*PO1/PO2*)：
生成的運算式透過將單價乘以專案數量，正確計算出行專案的總成本。
儲存運算式後，對映即告完成。儲存對 XML Map 端口的更改，即已配置好完整的工作流程。
## 範例檔案
本指南使用以下範例資料。
### X12 850
```text theme={null}
ISA*00* *00* *ZZ*AMAZONDS *01*003025392 *160623*1448*U*00401*000000013*0*P*+~
GS*PO*AMAZONDS*ATFDS*20070911*2001*95*X*004010~
ST*850*0003~
BEG*00*DS*TesT0008516**20070805~
CUR*BT*USD~
N1*BT*Amazon.com.kydc,Inc.*92*KYDC~
N1*SF*WHSE*92*WHSE~
N1*ST*Charlie Dinkins~
N3*11254 Main St*Suite 112~
N4*Seattle*WA*98104*US*CC*United States~
TD5**92*UPS_GR_RES****ZZ*RES~
N1*LW*Amber Baker~
N3*123 Anderson Avenue~
N4*Seattle*WA*98103*US~
PO1*1*3*EA*18.04*NT*SK*1617*****BL*1*ZZ*Amazon.com~
PO1*2*2*EA*54.42*NT*SK*4927*****BL*1*ZZ*Amazon.com~
PO1*3*1*EA*18*NT*SK*9876*****BL*1*ZZ*Amazon.com~
CTT*3*6~
SE*15*0003~
GE*1*40~
IEA*1*000000040~
```
### CSV
```csv theme={null}
CustomerId,PONumber,PODate,BillToPartyCode,ShipFromCode,ShipToAddress,ShipToCity,ShipToZIP,LineItemNumber,ItemID,ItemQuantity,ItemPrice,ItemTotalCost
Sir Charles,128F195,20190805,AbRes,W22,2408 Creek St,Springfield,52213,1,BouncyRubberBall,4,2.49,9.96
Lady Jane,128F196,20190805,AbRes,W22,2408 Creek St,Springfield,52213,2,SquishyNerfBall,2,4.29,8.58
```