跳轉到

使用說明

flowchart LR
    A(GitHub下載範例) --> B(設定站台網址與金鑰)
    A --> C(將 formschema.cs 加入專案) --> D(設定申請者) --> J(起單)
    C --> F(填寫欄位資料)--> J
    C --> G(附件<br>-非必要-)--> J
    C --> H(Callback<br>-非必要-)--> J

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

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

  1. 透過 Visual Studio 建立一個新的主控台應用程式 (Console App)
  2. 已將專案透過 NuGet 安裝 SDK，並設定好 SDK 參數
  3. 已取得 UOF X 站台網址
  4. 已取得 金鑰
  5. 已匯出一份 API 起單檔案(表單包含一單行文字欄位)，參考取得 API 起單檔案

加入 API 起單檔案

從方案總管中對專案按右鍵 > 加入 > 現有項目，選取匯出的 API 起單檔案 將其加入專案中，如下圖加入的 API 起單檔案 檔名為 formSchema.cs。

Image reference-schema

開始寫程式...

以下為完整的範例內容 

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

//設定金鑰
UofxService.Key = "xxx";

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

//上傳檔案
var fileView = await UofxService.File.FileUpload(@"C:\Users\Doucument\sample.pdf");
//轉換成檔案物件
var fileItem = new Ede.Uofx.FormSchema.UofxFormSchema.FileItem()
{
    Id = fileView.Id,
    FileName = fileView.FileName
};


//建立 外部起單物件
var doc = new Ede.Uofx.FormSchema.UofxFormSchema.UofxFormSchema()
{
    // 主要公司代碼 (如為其他公司兼職才需要填)
    // CorpCode = "ede-a"
    // 申請者帳號
    Account = "Justin",
    // 申請者部門代號
    DeptCode = "RD",
    // 要 CallBack 的 Url
    //CallBackUrl = "https://hr-system.com.tw/uofx-sdk/callback",
    // 客製資訊: 填入起單時間
    //CustomData = $"{DateTimeOffset.Now}",
    // 將檔案物件入附件欄位
    // AttachFiles = new List<Ede.Uofx.FormSchema.UofxFormSchema.FileItem>()
    // {
    //  fileItem
    // }
};

//建立 表單欄位物件，填寫表單欄位資料
doc.Fields = new Ede.Uofx.FormSchema.UofxFormSchema.UofxFormSchemaFields()
{
    C002 = "測試",
};

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));
}

使用方法

我們來逐步撰寫範例，首先在前置作業加入的API 起單檔案 formSchema.cs，其裡面已包含 外部起單物件 的 public class UofxFormSchema (你的 class 名稱可能不同)，我們必須輸入兩個資訊:

  • 申請者資訊
  • 表單欄位資料

先建立 外部起單物件，然後在 Account 和 DeptCode 屬性分別輸入帳號和部門代碼。

//建立 外部起單物件
var doc = new Ede.Uofx.FormSchema.UofxFormSchema.UofxFormSchema()
{
    //申請者帳號
    Account = "Justin",
    //申請者部門代號
    DeptCode = "RD"
};

員工身兼多個部門

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

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

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

//建立 表單欄位物件，填寫表單欄位資料
doc.Fields = new Ede.Uofx.FormSchema.UofxFormSchema.UofxFormSchemaFields()
{
    C002 = "測試",
};

呼叫 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 機制取得成功或失敗的資訊。

夾帶檔案附件

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

檔案物件 FileItem

在每個匯出的 API 起單檔案中，皆有檔案物件的 class，其包含了兩個屬性 Id 與 FileName，透過 SDK 上傳檔案後取得其值。

注意

請勿自行產生 Id 與 FileName，應透過 SDK 上傳檔案後取得。

public partial class FileItem
{
  public System.Guid Id { get; set; }
  public string FileName { get; set; }
}

透過 SDK 上傳檔案

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

//上傳檔案
var fileView = await UofxService.File.FileUpload(@"D:\sample\sample.pdf");

注意

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

注意

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

兼職人員起單

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

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

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

//建立 外部起單物件
var doc = new Ede.Uofx.FormSchema.UofxFormSchema.UofxFormSchema()
{
    //主要公司代碼 (如為其他公司兼職才需要填)
    CorpCode = "ede-a"
    //申請者帳號
    Account = "Justin",
    //申請者部門代號
    DeptCode = "RD"
};

錯誤處理

為確保程式不會因為異常 (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