UOFX Connector 技術手冊

概要

UOFX Connector 是用來連接 UOFX 伺服器並取得某種特定資料使用，系統內有各種不同的運行資料，隨著使用更高版本的 UOFX，可以讀取更多支援的資料內容。

對於組織而言，無須開發商的支援，就可以使用基礎的資料，在 PowerBI Desktop 上面執行各種資料運算、統計、報表製作等等靈活的運用。

此份文件旨在說明 UOFX Connector 與 UOFX 伺服器 Public API 之間的通訊內容定義，文件內容隨時會因為 UOFX 版本升級而擴充。

參數與查詢

UOFX Connector 所需要的參數有好幾個，只有 SiteUrl 為必填欄位，這是指向 UOFX 站台的資料提供 API 的網址，還有 CompanyCode 大部分的情況為必填，這是公司代碼，也跟連接器的串接金鑰有關。

所有欄位列舉如下:

• SiteUrl :
  UOFX 站台的 api 站台網址，需先確認 UOFX 站台可以正常登入使用
• CompanyCode :
  用來區分不同分公司的代號，輸入不同的公司代號，則能取用不同公司的資料，當然你也必須擁有那間公司的管理權限
• ModuleCode :
  模組代碼，用來告訴 API 目前將取用的模組
• FeatureType :
  功能代碼，用來告訴 API 目前將取用的功能，通常與 ModuleCode 匹配為一組，不同的組別代表執行不同的查詢功能，返回不同的資料集
• DataKey :
  資料識別碼，用來告訴 API 資料集的某種特徵，通常用於資料過濾
• DataKey2 :
  資料識別碼2，用來告訴 API 資料集的其他特徵，通常用於資料的二次篩選之用
• Status :
  狀態碼，較常使用於資料狀態篩選
• StartTime :
  開始時間，當資料集有時間特性，有些查詢可以使用此欄位標示資料的開始時間，做為資料篩選
• EndTime :
  結束時間，當資料集有時間特性，某些查詢使用此欄位標示資料的結束時間，做為資料篩選之用

當我們需要取得某種查詢的資料，必須仔細選取不同的 ModuleCode 與 FeatureType 組合，藉此定位合適的查詢功能,目前支援的查詢功能與參數搭配如下 :

組織查詢

輸入欄位說明

• ModuleCode :
  • 請輸入 org
• FeatureType :
  • 查詢部門資料，請輸入department
  • 查詢人員資料，請輸入employee
  • 查詢部門與人員資料全部資料，無須輸入值
• DataKey :
  • 若FeatureType 沒有輸入值，即表示查詢部門與人員資料，無須輸入值
  • 若FeatureType = department，請輸入你所要取得部門的 [部門代號]
  • 若FeatureType = employee，請輸入你所要取得人員的 [帳號]
• DataKey2 :
  • 未使用，無須輸入值
• Status : 帳號狀態
  • 若FeatureType 沒有輸入值，即表示查詢所有人員資料，無須輸入值
  • 若FeatureType = department，查詢 啟用 部門，請輸入 1；查詢 停用 部門請輸入 0
  • 若FeatureType = employee，查詢 啟用 帳號，請輸入 1；查詢 停用 帳號請輸入 0
• StartTime : 建檔日期
  • 不過濾建檔日期，無須輸入值
  • 取得申請時間在 [StartTime] 之後(含)的表單資料，請輸入[StartTime]
• EndTime :
  • 不過濾申請時間，無須輸入值
  • 取得申請時間在 [EndTime] 之前(含)的表單資料，請輸入[EndTime]

查詢功能	ModuleCode	FeatureType	DataKey	DataKey2	Status	StartTime	EndTime	查詢結果
查詢所有部門與員工資訊	org	[EMPTY]	[EMPTY]	[EMPTY]	[EMPTY]	[EMPTY]	[EMPTY]	department，employee
查詢部門資訊	org	[EMPTY] department	[EMPTY] [departmentCode]	[EMPTY]	[EMPTY] 0 => Disabled 1 => Enabled	[EMPTY] [StartTime]	[EMPTY] [EndTime]	department
查詢員工資訊	org	[EMPTY] employee	[EMPTY] [employeeCode]	[EMPTY]	[EMPTY] 0 => Disabled 1 => Enabled	[EMPTY] [StartTime]	[EMPTY] [EndTime]	employee

Note
上述資料，標示為 [EMPTY] 代表為空字串，意義為不過濾欄位內容的意思

Note
[StartTime] 與 [EndTime] 為 DateTime 的形式，其格式為 yyyy/MM/dd HH:mm:ss (Ex: 2024/10/15 15:30:52)

---

Department Table Schema

• Parent Code :
  上層部門代碼
• Department Code :
  部門代號，此欄位為單一分公司內的唯一值
• Department Name :
  部門名稱
• Department Status :
  部門的啟用狀態，1 代表啟用，0 代表已停用
• Remark :
  備註

【 Department Table Example 】

Parent Code	Department Code	Department Name	Department Status	Remark
	PRES	President	1	總經理室
PRES	ADMIN	Administration	1	行政部
PRES	SECPOOL	Secretarial Pool	1	秘書室
PRES	HR	HR Department	1	人力資源部

【 Structure diagram 】

President (PRES)
├── Administration (ADMIN)
├── Secretarial Pool (SECPOOL)
└── HR Department (HR)

Employee Table Schema

• Account :
  帳號
• Name :
  員工名稱
• Department Code :
  所隸屬的部門代碼
• Status :
  員工資料的啟用狀態，1 代表啟用，0 代表停用

【 Employee Table Example 】

Account	Name	Department Code	Status
Johnny	Johnny	HR	1
Amy	Amy	HR	1
Kevin	Kevin	ADMIN	1
Sophia	Sophia	ADMIN	1
Candy	Candy	SECPOOL	1
Robert	Robert	PRES	1

【 Structure diagram 】

President (PRES)
└── Robert

Administration (ADMIN)
├── Kevin
└── Sophia

Secretarial Pool (SECPOOL)
└── Candy

HR Department (HR)
├── Johnny
└── Amy

表單查詢

輸入欄位說明

• ModuleCode :
  • 請輸入 bpm
• FeatureType :
  • [Empty] 未使用
• DataKey :
  • [Empty] 未使用
• DataKey2 :
  • [EMPTY] 未使用
• Status :表單狀態
  • 查詢 簽核中 的表單，請輸入 簽核中 or Processing
  • 查詢 已結案 的表單，請輸入 已結案 or Completed
  • 查詢簽核結果為 同意 的表單，請輸入同意 or Approve
  • 查詢簽核結果為 否決 的表單，請輸入 否決 or Reject
  • 查詢簽核結果為 作廢 的表單，請輸入 作廢 or Cancel
  • 查詢流程 異常 的表單，請輸入 異常 or Exception
  • 查詢所有狀態的表單，無須輸入值
• StartTime :
  • 不過濾申請時間，無須輸入值
  • 取得申請時間在 [StartTime] 之後(含)的表單資料，請將[StartTime] 以日期格式寫入 yyyy/MM/dd HH:mm:ss (Ex: 2024/10/15 15:30:52)
• EndTime :
  • 不過濾申請時間，無須輸入值
  • 取得申請時間在 [EndTime] 之前(含)的表單資料，請輸入[EndTime] 以日期格式寫入 yyyy/MM/dd HH:mm:ss (Ex: 2024/10/31 15:30:52)

Query Result Table Schema

• 表單編號 :
  • 表單的編號，每一張表單流程啟動的唯一編號，每張表單一定會有這個欄位
• _Ver :
  • 表單版本，不同的表單都可以擁有不同的版本，表單內容是依附在不同的表單版本之下。
• _Applicant :
  • 申請者，申請表單人員的在系統中設定的名稱
• _ApplicationDate :
  • 申請時間，申請表單的時間
• _State :
  表單狀態，根據流程進行的程度，表單狀態會有所不同，其列舉如下 :
  • 簽核中 => 表單流程還在進行中，尚未結案
  • 同意 => 表單流程已結束，簽核結果為同意
  • 否決 => 表單流程已結束，簽核結果為否決
  • 作廢 => 表單流程已結束，簽核結果為作廢
  • 異常 => 表單發生異常，需要管理者介入處理
• 其他表單欄位...
  • 除了表單編號的其他欄位，會排列在以上的欄位後面顯示出來

Note
工作流程(BPM) 的查詢功能會將表單轉成資料表的形式，如果有一張表單如下 :

使用 UOFX 連接器將會得到以下的兩個資料表 :

BusinessTrip:

表單編號	_Ver	_Applicant	_ApplicationDate	_State	OccurrenceDate	Objective	Remark	Spent
2502000007	1	User1	2025/½ 10:21	同意	2025/½	參加AI教育訓練

BusinessTrip_Spent:

表單編號	_Ver	_Applicant	_ApplicationDate	_State	SpentItem	Cost	Description
2502000007	1	User1	2025/½ 10:21	同意	搭高鐵	1200	高雄到台北
2502000007	1	User1	2025/½ 10:21	同意	計程車	250	台北車站到會場
2502000007	1	User1	2025/½ 10:21	同意	捷運	100	會場到車站
2502000007	1	User1	2025/½ 10:21	同意	搭高鐵	1200	台北到高雄

Note
當表單有明細欄位時，我們將會得到一個額外的資料表，其名稱為 [表單名稱]_[明細欄位] ，其內容只包含明細欄位的內容，以這個例子來說，明細欄位的資料表名稱就是 BusinessTrip + _Spent

注意事項

• 連接器查詢表單的時候會將結果轉成資料表，系統只會取出第一個同名表單，所以在設計表單的時候，盡量排除同名的情況， 對於同一張表單的欄位，也不允許同名的情況，其他的同名欄位將被忽略。
• 連接器查詢表單時，系統會在資料表中額外產生這些欄位 : _Ver，_Applicant，_ApplicationDate，_State ，這些不存在於表單的欄位， 是從流程本身的屬性所擷取出來，讓使用者可以識別每一個流程之用，因為欄位名稱不能重複，所以設計表單時必須排除這些名稱。
• 連接器所查詢到的資料表規格，是最新已公開版本的表單內容，其他較舊的表單版本內容只要欄位名稱相同，也會被擷取出來。

流程績效查詢

• 當輸入參數 ModuleCode 為 FLOW 時，系統提供 BPM 表單流程的效能統計相關結果，公司在導入 BPM 一定時間之後，原先的紙本簽核模式轉變成線上的方式，使用上方便了，效率也會更加提升，當然也更加環保。對於管理階層來說，不會僅僅滿足於環保與電子化的成本降低，實際上的簽核效率將是更重要的議題。每張表單的使用率為何 ? 是否有人經常延遲簽核 ? 表單的流程設計上是否有缺陷，造成流程瓶頸 ? 使用率的趨勢我們是否可以統計出來 ? 針對這些相關效能議題，系統提供了一些統計資料表，讓我們可以輕易做到不同維度檢視，進而增進企業流程效率。

輸入欄位說明

• ModuleCode :
  • 請輸入 flow
• FeatureType :
  • [Empty] 未使用
• DataKey :
  • 只跟第三張報表的內容有關，這個欄位值用來查詢第三張報表的單據名稱，如果單據名稱包含 DataKey 內容，則只取出第一張表單來運算。其他應用保持空值即可。 (Ex: 請假單)
• DataKey2 :
  • [EMPTY] 未使用
• Status :
  • [EMPTY] 未使用
• StartTime :
  • 統計時間的基準月份，若為空白則代表使用目前時間的月份，輸入時使用日期格式如: 2025/10/1，無論指定哪一天，系統只取年月部分。
• EndTime :
  • 未使用

這個查詢我們可以一次得到製作三張報表的資料表。我們將依序解說這些報表的內容與組成方式。

第一張報表 - 單據類型績效表

這張報表需要 R1_Task，R1_Category，R1_Form 三個資料表的內容，如果有充足的資料可供分析，理論上我們將可以製作類似下圖的報表:

返回資料表: R1_Task

流程報表1 - 使用狀況當月統計，主要是用來計算當月總使用次數，與當月平均花費時間

• CategoryId (String)
• 表單分類代碼
• CategoryName (String)
• 表單的分類名稱
• FormId (String)
• 表單代碼
• FormName (String)
• 表單名稱
• FormSN (String)
• 表單序號
• TaskId (String)
• 流程代碼
• ApplicantName (String)
• 申請人名稱
• ApplicantDeptName (String)
• 申請人部門名稱
• TaskCreatedDate (DateTime)
• 流程開始時間
• TaskEndDate (DateTime)
• 流程結束時間
• TaskSpent (Double)
• 流程花費時間
• CreatedYearMonth (String)
• 流程開始年月, Ex: 2024/03

R1_Task 可以顯示三個內容，當月總使用次數，當月平均花費時間，單據類型當月使用次數佔比。

當月總使用次數 : - 因為資料表只有一個月的內容，所以要顯示當月使用次數，只需要使用卡片來顯示，將 R1_Task 的筆數統計起來就可以了。

當月平均花費時間 : - 當月平均花費時間的計算方式是 Sum(TaskSpent) / 資料筆數 ，所以把卡片的內容設定為 TaskSpent 的平均即可。

單據類型當月使用次數佔比 : - 這個圓餅圖需要統計 [單據類型] 的總使用時間的比值，我們只需要使用 [環圈圖] ，把圖例設為 [CategoryName]，數值設定成 TaskSpent ，[環圈圖] 就會自動統計所有 CategoryName 並且顯示各個分類的比例。

返回資料表: R1_Category

流程報表1 - 過去 12 月份使用表單分類統計資料，用來根據不同表單分類畫出平均簽核時間的趨勢

• CategoryId (String)
• 表單分類代碼
• CategoryName (String)
• 表單的分類名稱
• YearMonth (DateTime)
• 資料的年月的第一天日期
• ApplicantCount (Int)
• 當月的申請次數
• CategorySpent (Decimal)
• 當月分類的使用時數
• AverageSpent (Decimal)
• 當月分類的平均使用時數

當我們把 R1_Category 使用折線圖表顯出來時，可以顯示過去一年，每個月表單分類使用時數的趨勢，是否有季節關聯，或者向上向下的走勢，或者使用率的分別。系統的功能是將分析的結果呈現給使用者，而使用者需要自己更進一步去理解那些數據代表的意義。

返回資料表: R1_Form

流程報表1 - 使用表單當月與前三個月比較差異

• FormId (String)
• 表單代碼
• FormName (String)
• 表單名稱
• CategoryId (String)
• 表單分類代碼
• CategoryName (String)
• 表單的分類名稱
• YearMonth (DateTime)
• 查詢的年月, 內容為當月的一號
• ApplicantCount (Int)
• 申請次數
• FormSpent (Decimal)
• 表單消耗時數
• AverageSpent (Decimal)
• 表單平均消耗時數
• BeforeCount (Int)
• 前三個月申請次數
• BeforeSpent (Decimal)
• 前三個月表單消耗時數
• BeforeAverageSpent (Decimal)
• 前三個月表單平均消耗時數
• DiffRate (Decimal)
• 查詢的月份，與前三個月平均簽核時間的差異比例 (值域: 0.00 ~ 1.00)

當我們將 R1_Form 以 [100% 堆疊橫條圖] 來顯示當月與前三個月的平均簽核時間的比較，對於那些表單最近的使用率比較高，可以全部列出，當然也能看到使用率最低的表單，企業的管理者倘若發現圖表內容有異常，就可以即時發現，日後就能做出調整。

第二張報表 - 單據逾時一覽表

這張報表需要 R2_ExpiredForm 的內容，報表由 [逾時單據數量]，[平均逾時時間]，[總逾時時間]，[逾時次數趨勢圖]，[表單類型逾時次數占比]，[表單平均逾時時數]，[表單逾時Pareto Chart分析]，各個部份所組成，以下說明如何利用資料表來顯示這些資訊。

返回資料表: R2_ExpiredForm

流程報表2 - 逾時表單過去 12 個月統計，這個資料表以表單為單位，統計過去 12 個月的表單逾時相關資訊 (目前的逾時判定方式為站點的通知頻率的時數，超過此時數還未往下送，則判定為逾時，通常這個數值為 8HR)，欄位列舉如下

• CategoryId (String)
• 表單分類代碼
• CategoryName (String)
• 表單的分類名稱
• FormId (String)
• 表單代碼
• FormName (String)
• 表單名稱
• YearMonth (DateTime)
• 表單申請年月
• ExpiredCount (Int)
• 逾時次數
• ExpiredHours (Decimal)
• 逾時時數
• ExpiredAverageHours (Decimal)
• 平均逾時時數(在某個年月之下的)

這個資料表已經做了一些逾時表單的統計，每張表單在每個月的統計值已經算好，只需要使用不同角度的運算，就可以顯示各個報表上面的數據，如果有足夠的資料來展現，理論上應該會呈現如下的報表，接著我們就來解釋報表上每個資料區塊要如何設定。

逾時單據數量 : - 這個數值是統計當月有多少單據逾時的數量，只需要把當月的 ExpiredCount 全部加起來即可，使用 卡片 來展現，並且將 YearMonth 設定為篩選欄位，只勾選當時月份。

平均逾時時間(h) : - 這個數值為 總逾時時間/逾時單據數量，也就是每張單據的平均逾時，使用 卡片 來展現，並且將 YearMonth 設定為篩選欄位，只勾選當時月份。

總逾時時間 : - 此數值為當月所有逾時時間的加總，使用 卡片 即可呈現，使用 卡片 來展現，並且將 YearMonth 設定為篩選欄位，只勾選當時月份。

逾時次數趨勢圖 : - 這個圖表以月分為單位，統計過去一年逾時次數的走勢圖，使用 折線圖 ，YearMonth 設定為 X 軸，ExpiredCount 設定為 Y 軸即可。

表單類型逾時次數占比 : - 這個圖表顯示了各種表單類型逾時所占的比例，使用 環圈圖 ，CategoryName 設定為圖例，ExpiredCount 設定為值，圖形會自動把圖例的欄位加總起來，變成數值去計算。記得將 YearMonth 設定為篩選欄位，只勾選當時月份。

表單平均逾時時數 : - 這個圖表從大到小，顯示各種表單的平均逾時時數，可以知道最常發生逾時的表單，進而加以改進流程。這個圖表使用 堆疊橫條圖 將 X 軸設定為 ExpiredAverageHours ，將 Y 軸設定為 FormName，將 YearMonth 設定為篩選欄位，只勾選當時月份。

表單逾時 Pareto Chart 分析 - Pareto Chart 為所謂的八二法則分析圖表，意義代表 20% 的部分，決定了 80% 的重要性。用在表單逾時上面，即為 20% 的表單，造成了 80% 的表單逾時。Pareto 曲線在 PowerBI 裡面並沒有內建，我們需要做一點手腳，在資料表的地方，新增一個 量值 內容設定為 :

    TotalHours = SUM('R2_ExpiredForm'[ExpiredHours])

接著在右邊資料表欄位的地方，新增一個 量值 內容設定為 :

Pareto = 
    var number=[TotalHours]
    var molecule=CALCULATE([TotalHours], FILTER(ALL('ExpiredForm'[FormName]), [TotalHours]>=number))
    var denominator=CALCULATE([TotalHours], ALL('ExpiredForm'[FormName]))
RETURN DIVIDE(molecule, denominator)

在報表上面拉出一個 折線與堆疊直條圖， FormName 設定為 X 軸，ExpiredHours 設定為 Y 軸，並且把線條 Y 軸，設定為剛剛產生的 Pareto 欄位，這樣一個漂亮的 Pareto Chart 就出現了。

第三張報表 - 單據逾時狀況表

這張報表需要資料表 R3_HalfYearForm 與 R3_Site，其組成為 [逾時單據數量]，[平均逾時時數(h)],[近六個月使用次數趨勢],[近六個月平均簽核時間趨勢] 以及 [簽核狀況列表] 幾個部分，如果有足夠數據，並且設定正確，應該會得到如下的報表，接下來說明相關的資料表規格，與圖表的組合方式。

返回資料表: R3_HalfYearForm

流程報表3 - 簽核狀況趨勢，這個資料表紀錄了最近六個月的簽核次數與簽核時間等資訊，可以利用來畫走勢圖。

• FormName (String)
• 表單名稱
• YearMonth (DateTime)
• 查詢的年月, 內容為當月的一號
• TaskCount (Int)
• 當月簽核的數量
• TaskHours (Decimal)
• 當月簽核的總時數
• AverageTaskSpent (Decimal)
• 平均花費簽核時間
• ExpiredTaskCount (Int)
• 簽核逾時次數
• ExpiredTaskHours (Decimal)
• 簽核逾時的總時數
• AverageExpiredTaskHours (Decimal)
• 簽核逾時的平均時數，其值 = 總逾時時數 / 總逾時次數

逾時單據數量 : - 要顯示這個數據，先拉出一個卡片，將其值設定為 R3_HalfYearForm 的 ExpiredTaskCount 欄位，然後過濾欄位設定成 YearMonth，指定為要查詢時的月份

平均逾時時數(h) : - 要顯示這個數據，先拉出一個卡片，將其值設定為 R3_HalfYearForm 的 AverageExpiredTaskHours 欄位，然後過濾欄位設定成 YearMonth，指定為要查詢時的月份

近六個月使用次數趨勢 : - 要顯示這個圖表，先拉出一個折線圖，把 X 軸設定成 R3_HalfYearForm.YearMonth 欄位，把 Y 軸設定成 R3_HalfYearForm.TaskCount 欄位，將 X 軸的階層切換到月份，就可以根據月份來顯示走勢圖。

近六個月平均簽核時間趨勢 : - 要顯示這個圖表，先拉出一個折線圖，把 X 軸設定成 R3_HalfYearForm.YearMonth 欄位，把 Y 軸設定成 R3_HalfYearForm.AverageTaskSpent 欄位，將 X 軸的階層切換到月份，就可以根據月份來顯示走勢圖。

返回資料表: R3_Site

流程報表3 - 簽核狀況列表，這個資料表列出部門簽核人員的簽核狀況，可以知道是否有簽核時間過度集中的問題。

• FormName (String)
• 表單名稱
• YearMonth (DateTime)
• 查詢的年月, 內容為當月的一號
• SignerDeptName (String)
• 簽核人員的部門
• SignerName (String)
• 簽核人員的名稱
• NodeCount (Int)
• 簽核人員的當月簽核數
• NodeSpent (Decimal)
• 簽核人員的當月簽核時間(h)
• NodeAverageSpent (Decimal)
• 簽核人員地當月平均簽核時間(h)
• NodePercentAtAll (Decimal)
• 簽核人員與部門總簽核時間的占比

簽核狀況列表 : - 這邊的顯示，直接用資料表來顯示即可，把 SignerDeptName, SignerName, NodeCount, NodeAverageSpent, NodePercentAtAll 等欄位拉到資料表裡面，依序變更欄位名稱，即可得到如下的資料表內容。