ดูแลองค์กร

สมาชิกและผังองค์กร

สมาชิก หน่วยงาน ตำแหน่ง กลุ่ม attribute นำเข้า CSV และ endpoint resolve

ไดเรกทอรีคือองค์กรในสายตาของ Pi Auth: ใครเป็นสมาชิก นั่งอยู่ตรงไหน ถือตำแหน่งอะไร แอปอ่านจากโทเค็นหรือ API แทนที่จะเก็บสำเนาเอง และสิทธิ์ก็ผูกอยู่กับมัน — การรักษาไดเรกทอรีให้ทันสมัยจึงเป็นสิ่งที่ทำให้ทุกอย่างถูกต้อง

สมาชิก

สมาชิกคือผู้ใช้ภายใน tenant หนึ่ง เข้ามาได้จากคำเชิญ (อีเมล) จาก SSO ขององค์กรตอนล็อกอินครั้งแรก จากการนำเข้า CSV หรือผ่าน SCIM provisioning จากระบบ HR หรือ IdP

ฟิลด์	ความหมาย
Base role	`owner`, `admin` หรือ `member` owner และ admin ดูแล tenant (สิทธิ์ในตัว `tenant:admin`, `directory:`, `access:`); member ได้ `directory:read` ต้องมี owner อย่างน้อยหนึ่งคนเสมอ
สถานะ	`INVITED` → `ACTIVE`; `SUSPENDED` เก็บข้อมูลไว้แต่ห้ามล็อกอินและตัดสิทธิ์; `LEFT` คือสถานะออก — membership ยังอยู่เพื่อ audit แต่ไม่ปรากฏที่อื่น
หน่วยงานและตำแหน่งหลัก	สมาชิกอยู่ตรงไหนในผังและถือตำแหน่งอะไร — ทั้งคู่ไปอยู่ในโทเค็นเป็น org และ pos
Assignment	ที่นั่งเพิ่มเติม: SECONDARY (สังกัดรอง), ACTING (รักษาการตำแหน่ง), DELEGATE (ได้รับมอบอำนาจ) แต่ละอันมีช่วงเวลามีผลได้
Attribute	ฟิลด์เพิ่มเติมแบบมีชนิด (ข้อความ ตัวเลข วันที่ เลือกจากรายการ ใช่/ไม่ใช่) อันที่ติ๊ก “ใส่ในโทเค็น” จะไปอยู่ใน attrs

หน่วยงาน

หน่วยงานเป็นต้นไม้ แต่ละหน่วยมี code และ code ต่อกันเป็น path เช่น /acme/eng/it path คือสิ่งที่แอปและ binding ใช้: ผูก role กับ /acme/eng รวมหน่วยย่อย จะครอบคลุมทุกคนใน IT, QA และหน่วยใดก็ตามที่สร้างใต้ Engineering ในภายหลัง ย้ายหน่วยแล้ว path ของทุกอย่างใต้มันอัปเดตตาม

ตำแหน่ง

ตำแหน่งคืองานที่มี code และ level เป็นตัวเลข (DIR level 1, MGR level 2, …) level ทำให้แอปและ resolve API ถามได้ว่า “หัวหน้าที่ใกล้ที่สุดเหนือคนนี้คือใคร” โดยไม่ต้อง hard-code ชื่อ สมาชิกถือตำแหน่งหลักหนึ่งตำแหน่ง assignment แบบรักษาการและสังกัดรองเพิ่มได้อีก

กลุ่ม

กลุ่มคือชุดสมาชิกแบบแบนที่ตัดข้ามผัง — “ทีมดับเพลิง”, “SAP key users” เป็นเป้าหมายของ binding ได้ และปรากฏในโทเค็นเป็น groups

นำเข้าทีละมาก

สมาชิก → นำเข้า CSV อัปเดตหน่วยงาน ตำแหน่ง รหัสพนักงาน และ attribute ของสมาชิกในครั้งเดียว — อีเมลที่ยังไม่เป็นสมาชิก: ถ้ามีบัญชี Pi Auth แล้วจะถูกเพิ่มเป็นสมาชิกทันที (role จากคอลัมน์ role: member/admin) ถ้ายังไม่มีบัญชีจะได้รับคำเชิญทางอีเมล และหน่วยงาน/ตำแหน่ง/attribute ในแถวนั้นถูกใส่ให้เมื่อตอบรับ (การเชิญต้องนำเข้าด้วยบัญชีผู้ใช้ ไม่ใช่ service token; ผลลัพธ์แยกนับ updated / added / invited) ส่งออก CSV ให้รูปแบบเดียวกัน วงจรปกติจึงเป็น ส่งออก → แก้ → นำเข้า แต่ละแถวถูกนำเข้าแยกกัน แถวที่ผิดจะรายงานเลขบรรทัดและเหตุผลกลับมา ส่วนที่เหลือผ่านตามปกติ คอลัมน์เพิ่มเติมจับคู่กับ attribute ตาม key

members.csv

email,name,employeeNo,orgUnitCode,positionCode,role,status
somchai@acme.co.th,สมชาย ใจดี,E-0042,it,MGR,member,ACTIVE
new.hire@acme.co.th,New Hire,E-0107,it,ENG,member,ACTIVE

ถามคำถามกับไดเรกทอรี

แอปแทบไม่ต้องการทั้งต้นไม้ แต่ต้องการ “ใครอนุมัติเรื่องนี้?” endpoint resolve ไล่ขึ้นจากหน่วยงานของสมาชิก แล้วคืนผู้ถือตำแหน่งที่ระบุ ใกล้สุดก่อน รวมผู้รักษาการเมื่อขอ:

SDK

const { matches } = await svc.directory.resolve({
  positionCode: "DIR",
  withinOrgPathOf: user.tenant.membershipId,
  nearestOnly: true,
});