整合疑難排解指南
概述
整合系統由多個自動化的運作元件組成。當遇到無法立即看見的問題時，排解故障可能會讓人感到困難，但只要一步一步地進行，通常都能找到並解決問題。
這份故障排解指南可以幫助你了解整合系統的運作元件與整合循環，並從整體角度學會如何排查問題。雖然整合有很多不同類型，每種都有其細節，但它們的運作流程和核心元件其實大同小異。
適用對象
BarTender 2019 及以後版本
整合流程的組成元件
整合流程中有多個運作元件協同合作，來自動化你的列印工作。以下簡單介紹每個元件及其在流程中的作用。
服務
- BarTender Integration Service：這個服務負責執行整合本身，啟動與停止整合，並處理觸發偵測與資料處理。
- BarTender Print Scheduler Service：這個服務負責處理標籤檔案，準備好後送到印表機佇列。
- BarTender System Service：這個服務負責記錄日誌，並在各服務與系統資料庫之間進行溝通。
列印引擎
列印引擎其實就是以服務方式運作的 BarTender Designer。你會在執行中的程序清單看到 bartend.exe。列印引擎會由 Print Scheduler 服務自動啟動與關閉，並負責實際的標籤列印。預設情況下，列印引擎有以下特性：
- Print Scheduler 服務會根據需求啟動它們。如果整合負載增加，會自動開啟更多引擎。
- 它會維持列印順序（確保序號與紀錄不會在標籤紙上亂序）。
- 同時最多可處理 5 份文件，若閒置則會自動關閉。
- 如果 60 分鐘內未被使用，Print Scheduler 服務會自動關閉它們。
列印引擎是全自動的。你不需要手動開啟或關閉，Print Scheduler 服務會自動處理。你最多可以同時啟動的列印引擎數量為 CPU 核心數 x2。
整合循環
整合本質上是循環運作的。它們會啟動並等待某個事件來觸發運作。這個觸發事件可能是一個檔案、資料庫中的紀錄、一封電子郵件、網路上的訊息、定時觸發等。一旦偵測到觸發事件，整合就會開始處理資料並送出列印。紫色 Print Scheduler 方框以外的部分，都是由 Integration Service 處理。
一般來說，當工作送到佇列並且 Print Scheduler 向 Integration Service 確認已完成後，整合就會回到等待狀態。
整合可能因以下幾個原因進入停止狀態：
- 這是一次性、非重複的定時整合。
- 整合在 Integration Builder、管理主控台中被手動停止，或服務關閉。
- 整合系統發生錯誤且無法自動復原。
由於整合系統有許多運作元件，排解故障時請記得幾件事：
- 務必更新到最新的服務版本。這樣可以避免遇到已經修正的錯誤。
- 依照整合循環的每個步驟順序進行排查。這樣可以確保你不是在修復前一個步驟就已經出錯的問題。
- 如果需要協助或遇到本指南未涵蓋的情況，請聯絡技術支援！
在進行這些操作時，你需要存取整合檔案（.btin）、標籤檔案（.btw）、任何資料庫檔案、觸發資料（如果不是定時整合），以及 Integration Builder。
故障排解
權限問題是整合流程中常見的問題，尤其是在使用網路資源時。你可以點擊整合標題，並在「使用者帳戶」區塊輸入資訊，將整合權限提升到網域帳戶。
請在這裡設定權限，除非技術支援人員有特別指示，否則不要直接在 Integration Service 上設定帳戶。同樣地，你也可以在 BarTender System Service 上設定帳戶，Integration Service 會自動繼承這些權限。
帳戶必須具備以下條件，才能正確執行整合：
- 必須是本機管理員群組成員（這對於訊息傳遞、存取暫存檔案、無障礙存取檔案結構以取得標籤等是必要的）
- 必須有網域層級的存取權（才能存取網路印表機或磁碟機）
- 群組原則必須允許本機登入（沒有這個權限無法執行服務或任務）
- 密碼不會變更（避免因密碼政策導致整合中斷）
要排查整合流程，請點擊每個步驟展開詳細內容，逐步檢查以協助找出問題：
啟動整合
等待觸發
當整合啟動後，就會進入等待觸發的階段。這看似不需要排查，但如果你一直卡在等待狀態怎麼辦？如果觸發事件始終沒來怎麼辦？如果你遇到「什麼都沒發生」的情況，排查這個步驟可能會幫你找出原因。
所有整合類型都會等待某個事件發生或出現。可能是一個檔案、網路埠上的資料、資料表中的紀錄，或是特定時間。所有觸發偵測的設定都和前一個步驟一樣，位於 Integration 標頭下的第一個子區段。
以下是常見整合類型可以檢查的幾個重點：
檔案整合
- 觸發檔案是否有放在整合設定的掃描資料夾？
- 觸發檔案是否符合預期的檔案格式？例如整合在找 .csv，但你放的是 .css，格式就不符。
- 是否有其他整合先搶走了檔案？
資料庫整合
- 資料是否有插入正確的資料表？
- 資料偵測方式是否正確？如果整合在監控遞增值，但你卻只更新日期時間，偵測方式就不符。
- 被監控的欄位是否有遞增，或日期時間是否有更新？
Socket 與 Web Service 整合
- 資料是否送到正確的位址？
- 防火牆是否擋住了連接埠？
重點整理
- 確保觸發事件有送到正確的位置。
- 再次確認沒有東西在偵測前就攔截或搶走觸發事件。
偵測後動作
和前一個步驟類似，這個步驟看起來應該會自動運作。但有時候會直接出現錯誤，有時則要等到整合循環重複時才會發現問題。
這個步驟指的是整合收到資料後要做的事。只有兩種整合類型會用到偵測後動作，其他類型可以跳過這一步。以下是常見有偵測後動作的整合類型需要注意的地方：
檔案整合
在所有整合類型中，這一步檔案整合最容易出現問題。如果偵測後動作出錯，整合會直接顯示錯誤訊息，告訴你哪裡有問題。常見問題包括沒有權限更改檔案或資料夾，以及檔案路徑設定錯誤。
檔案整合的偵測後動作設定如下：
Socket 整合
在這個步驟，Socket 整合的問題不像檔案整合那麼明顯。如果你的 Socket 整合流量不大，可能不會有問題，但如果流量很大，偶爾會出現這個錯誤：「Error: Cannot access disposed object.」
這種情況是因為 Socket 在收到資料後沒有關閉，導致新資料不斷湧入。整合還沒準備好處理新資料，就會把它當成垃圾資料直接丟棄，造成資料遺失、列印漏掉。
如果你發現這種情況，可以參考這篇文章來解決：執行 Socket 整合時發生錯誤。
重點整理
- 這個步驟只適用於兩種特定整合。
- 這一步的錯誤不一定很明顯。
處理整合動作
整合動作是指您的整合在處理和列印標籤時所執行的所有步驟。所有動作都會列在動作標題下方：
這個範例相當簡單，僅包含一個列印動作。不過，有些整合可能會包含多個步驟，例如迴圈、資料解析、輸出訊息或電子郵件，或是條件判斷。以下是一個較大的範例，資料會透過一連串命名的搜尋與刪除動作從觸發器中解析出來，然後再用於「列印文件」動作：
這會增加這個步驟的複雜度，也增加了出錯的可能性。最好的做法是先從簡單開始。將動作精簡到最低限度，盡量減少步驟（通常只保留從「新增」選單建立新整合時會用到的動作，以及處理資料所需的最基本步驟），然後再從這裡開始。
- 移除多餘的步驟。先保留最基本的部分。
- 逐步加入每個步驟並測試，確保問題不是出在某個特定動作。
這個步驟最大的挑戰在於測試。如果問題出現在整合流程的後面步驟，那麼在測試所有步驟時問題都會持續存在。即使如此，仔細檢查這個步驟的所有細節仍然非常重要。以下是整合中最基本步驟常見的問題：
文件位置
要列印標籤，整合當然必須能夠開啟文件。如果文件位置或名稱無效，整合很可能會出現文件錯誤，提示開啟文件時發生問題。您可以在以下位置找到文件名稱：
- 列印文件動作：在「文件」標籤的「文件」區段。如果文件是由變數決定，請追蹤該變數的來源（通常來自資料庫欄位名稱、設定變數動作，或是某個搜尋動作），並確保該變數中的資料正確無誤。
- 列印指令腳本動作：在觸發資料的 /AF 參數中
- 列印 BTXML 動作：在觸發資料的 <Format> 標籤中
如果在「列印文件」動作中沒有指定文件，當您嘗試啟動整合時，會立即出現錯誤訊息，提示缺少文件。
印表機名稱
就像沒有文件就無法列印一樣，沒有有效的印表機也無法列印。大多數情況下，整合會出現錯誤，通常是無效印表機錯誤或 Windows 錯誤代碼 1801（Windows 無法使用這台印表機）。後者屬於 Windows 系統問題，超出本疑難排解範圍。前者可以在以下位置找到：
- 列印文件動作：在「列印選項」標籤的「印表機」欄位
- 列印指令腳本動作：在觸發資料的 /P 參數中
- 列印 BTXML 動作：在觸發資料的 <Printer> 標籤中
如果沒有指定印表機，整合會使用標籤檔案中儲存的印表機。如果您的整合沒有指定印表機，請在 BarTender Designer 中開啟標籤，然後前往 檔案 > 列印。這就是您的整合正在使用的印表機。
有時候，標籤會被送到意料之外的印表機，或是直接消失不見。這通常是因為印表機重新導向系統啟動，將列印工作送到第一台可用的印表機。如果您遇到這種奇怪的情況，請參考這篇文章來解決問題：整合列印被送到錯誤或隨機的印表機。
資料庫類型或欄位名稱不符
如果您的整合使用資料庫並從整合接收資料，您必須確保資料庫類型相符。舉例來說，如果您的標籤連接到逗號分隔值（CSV）資料庫，但整合傳送的是以 Tab 分隔的資料，或是完全不同格式（如 XML 資料），就會造成資料庫類型不符，文件無法理解傳送過來的資料。這可能會導致各種整合錯誤，內容可能提到資料庫、欄位或資料為空的問題。
此外，即使資料庫類型相符，如果欄位名稱不同或順序不同，也可能導致類似的整合錯誤。
要再次確認資料庫是否正確對應，您可以這樣做：
- 在 BarTender Designer 中開啟標籤檔案。前往 檔案 > 資料庫連線設定。在這個對話框中，您可以檢查欄位名稱以及標籤所連接的資料庫類型。
- 此外，您也可以在這個設定對話框中找到連接的資料庫名稱，並在電腦上開啟它，確認格式（例如 CSV 與 Tab 分隔）及欄位名稱。
- 將連接的資料庫與觸發器中包含的資料進行比對。
如果您的標籤資料庫不是純文字檔（或在 BarTender 2019 R5 及之後版本為 Excel 檔），整合一定會因資料庫不符而失敗。如果您的標籤連接到不支援的資料庫，您必須將連線改為支援的資料庫，並重新設定標籤上的物件以對應新的欄位。
標籤只有預設資料
這種情況發生是因為整合在列印時沒有將資料傳遞給標籤。最常見的原因是整合沒有設定要這麼做（預設行為），而且只會發生在「列印文件」動作。以下是兩種常見情境及其解決方法：
- 傳遞資料庫資訊：整合必須設定為覆寫資料。這個設定在「列印文件」動作的「列印選項」標籤下的「資料庫覆寫」區段。您必須用 整合資料 或 EventData 覆寫資料庫，才能將觸發資料傳遞給標籤。
- 未定義命名資料來源：整合必須設定如何將變數與標籤上的命名資料來源配對。如果您發現「命名資料來源」標籤下缺少同名的命名資料來源，請點選「文件」標籤上的「匯入文件設定」按鈕，然後將匯入的命名資料來源與整合變數配對。
重點整理
- 為了更有效地排除這個步驟的問題，先將動作數量減到最少，再逐步加入，觀察問題出現在哪個步驟。
- 資料問題在這個步驟很常見，這裡修正可以避免後續步驟出現問題。
建立列印 BTXML
整合流程中的列印部分依賴一種格式化的 XML，稱為 BTXML。它包含文件和印表機資訊，以及您設定要傳遞給標籤的觸發檔案資料。
雖然您可以自行建立 BTXML，並透過「列印 BTXML」動作傳送到整合，但其實不需要這麼做！整合會自動將您在列印動作中的資料和設定轉換成 BTXML。
如果您已經完成前面步驟的所有疑難排解，BTXML 會順利轉換，您可以進行下一步。
自動化列印
整合流程的最後一步（在流程重複前）就是實際的列印。這一切都由「列印排程器」服務自動處理，流程也很簡單。以下是本文開頭流程圖的片段：
當 BTXML 腳本從上一個步驟傳送到「列印排程器」後，這個步驟就會立即開始。服務會負責開啟「列印引擎」，然後判斷要開啟哪個標籤檔案（如果該檔案尚未在引擎中開啟）。文件開啟後，若有來自整合的資料，會透過資料庫覆寫或命名資料來源，將資料放到標籤的正確位置。資料處理完成後，標籤會送到 BTXML 指定的印表機，或是標籤上預設的印表機（如果未指定）。
這一切都在服務中自動完成，那如果出現問題該怎麼辦？又該如何排除？由於您已經在前面步驟做了大部分工作，這一步的疑難排解其實比想像中簡單。
如本指南開頭所述，「列印排程器」服務所用的「列印引擎」其實就是以服務模式執行的 BarTender Designer。這表示您可以直接用 Designer 來排除這個步驟的問題。
基本疑難排解
在列印時，「列印引擎」會根據 BTXML 腳本的指示自動列印標籤檔案。如果您要模擬這個腳本，只需開啟標籤，前往 檔案 > 列印，更改印表機名稱，然後列印文件。雖然 BTXML 腳本還能做一些額外的事，但這個簡單的動作就能讓我們了解「隱形」列印引擎正在發生什麼事。
開啟與列印文件
「列印引擎」最基本的行為就是開啟並列印文件。雖然前面的步驟已經檢查過文件是否在正確的位置，但實際開啟文件可以確認「列印引擎」在列印時能否正確使用該文件。
- 嘗試開啟文件。能順利開啟嗎？還是有錯誤或訊息跳出？
- 如果嘗試列印文件，能順利列印嗎？還是有錯誤或警告訊息跳出？
如果其中任何一個動作出現對話框，顯示警告或錯誤，這些都可能會干擾自動列印流程。下一節會說明如何處理這些對話框。
錯誤與警告對話框
雖然「列印引擎」可以略過大多數對話框，但有些對話框會導致列印被跳過或出錯。有時候，「列印引擎」不會正確將這些訊息記錄到整合日誌中，因此在這裡檢查和觀察任何對話框，有助於找出問題。
以下是一些可能被略過，但仍可能造成整合問題的對話框範例：
- 頁面調整對話框：當印表機的紙張尺寸略有不同時，BarTender 會自動調整標籤。如果標籤看起來怪怪的，可能是紙張不同。請調整標籤並用整合用的印表機儲存，以避免這個對話框跳出。
- 裁切警告：在 BarTender 2019 早期版本，這個警告會直接導致列印失敗。如果列印卡在這裡，請更新您的軟體。
- TrueType 字型替代訊息：這個訊息可以在列印對話框中關閉。這個訊息無法被略過，建議將其關閉。
以下是一些可能導致列印停止並出錯的對話框，這些也可能出現在整合訊息中：
- 頁面尺寸錯誤對話框：如果範本設定為固定尺寸，或尺寸超過印表機規格，整合會自動調整文件時，可能會出現這個訊息。請前往 檔案 > 頁面設定 開啟頁面對話框，檢查「頁面」標籤的詳細設定，也要檢查「版面配置」標籤是否有太多欄或列。
- 資料庫連線錯誤：如果資料庫檔案被移動或無法存取，會出現這種錯誤。請用 檔案 > 資料庫連線設定 重新建立連線，然後儲存文件。
- 範本未參考資料庫欄位：請參考 錯誤 3600：範本未參考任何資料庫欄位。
- 缺少圖片或連結物件：如果連結的圖片或物件被移動，或位於無法存取的網路位置，會出現這個錯誤。BarTender 會等到物件或圖片重新連結後才會列印。
- 提到 TMP 的錯誤：標籤或連結資源可能已損毀。建議還原標籤備份或重新製作。
這不是完整清單，但已涵蓋您在疑難排解時最常遇到的問題。
重點整理
- 這個自動化步驟可以用 BarTender Designer 來檢查。
- 對話框通常能告訴您問題所在。
其他疑難排解
有時候，問題無法直接在整合流程中找到。以下是一些額外的資源，或許能幫助你解決上面文章未提及的其他情況。
一般問題
整合突然停止
整合可能因多種原因而停止，其中一些原因已在上文說明。最常見但未提及的原因是資源突然無法存取。這種情況在資料庫整合和使用雲端儲存位置的檔案整合中最常見。BarTender 2021 會在資源恢復可用時嘗試重新啟動整合，但舊版則會直接停止整合。
如果你的整合突然停止，請檢查日誌中的最新錯誤，以找出原因。
檔案整合
整合執行速度緩慢
影響檔案整合速度的因素有很多，但這類整合有其獨特的影響因素。掃描資料夾的大小很重要。由於檔案整合會掃描資料夾以尋找新檔案，如果檔案數量越來越多，掃描所需的時間也會越來越長。
如果你的整合沒有設定在處理完觸發檔案後刪除或移動這些檔案，這些觸發檔案會隨時間累積。如果你發現整合速度變慢，請嘗試從掃描資料夾中移除已處理的觸發檔案，看看是否能提升速度。
資料庫整合
重複紀錄或多次列印
如果資料庫整合正在掃描某個資料表，而標籤同時也連接到這個資料表，你很可能會遇到重複列印標籤的情況。請參考以下文章，了解如何解決這個問題，以及如何正確設定資料庫整合與標籤：
整合撈取紀錄速度緩慢
整合執行緩慢可能有很多原因，但資料庫整合有其特殊情況。資料庫整合會掃描整個資料表，以檢查是否有符合觸發條件的新紀錄。如果資料表越來越大，這個過程會隨著資料增加而變慢，每次查詢都會對資料庫伺服器造成負擔。
建議定期清理資料庫中未使用的紀錄，或設定整合在處理後自動刪除紀錄，以減輕資料庫和整合的負擔。
Socket 整合
無法存取已釋放物件錯誤
如果你發現整合跳過了某些標籤，可能會在日誌中看到「無法存取已釋放物件」的錯誤。這表示 socket 在作業之間沒有正確關閉。要解決這個問題，請參考 執行 Socket 整合時發生錯誤：無法存取已釋放物件。
還需要協助嗎？聯絡我們！
雖然按下啟動按鈕或讓整合自動啟動看起來沒什麼好排查的，但這其實是整合循環的第一步。這個步驟會讓整合開始偵測觸發事件。如果出現問題，或觸發來源已經不存在，整合就會一直等待，甚至可能發生錯誤。
每種整合類型在整合檔案中對這些資訊的稱呼都不同，必須正確設定才能運作。對所有整合類型來說，相關設定都會在 Integration 區塊的第一個子區段，並說明它正在偵測什麼。在這張截圖中，這是檔案整合，所以子區段名稱是「File Detection」，代表它正在尋找檔案來觸發整合。
這個步驟常見的問題通常與權限、檔案名稱和觸發設定有關。如果你在 Integration Builder 啟動整合時，出現錯誤訊息，通常會直接告訴你是哪裡出問題。
以下是各種常見整合類型在這個步驟可能遇到的狀況：
檔案整合
對於檔案整合來說，權限和檔案位置非常重要。
如果整合無法存取資料夾，通常會出現權限錯誤或存取錯誤。建議掃描資料夾不要使用虛擬磁碟代號（即非實體磁碟），也不要放在「我的文件」或桌面上。
同時建議掃描資料夾最好設在 Windows 系統上。如果你打算用 Unix、Linux 或其他作業系統來放掃描目錄，建議改用像 FTP 這類雲端位置。
如果是網路資料夾，請提升整合的權限，確保有正確的存取權。
資料庫整合
能否存取資料庫是關鍵。請確認以下事項：
這些設定都在連線設定對話框中。就像在標籤上排查資料庫連線一樣，點選「資料庫連線設定...」按鈕可以檢查資料庫是否連線正常。如果有問題，對話框會顯示錯誤訊息。
Socket 整合
網路連線非常重要。如果無法建立連線，可以先檢查連線本身。
整合需要一個「安靜」的連接埠。如果有其他程式在該埠傳輸資料，整合通常會出現錯誤，提示該埠無法使用。和其他整合一樣，錯誤訊息通常會告訴你問題所在及解決方法。
重點整理
雖然這個步驟在不同整合類型上會有差異，但有幾個共通重點：