跳轉到

如何使用

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. 取得要起單的表單代號

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

在開始建立表單資料前，我們可以先透過 表單代號 取得此表單的全部欄位資訊，方法如下:

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

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

//取得表單欄位資訊
var info = await UofxService.BPM.GetFormInfo("表單代號");
Console.WriteLine(UofxService.Json.Convert(info));

回傳的欄位資訊 (info) 是 JSON 格式，其結構如下:

{
  "Fields": [
    {
      "Name": "姓名",   <==欄位名稱
      "Code": "C002",   <==欄位代號
      "TypeId": "text", <==欄位類型
      "FieldHelper": "FieldHelper.Base.Text", <==建議輸入數值方式
      "Fields": null,   <==子欄位
      "IsRequired": false    <==是否必填
    }
  ]
}

有了這些欄位資訊後，接下來才知道起單要填多少欄位，以及欄位類型是什麼，並且就算往後表單變更，只要重複上述方法，就能取得最新的欄位資訊了。

開始寫程式...

以下為完整的範例內容 

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

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


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

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

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

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

try
{
    //呼叫站台進行起單
    var traceId = await UofxService.BPM.ApplyForm(doc);
    //將 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 輸入申請者帳號和部門代碼 (Account 和 DeptCode)。

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

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

員工身兼多個部門

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

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

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

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

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

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

{
  "Fields": [
    {
      "Name": "姓名",   
      "Code": "C002",   
      "TypeId": "text", 
      "FieldHelper": "FieldHelper.Base.Text", <==建議輸入數值方式
      "Fields": null   
    }
  ]
}

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

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

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

//產生表單物件
var doc = 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 站台進行起單

外部起單的 method 位於 UofxService.BPM.ApplyForm，注意其為非同步的涵式，所以我們加上 await 等待呼叫結果，並建立一個變數 traceId 接收此次呼叫回傳的唯一代號，最後我們將結果輸出到畫面上。

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

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

Image success-result

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

夾帶檔案附件

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

檔案物件 FileModel

檔案物件 (Ede.Uofx.PubApi.Sdk.NetStd.Helpers.FileModel) 有兩個屬性 Id 、 FileName，請勿自行產生 Id 與 FileName，應透過 SDK 上傳檔案後取得。 

public class FileModel
{
    public Guid Id { get; private set; }

    public string FileName { get; private set; }
}

透過 SDK 上傳檔案

透過 SDK 上傳檔案只需要一個步驟，呼叫 UofxService.File.FileUpload，並傳入完整的檔案路徑。

//上傳檔案
var fileView = await UofxService.File.FileUpload(@"D:\sample\sample.pdf");
//轉成檔案物件
var fileItem = new FileModel(fileView.Id, fileView.FileName);

注意權限

請確保檔案路徑是有效且有可讀取權限

時效性

SDK 上傳的檔案有時效性，超過一天即會失效。

Filestream支援

UofxService.File.FileUpload 也支援 FileStream 型態參數

夾帶檔案或使用檔案欄位

接著將檔案物件放入對應欄位即可

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

兼職人員起單

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

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

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

//申請者帳號、申請者部門代號、主要公司代碼 (如為其他公司兼職才需要填)
formHelper.ApplyAccount("Justin", "PRX", "ede-a");
//formHelper.ApplyAccount("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));
}
錯誤訊息中會有錯誤代碼，請查詢附錄1-錯誤代碼表來修正錯誤。
Image fail-result