跳轉到

如何使用

flowchart LR
    A(GitHub下載範例) --> B(設定站台網址、金鑰、公司代碼)
    B --> C(設定申請者)
    C --> F(填寫欄位資料)--> J
    C --> G(附件<br>-非必要-)--> J
    C --> H(Callback<br>-非必要-)--> J
    J(起單)

接下來的範例將使用 Visual Studio 建立一個主控台應用程式 (Console App)，程式語言為 C#。依照實際需求，您也可以使用 WebApi、ClassLibrary 來完成外部起單，請參考系統需求篇的支援說明。

在繼續往下說明之前，請確認您下列事項皆已經準備完成:

  1. 透過 Visual Studio 建立一個新的主控台應用程式 (Console App)
  2. 已將專案透過 NuGet 安裝 SDK，並設定好 SDK 參數
  3. 已取得 UOF X 站台網址
  4. 已取得 金鑰
  5. 已取得 公司代碼
  6. 取得要起單的 表單代號

開始之前，先取得表單欄位資訊...

在開始建立表單資料前，我們可以先透過 表單代號 取得全部的欄位資訊，有了欄位資訊，才知道起單要填多少欄位，以及欄位類型是什麼，並且就算往後表單變更，只要重複此操作，就能取得最新的欄位資訊，方法如下:

命名空間: Ede.Uofx.OpenApi.Sdk.NetStd.Service

方法名稱: UofxService.BPM.Apply.GetFormInfo

var info = await UofxService.BPM.Apply.GetFormInfo("表單代號");

輸入參數

屬性 型態 必填 預設值 說明
formCode string V 表單代碼

回傳結果

命名空間: Ede.Uofx.OpenApi.Sdk.NetStd.Models.Bpm

物件名稱: FormInfo

屬性 型態 說明
AllowApplyForm bool 此單據是否可外部起單
Fields IList<FieldViewModel> 表單欄位

命名空間: Ede.Uofx.OpenApi.Sdk.NetStd.Models.Bpm

物件名稱: FieldViewModel

屬性 型態 說明
Name string 欄位名稱
Code string 欄位代碼
TypeId string 欄位類型
FieldHelper string FieldHelper 使用方式
IsRequired bool 必填
NotSupport bool SDK 是否支援此欄位
Fields IList<FieldViewModel> 子欄位

不要使用不支援的欄位

🚨 請勿對不支援的欄位 (NotSupport = true) 輸入任何值，這會導致未知的異常。

並非每個表單都可以外部起單

🚨 請留意 AllowApplyForm 屬性，如果其為 false，代表此表單不支援外部起單，通常是因為有特定欄位為 "SDK不支援欄位" ，且又為必填導致。

開始寫程式...

以下為完整的範例內容 

using Ede.Uofx.PubApi.Sdk.NetStd.Service;
using System;

// 設定金鑰
UofxService.Key = "xxx";
// 設定公司代碼
UofxService.CorpCode = "ooo";
// 設定 UOF X 站台網址
UofxService.UofxServerUrl = "https://myuofx.com.tw";

// 申請的表單代號
var formHelper = new FormHelper("表單代號");

// 申請者帳號、申請者部門代號
formHelper.ApplyAccount(UserModel.Create(UserType.Account, "Justin"), "PRX");

// 填入表單欄位值
formHelper.FieldAdd("C002", FieldHelper.Base.Text("測試"));

// 產生表單物件
var form = formHelper.Complete();

try
{
  // 呼叫站台進行起單
  var traceId = await UofxService.BPM.Apply.ApplyForm(form);
  // 將 Trace Id 印出
  Console.WriteLine($"Trace Id: {traceId}");
}
catch (Exception e)
{
  // 將 exception 轉換成較容易判斷的 model
  var model = UofxService.Error.ConvertToModel(e);
  // 將 model 轉成 json 格式印出
  Console.WriteLine(UofxService.Json.Convert(model));
}

使用方法

我們來逐步撰寫範例，首先指定要起單的 表單代號，並取得起單輔助器物件，接著透過 ApplyAccount 輸入申請者和部門代碼 (User 和 DeptCode)。

命名空間: Ede.Uofx.OpenApi.Sdk.NetStd.Helpers

物件名稱: FormHelper

//申請的表單代號
var formHelper = new FormHelper("表單代號");

//申請者、申請者部門代號
formHelper.ApplyAccount(UserModel.Create(UserType.Account, "Justin"), "PRX");

申請者

申請者用法請參考 UserModel 物件

員工身兼多個部門

如果員工同時身兼多個部門，則 DeptCode 請依照表單申請的需求，填入適當的部門，其將影響簽核流程的簽核人員判斷。

接下來填入 表單欄位資料，例如範例中的表單有一個「單行文字」欄位，代號為 C002，我們將 C002 填入 '測試'。

//填入表單欄位值
formHelper.FieldAdd("C002", FieldHelper.Base.Text("測試"));

PS1: 請依照您的表單欄位填入對應數值，表單設計中設定為必填的欄位皆須給值。

PS2: 更多欄位 FieldHelper 使用方式請參考 目前支援欄位章節

欄位數值可以藉由 FieldHelper 小工具幫助填入正確的格式，在前面 取得表單欄位資訊 中，可以查看每個欄位的 FieldHelper 使用方式，這能有效避免資料格式的錯誤。

你也可以如下列方式直接填入 '測試'，對「單行文字」欄位而言會得到同樣的結果，但我們不建議這樣做，因為有些欄位類型並非輸入 '字串' 就可以表達。

//填入表單欄位值
formHelper.FieldAdd("C002", "測試"); 
//formHelper.FieldAdd("C002", FieldHelper.Base.Text("測試"));

在填完所有欄位值後，使用 Complete() 取得表單物件就可以準備起單了。

//產生表單物件
var form = formHelper.Complete();

注意complete使用時機點

請確保欄位資料都填入後才呼叫 Complete，通常應該是在起單前才進行此動作。

驗證欄位

為避免當表單起單後才發現欄位沒填...等問題，可以在填完所有欄位後呼叫 ValidFields 來檢查錯誤。 

//驗證欄位輸入狀況
formHelper.ValidFields(out var unenteredFields, out var unenteredAndRequiredFields, out var notFoundFields);

out 輸出變數 型態 說明
unenteredFields List<string> 非必填欄位未填
unenteredAndRequiredFields List<string> 必填欄位未填 (這會導致起單失敗)
notFoundFields List<string> 欄位代碼不存在表單中 (不會造成起單失敗，但輸入資料會遺失)

注意

此方法無法檢驗出格式錯誤 (例: 應該是數字卻輸入英文)，輸入 null、空字串 (string.Empty) 等情形。

呼叫 X 站台進行起單

確定欄位資料都填完後，就可以呼叫 SDK 進行起單等待呼叫結果，同時建立一個變數 traceId 接收此次呼叫回傳的唯一代號，最後我們將結果輸出到畫面上。

命名空間: Ede.Uofx.OpenApi.Sdk.NetStd.Service

方法名稱: UofxService.BPM.Apply.ApplyForm

try
{
  //呼叫站台進行起單
  var traceId = await UofxService.BPM.Apply.ApplyForm(form);
  //將 Trace Id 印出
  Console.WriteLine($"Trace Id: {traceId}");
}

按下 F5 執行看看，正確的話應該會得到如下的結果:

Image success-result

取得 Trace Id 代表已經向 UOF X 站台發送外部起單完成 ，但並非代表 起單一定成功，因為這只表示 UOF X 接收到此需求並轉為背景處理，可能會因為當下的組織或表單版本等，導致起單失敗，表單負責人可以從他的管理面版得知起單失敗情形，外部系統也可透過 Callback 機制取得成功或失敗的資訊。

夾帶檔案附件

外部起單也支援夾帶檔案附件，但在必須在呼叫外部起單前，先將檔案上傳取得 檔案物件(FileViewModel)，後續才能將檔案夾帶在表單，或放進表單的檔案欄位中。

有關檔案上傳的說明，請參考 通用方法 > 檔案上傳章節

夾帶檔案或使用檔案欄位

透過上傳檔案取得 檔案物件 後，將其放入對應欄位即可

// 夾帶附件
formHelper.AttachFiles(new List<FileViewModel>() { fileObj });
// 上傳檔案欄位
formHelper.FieldAdd("C017", FieldHelper.Base.FileUpload(new List<FileViewModel>() { fileObj }));
// 文件檢視器欄位
formHelper.FieldAdd("C027", FieldHelper.Base.FilesViewer(new List<FileViewModel>() { fileObj }));

兼職人員起單

UOF X 支援建立多公司，並且人員可以跨公司兼任。例如 UOF X 系統中有兩間公司 A 和 B，員工 Justin 在 A 公司中任職，但也在 B 公司兼任，如下圖:

UOF X
|  └─ 🏢 公司 A (公司代碼: ede-a)
|    └─ 🧑 員工: Justin (主要)
|  └─ 🏢 公司 B (公司代碼: ede-b)
|    └─ 🧑 員工: Justin (兼任)

如果要幫員工從 B 公司 (兼職的公司) 外部起單，則必須給予此員工的主要公司代碼，方能成功起單。

// 申請者帳號、申請者部門代號、主要公司代碼 (如為其他公司兼職才需要填)
formHelper.ApplyAccount(UserModel.Create(UserType.Account, "Justin", "ede-a"), "PRX");
//formHelper.ApplyAccount(UserModel.Create(UserType.Account, "Justin"), "PRX"); //沒兼職的方法

詳細說明請參考 通用物件 > 使用者物件

錯誤處理

為確保程式不會因為異常 (exception) 而導致中斷，應該要在呼叫站台進行起單加上 try catch 去攔截錯誤 (請參考 SDK 呼叫異常章節)，攔截錯誤程式碼如下:

catch (Exception e)
{
  // 將 exception 轉換成較容易判斷的 model
  var model = UofxService.Error.ConvertToModel(e);
  // 將 model 轉成 json 格式印出
  Console.WriteLine(UofxService.Json.Convert(model));
}
錯誤訊息中會有錯誤代碼，請查詢錯誤代碼表來修正錯誤。