應用情境 - 新增組織

「維護組織人員」功能用於快速更新組織架構及人員資訊。在整合 UOF X 與 HR 系統的過程中，可能出現兩邊系統的組織資料不同步的情況，因此，UOF X 提供了此功能，讓公司能夠有效解決資料不同步的問題，確保與 HR 系統資料的一致性。該功能支援建立組織架構及同步組織人員資訊，以下會展示一個應用情境：「新增組織」，並提供具體的實作步驟與方法作為參考。

應用情境¶

公司 A 最近導入 UOF X，但由於現有的組織資料仍存放於舊有的 HR 系統中，因此需要將這些資料新增至 UOF X，以確保兩套系統的組織資訊一致。

若採用手動新增，雖然能針對每個部門或人員資料進行細緻調整，但此方式容易耗費大量時間與人力，且隨著資料量的增加，更可能導致資料遺漏或輸入錯誤。

透過 UOF X 維護組織人員功能，只需將 HR 系統中的資料轉換為匯入格式，即可快速完成多筆資料的同步。

UOF X 與 HR 整合優勢¶

資料同步與一致性：確保 UOF X 與 HR 系統中的組織架構及人員資訊保持一致，避免因資料不同步導致的管理混亂。
提升管理效率：支援自動同步與批次更新，減少重複輸入的工作，降低人為錯誤風險。
即時更新組織變動：當組織調整或人事異動時，可透過 UOF X 快速反映變動，確保內部系統即時更新。
減少人力與時間成本：自動化的同步流程降低人力需求，提升資料維護效率，節省大量時間。
降低資料不一致風險：整合過程中即時檢查與更新，避免資料不一致對業務流程造成的影響。

實作¶

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

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

透過 Visual Studio 建立一個新的主控台應用程式 (Console App)
已將專案透過 NuGet 安裝 SDK，並設定好 SDK 參數
已取得 UOF X 站台網址
已取得 金鑰

範例程式下載: https://github.com/UOfficeForceX/SDK-Quickstart

以下為情境中新增組織的完整範例內容，分為六大部分:

設定金鑰、站台網址: 可參考 SDK 參數設定
新增組織: 依據組織人員結構，新增人員前需先建立職務、職稱與部門，可參考目前支援組織人員 API
新增人員: 填入人員資料，可參考目前支援組織人員 API - 人員
新增部門主管: 將該人員設定為部門主管，可參考目前支援組織人員 API - 部門主管
取得人員帳號與部門: 查看上述資料是否已成功建立
更新使用者權限: 確保修改造成的權限異動有被重新套用

using Ede.Uofx.PubApi.Sdk.NetStd.Interfaces;
using Ede.Uofx.PubApi.Sdk.NetStd.Models.Base;
using Ede.Uofx.PubApi.Sdk.NetStd.Service;
using Newtonsoft.Json;

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

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

try
{
    // 新增部門層級
    var addDeptLev = await UofxService.BASE.DeptLevel.Create(new DeptLevelViewModel()
    {
        CorpCode = "CorpCode", // 公司代號
        Seq = 1, // 部門層級的階層與排序 ( 從 1 開始 )
        Code = "lev-max", // 部門層級代號
        Name = "Level Max", // 部門層級名稱
        Active = true // 是否啟用部門層級
    });
    Console.WriteLine($"新增部門層級: {addDeptLev}");

    // 新增部門
    var addDept = await UofxService.BASE.Department.Create(new DepartmentCreateModel()
    {
        ParentCode = "", // 父部門代號 ( 可設定為空值，代表無父部門 )
        CorpCode = "CorpCode", // 公司代號
        Code = "Demo", // 部門代號
        DeptLevelCode = "lev-max", // 部門層級代號
        Name = "Demo部門", // 部門名稱
        Description = "從 SDK 建立部門" // 描述
    });
    Console.WriteLine($"新增部門: {addDept}");

    // 新增職稱
    var addTitle = await UofxService.BASE.JobTitle.Create(new JobTitleViewModel()
    {
        CorpCode = "CorpCode", // 公司代號
        Rank = 1, // 職稱階層
        Seq = 1, // 職稱排序 ( 從 1 開始 )
        Code = "Boss", // 職稱代號
        Title = "老闆", // 職稱名稱
        Active = true // 是否啟用職稱
    });
    Console.WriteLine($"新增職稱: {addTitle}");

    // 新增職務類別與職務
    var addFunc = await UofxService.BASE.JobFunc.Create(new JobFuncViewModel()
    {
        CorpCode = "CorpCode", // 公司代號
        CategoryName = "管理", // 不存在會自動新增
        Code = "Decision", // 職務代號
        JobFunc = "決策", // 職務名稱
        Active = true // 是否啟用職務
    });
    Console.WriteLine($"新增職務類別與職務: {addFunc}");

    // 新增人員
    var addEmpl = await UofxService.BASE.OrgEmpl.CreateEmpl(new EmpCreateRequestModel()
    {
        CorpCode = "CorpCode", // 公司代號
        Account = "boss", // 人員帳號
        Name = "王老闆", // 中文姓名
        Gender = "2", // 性別 ( 男性 0, 女性 1, 其他 2 )
        EnglishName = "Boss Wang", // 英文姓名
        EmployeeNumber = "EMP01234", // 員工編號
        ExpiredTime = DateTime.Now.AddYears(5), // 帳號過期時間
        IdCardNumber = "A123456789", // 身份證字號
        BirthDate = new DateTime(1992, 8, 25), // 生日
        PhoneNumber = "0912345678", // 行動電話
        BusinessCard = "Wang - Boss", // 名片職稱
        HireDate = new DateTime(2015, 4, 10), // 到職日
        Email = "boss@example.com", // 主要信箱
        EmailEx = "boss@corp.com", // 其他信箱
        Depts = new List<EmpCreateOfDeptItemRequestModel>
        {
        new EmpCreateOfDeptItemRequestModel
        {
            Code = "Demo", // 部門代號
            IsMainDept = true, // 是否為主要部門
            JobTitleCode = "Boss", // 職稱代號
            JobFuncs = new List<string> { "Decision" } // 職務代號 ( 可多筆 )
        }
        }
    });
    Console.WriteLine($"新增人員: {addEmpl}");

    // 設定部門主管
    var setDeptManager = await UofxService.BASE.Department.Manager.Set(new DeptSetManagerModel()
    {
        CorpCode = "CorpCode", // 公司代號
        Code = "Demo", // 部門代號
        Type = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
        Value = "boss" // 帳號或員編
    });
    Console.WriteLine($"設定部門主管: {setDeptManager}");

    // 取得該人員帳號與部門
    var empl = await UofxService.BASE.OrgEmpl.Get(new EmplQueryRequestModel()
    {
        CorpCode = "CorpCode", // 公司代號
        UserType = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
        UserCode = "boss" // 帳號或員編
    });

    var emplDept = await UofxService.BASE.OrgEmpl.GetDept(new EmplQueryRequestModel()
    {
        CorpCode = "CorpCode", // 公司代號
        UserType = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
        UserCode = "boss" // 帳號或員編
    });
    Console.WriteLine("人員帳號與部門");
    Console.WriteLine(JsonConvert.SerializeObject(empl, Formatting.Indented));
    Console.WriteLine(JsonConvert.SerializeObject(emplDept, Formatting.Indented));

    // 更新使用者權限 
    await UofxService.BASE.Permission.UpdateUserPermission();
}
catch (Exception e)
{
    //將 exception 轉換成較容易判斷的 model
    var model = UofxService.Error.ConvertToModel(e);
    //將 model 轉成 json 格式印出
    Console.WriteLine(UofxService.Json.Convert(model));
}

新增部門層級¶

首先，建立一個部門層級，呼叫 UofxService.BASE.DeptLevel.Create 建立 DeptLevelViewModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功

// 新增部門層級
var addDeptLev = await UofxService.BASE.DeptLevel.Create(new DeptLevelViewModel()
{
    CorpCode = "CorpCode", // 公司代號
    Seq = 1, // 部門層級的階層與排序 ( 從 1 開始 )
    Code = "lev-max", // 部門層級代號
    Name = "Level Max", // 部門層級名稱
    Active = true // 是否啟用部門層級
});
Console.WriteLine($"新增部門層級: {addDeptLev}");

新增部門¶

有了部門層級，接著建立部門，並將部門的層級設定為上述新增之部門層級。呼叫 UofxService.BASE.Department.Create 建立 DepartmentCreateModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功

// 新增部門
var addDept = await UofxService.BASE.Department.Create(new DepartmentCreateModel()
{
    ParentCode = "", // 父部門代號 ( 可設定為空值，代表無父部門 )
    CorpCode = "CorpCode", // 公司代號
    Code = "Demo", // 部門代號
    DeptLevelCode = "lev-max", // 部門層級代號
    Name = "Demo部門", // 部門名稱
    Description = "從 SDK 建立部門" // 描述
});
Console.WriteLine($"新增部門: {addDept}");

新增職稱¶

接著建立職稱，呼叫 UofxService.BASE.JobTitle.Create 建立 JobTitleViewModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功

// 新增職稱
var addTitle = await UofxService.BASE.JobTitle.Create(new JobTitleViewModel()
{
    CorpCode = "CorpCode", // 公司代號
    Rank = 1, // 職稱階層
    Seq = 1, // 職稱排序 ( 從 1 開始 )
    Code = "Boss", // 職稱代號
    Title = "老闆", // 職稱名稱
    Active = true // 是否啟用職稱
});
Console.WriteLine($"新增職稱: {addTitle}");

新增職務類別與職務¶

再來新增職務類別與職務，呼叫 UofxService.BASE.JobFunc.Create 建立 JobFuncViewModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功

// 新增職務類別與職務
var addFunc = await UofxService.BASE.JobFunc.Create(new JobFuncViewModel()
{
    CorpCode = "CorpCode", // 公司代號
    CategoryName = "管理", // 不存在會自動新增
    Code = "Decision", // 職務代號
    JobFunc = "決策", // 職務名稱
    Active = true // 是否啟用職務
});
Console.WriteLine($"新增職務類別與職務: {addFunc}");

新增人員¶

有了部門、職稱與職務，則可以新增人員帳號，並將上述建立的資料設定到該人員資料中。呼叫

var{

UofxService.BASE.OrgEmpl.Create 建立 EmpCreateRequestModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功 href="#__codelineno-5-1">// 新增人員 class="w"> addEmpl = await UofxService.BASE.OrgEmpl.CreateEmpl(new EmpCreateRequestModel() pan> CorpCode = "CorpCode", // 公司代號 Account = "boss", // 人員帳號 Name = "王老闆", // 中文姓名 Gender = "2", // 性別 ( 男性 0, 女性 1, 其他 2 ) EnglishName = "Boss Wang", // 英文姓名 EmployeeNumber = "EMP01234", // 員工編號 ExpiredTime = DateTime.Now.AddYears(5), // 帳號過期時間 IdCardNumber = "A123456789", // 身份證字號 BirthDate = new DateTime(1992, 8, 25), // 生日 PhoneNumber = "0912345678", // 行動電話 BusinessCard = "Wang - Boss", // 名片職稱 HireDate = new DateTime(2015, 4, 10), // 到職日 Email = "boss@example.com", // 主要信箱 EmailEx = "boss@corp.com", // 其他信箱 Depts = new List<EmpCreateOfDeptItemRequestModel> { new EmpCreateOfDeptItemRequestModel { Code = "Demo", // 部門代號 IsMainDept = true, // 是否為主要部門 JobTitleCode = "Boss", // 職稱代號 JobFuncs = new List<string> { "Decision" } // 職務代號 ( 可多筆 ) } } }); Console.WriteLine($"新增人員: {addEmpl}");

設定部門主管¶

接著將新增人員設定為該部門主管，呼叫 UofxService.BASE.Department.Manager.Set 建立 DeptSetManagerModel 物件，並 Console.WriteLine 列印出結果，若回傳 True 代表建立成功

// 設定部門主管
var setDeptManager = await UofxService.BASE.Department.Manager.Set(new DeptSetManagerModel()
{
    CorpCode = "CorpCode", // 公司代號
    Code = "Demo", // 部門代號
    Type = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
    Value = "boss" // 帳號或員編
});
Console.WriteLine($"設定部門主管: {setDeptManager}");

取得人員及人員部門¶

最後，我們呼叫 UofxService.BASE.OrgEmpl.Get 及 UofxService.BASE.OrgEmpl.GetDept 來取得新增人員之帳號與部門資訊，並 Console.WriteLine 列印出結果

// 取得該人員帳號與部門
var empl = await UofxService.BASE.OrgEmpl.Get(new EmplQueryRequestModel()
{
    CorpCode = "CorpCode", // 公司代號
    UserType = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
    UserCode = "boss" // 帳號或員編
});

var emplDept = await UofxService.BASE.OrgEmpl.GetDept(new EmplQueryRequestModel()
{
    CorpCode = "CorpCode", // 公司代號
    UserType = UserType.Account, // 人員的類別 ( 帳號 Account, 員編 EmployeeNo )
    UserCode = "boss" // 帳號或員編
});
Console.WriteLine("人員帳號與部門");
Console.WriteLine(JsonConvert.SerializeObject(empl, Formatting.Indented));
Console.WriteLine(JsonConvert.SerializeObject(emplDept, Formatting.Indented));

更新使用者權限¶

完成後，別忘了要呼叫 更新使用者權限，確保修改造成的權限異動有被重新套用。

更新使用者權限

不管針對組織人員修改了什麼，在程式最後都呼叫一次 更新使用者權限 就對了。

// 更新使用者權限 
await UofxService.BASE.Permission.UpdateUserPermission();