#เหตุการณ์ก่อนดำเนินการ

#บทนำ

ปลั๊กอินเหตุการณ์ก่อนดำเนินการมีกลไกการดักจับการดำเนินการ ซึ่งจะทำงานหลังจากมีการส่งคำขอสำหรับการดำเนินการสร้าง (create), อัปเดต (update) หรือลบ (delete) แต่ก่อนที่จะถูกประมวลผลครับ/ค่ะ

หากในเวิร์กโฟลว์ที่ถูกทริกเกอร์มีโหนด "สิ้นสุดเวิร์กโฟลว์" (End workflow) ถูกดำเนินการ หรือโหนดอื่น ๆ ทำงานล้มเหลว (เช่น เกิดข้อผิดพลาดหรือไม่สามารถทำงานให้เสร็จสมบูรณ์ได้) การดำเนินการบนฟอร์มนั้นจะถูกดักจับไว้ครับ/ค่ะ มิฉะนั้น การดำเนินการที่ตั้งใจไว้จะถูกดำเนินการตามปกติ

เมื่อใช้ร่วมกับโหนด "ข้อความตอบกลับ" (Response message) คุณสามารถกำหนดค่าข้อความตอบกลับที่จะส่งกลับไปยังไคลเอนต์สำหรับเวิร์กโฟลว์นี้ได้ เพื่อให้ข้อมูลแจ้งเตือนที่เหมาะสมแก่ไคลเอนต์ครับ/ค่ะ เหตุการณ์ก่อนดำเนินการสามารถใช้สำหรับการตรวจสอบทางธุรกิจหรือการตรวจสอบตรรกะ เพื่ออนุมัติหรือดักจับคำขอการดำเนินการ เช่น การสร้าง, อัปเดต และลบ ที่ไคลเอนต์ส่งมา

#การกำหนดค่าทริกเกอร์

#การสร้างทริกเกอร์

เมื่อสร้างเวิร์กโฟลว์ ให้เลือกประเภท "เหตุการณ์ก่อนดำเนินการ" ครับ/ค่ะ

#การเลือกคอลเลกชัน

สิ่งแรกที่ต้องกำหนดค่าในทริกเกอร์ของเวิร์กโฟลว์การดักจับ คือ คอลเลกชันที่เกี่ยวข้องกับการดำเนินการนั้น ๆ ครับ/ค่ะ

จากนั้นให้เลือกโหมดการดักจับครับ/ค่ะ คุณสามารถเลือกที่จะดักจับเฉพาะปุ่มดำเนินการที่ผูกกับเวิร์กโฟลว์นี้เท่านั้น หรือจะเลือกดักจับการดำเนินการที่เลือกทั้งหมดสำหรับคอลเลกชันนี้ก็ได้ (โดยไม่คำนึงว่าจะมาจากฟอร์มใด และไม่จำเป็นต้องผูกกับเวิร์กโฟลว์ที่เกี่ยวข้อง)

#โหมดการดักจับ

ปัจจุบันประเภทการดำเนินการที่รองรับ ได้แก่ "สร้าง", "อัปเดต" และ "ลบ" ครับ/ค่ะ คุณสามารถเลือกประเภทการดำเนินการได้หลายประเภทพร้อมกัน

#การกำหนดค่าการดำเนินการ

หากคุณเลือกโหมด "ทริกเกอร์การดักจับเฉพาะเมื่อมีการส่งฟอร์มที่ผูกกับเวิร์กโฟลว์นี้" ในการกำหนดค่าทริกเกอร์ คุณจะต้องกลับไปที่หน้าจอฟอร์ม และผูกเวิร์กโฟลว์นี้เข้ากับปุ่มดำเนินการที่เกี่ยวข้องครับ/ค่ะ

ในการกำหนดค่าการผูกเวิร์กโฟลว์ ให้เลือกเวิร์กโฟลว์ที่เกี่ยวข้องครับ/ค่ะ โดยปกติแล้ว การเลือกบริบทข้อมูลสำหรับทริกเกอร์จะตั้งค่าเริ่มต้นเป็น "ข้อมูลฟอร์มทั้งหมด" ก็เพียงพอแล้ว

#เงื่อนไขสำหรับการดักจับ

ใน "เหตุการณ์ก่อนดำเนินการ" มีสองเงื่อนไขที่จะทำให้การดำเนินการที่เกี่ยวข้องถูกดักจับไว้ครับ/ค่ะ

1. เวิร์กโฟลว์ทำงานไปถึงโหนด "สิ้นสุดเวิร์กโฟลว์" ใด ๆ ครับ/ค่ะ คล้ายกับคำแนะนำการใช้งานก่อนหน้านี้ เมื่อข้อมูลที่ทริกเกอร์เวิร์กโฟลว์ไม่ตรงตามเงื่อนไขที่กำหนดไว้ล่วงหน้าในโหนด "เงื่อนไข" (Condition) ระบบจะเข้าสู่สาขา "ไม่" และดำเนินการโหนด "สิ้นสุดเวิร์กโฟลว์" ณ จุดนี้ เวิร์กโฟลว์จะสิ้นสุดลง และการดำเนินการที่ร้องขอจะถูกดักจับไว้
2. โหนดใด ๆ ในเวิร์กโฟลว์ทำงานล้มเหลวครับ/ค่ะ รวมถึงการทำงานผิดพลาดของโหนด หรือสถานการณ์ผิดปกติอื่น ๆ ณ จุดนี้ เวิร์กโฟลว์จะสิ้นสุดลงด้วยสถานะที่เกี่ยวข้อง และการดำเนินการที่ร้องขอจะถูกดักจับไว้ด้วย ตัวอย่างเช่น หากในเวิร์กโฟลว์มีการเรียกข้อมูลภายนอกผ่าน "คำขอ HTTP" (HTTP request) หากคำขอนั้นล้มเหลว เวิร์กโฟลว์จะสิ้นสุดลงด้วยสถานะล้มเหลว และจะดักจับคำขอการดำเนินการที่เกี่ยวข้องด้วย

เมื่อเงื่อนไขการดักจับเป็นไปตามที่กำหนด การดำเนินการที่เกี่ยวข้องจะไม่ถูกดำเนินการอีกต่อไปครับ/ค่ะ ตัวอย่างเช่น หากการส่งคำสั่งซื้อถูกดักจับ ข้อมูลคำสั่งซื้อที่เกี่ยวข้องจะไม่ถูกสร้างขึ้น

#พารามิเตอร์ที่เกี่ยวข้องสำหรับการดำเนินการนั้น ๆ

ในเวิร์กโฟลว์ประเภท "เหตุการณ์ก่อนดำเนินการ" สำหรับการดำเนินการที่แตกต่างกัน จะมีข้อมูลที่แตกต่างกันจากทริกเกอร์ที่สามารถใช้เป็นตัวแปรในเวิร์กโฟลว์ได้ครับ/ค่ะ

#การแสดงผลข้อความตอบกลับ

หลังจากกำหนดค่าทริกเกอร์เรียบร้อยแล้ว คุณสามารถกำหนดตรรกะการตัดสินใจที่เกี่ยวข้องในเวิร์กโฟลว์ได้เองครับ/ค่ะ โดยปกติจะใช้โหมดสาขาของโหนด "เงื่อนไข" เพื่อตัดสินใจตามเงื่อนไขทางธุรกิจที่เฉพาะเจาะจง เลือกว่าจะ "สิ้นสุดเวิร์กโฟลว์" หรือไม่ และส่งคืน "ข้อความตอบกลับ" ที่กำหนดไว้ล่วงหน้า

ณ จุดนี้ การกำหนดค่าเวิร์กโฟลว์ที่เกี่ยวข้องก็เสร็จสมบูรณ์แล้วครับ/ค่ะ และคุณสามารถลองส่งข้อมูลที่ไม่ตรงตามเงื่อนไขที่กำหนดในเวิร์กโฟลว์ เพื่อทริกเกอร์ตรรกะการดักจับของตัวดักจับ ณ จุดนี้ คุณจะเห็นข้อความตอบกลับที่ส่งคืนมา

#สถานะของข้อความตอบกลับ

หากในโหนด "สิ้นสุดเวิร์กโฟลว์" ถูกกำหนดค่าให้ออกด้วยสถานะ "สำเร็จ" และเมื่อทำงานมาถึงโหนด "สิ้นสุดเวิร์กโฟลว์" นี้ คำขอสำหรับการดำเนินการนั้นจะยังคงถูกดักจับไว้ครับ/ค่ะ แต่ข้อความตอบกลับที่ส่งคืนมาจะแสดงด้วยสถานะ "สำเร็จ" (แทนที่จะเป็น "ข้อผิดพลาด")

#ตัวอย่าง

จากคำแนะนำการใช้งานพื้นฐานข้างต้น เราจะยกตัวอย่างสถานการณ์ "การส่งคำสั่งซื้อ" ครับ/ค่ะ สมมติว่าเราต้องการตรวจสอบสต็อกสินค้าทั้งหมดที่ผู้ใช้เลือกเมื่อพวกเขาส่งคำสั่งซื้อ หากสินค้าที่เลือกชิ้นใดชิ้นหนึ่งมีสต็อกไม่เพียงพอ การส่งคำสั่งซื้อนั้นจะถูกดักจับไว้ และส่งคืนข้อความแจ้งเตือนที่เหมาะสม ระบบจะวนตรวจสอบสินค้าแต่ละรายการจนกว่าสต็อกของสินค้าทั้งหมดจะเพียงพอ จากนั้นจึงจะผ่าน และสร้างข้อมูลคำสั่งซื้อสำหรับผู้ใช้

ขั้นตอนอื่น ๆ จะเหมือนกับที่อธิบายไว้ครับ/ค่ะ แต่เนื่องจากคำสั่งซื้อหนึ่งรายการเกี่ยวข้องกับสินค้าหลายรายการ นอกจากการเพิ่มความสัมพันธ์แบบ Many-to-Many "คำสั่งซื้อ" <-- m:1 -- "รายละเอียดคำสั่งซื้อ" -- 1:m --> "สินค้า" ในการสร้างแบบจำลองข้อมูลแล้ว คุณยังต้องเพิ่มโหนด "วนซ้ำ" (Loop) ในเวิร์กโฟลว์ "เหตุการณ์ก่อนดำเนินการ" เพื่อใช้ในการวนตรวจสอบว่าสต็อกของสินค้าแต่ละรายการเพียงพอหรือไม่

อ็อบเจกต์สำหรับโหนดวนซ้ำจะถูกเลือกเป็นอาร์เรย์ "รายละเอียดคำสั่งซื้อ" จากข้อมูลคำสั่งซื้อที่ส่งมาครับ/ค่ะ

โหนดเงื่อนไขในเวิร์กโฟลว์วนซ้ำใช้เพื่อตรวจสอบว่าสต็อกของอ็อบเจกต์สินค้าปัจจุบันในลูปเพียงพอหรือไม่ครับ/ค่ะ

การกำหนดค่าอื่น ๆ จะเหมือนกับการใช้งานพื้นฐานครับ/ค่ะ เมื่อส่งคำสั่งซื้อในที่สุด หากสินค้าชิ้นใดชิ้นหนึ่งมีสต็อกไม่เพียงพอ การส่งคำสั่งซื้อจะถูกดักจับไว้ และส่งคืนข้อความแจ้งเตือนที่เหมาะสม ในการทดสอบ ลองส่งสินค้าหลายรายการในคำสั่งซื้อเดียว โดยมีสินค้าหนึ่งชิ้นสต็อกไม่เพียงพอ และอีกชิ้นสต็อกเพียงพอ คุณจะเห็นข้อความตอบกลับที่ส่งคืนมา

จะเห็นได้ว่า ในข้อความตอบกลับไม่ได้แจ้งว่าสินค้าชิ้นแรก "iPhone 15 pro" มีสต็อกไม่เพียงพอครับ/ค่ะ แต่แจ้งเฉพาะว่าสินค้าชิ้นที่สอง "iPhone 14 pro" มีสต็อกไม่เพียงพอ นี่เป็นเพราะในลูป สินค้าชิ้นแรกมีสต็อกเพียงพอ จึงไม่ถูกดักจับ ในขณะที่สินค้าชิ้นที่สองมีสต็อกไม่เพียงพอ จึงดักจับการส่งคำสั่งซื้อไว้

#การเรียกใช้งานภายนอก

เหตุการณ์ก่อนดำเนินการจะถูกแทรกเข้าไปในขั้นตอนการประมวลผลคำขอครับ/ค่ะ ดังนั้นจึงรองรับการทริกเกอร์ผ่านการเรียกใช้ HTTP API ด้วย

สำหรับเวิร์กโฟลว์ที่ผูกอยู่กับปุ่มดำเนินการเฉพาะจุด คุณสามารถเรียกใช้ได้ดังนี้ครับ/ค่ะ (ตัวอย่างเช่น ปุ่มสร้างของคอลเลกชัน posts)

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

โดยที่พารามิเตอร์ URL triggerWorkflows คือคีย์ของเวิร์กโฟลว์ครับ/ค่ะ หากมีหลายเวิร์กโฟลว์ ให้คั่นด้วยเครื่องหมายจุลภาค (comma) คุณสามารถดูคีย์นี้ได้โดยการเลื่อนเมาส์ไปวางเหนือชื่อเวิร์กโฟลว์ที่ด้านบนของผืนผ้าใบเวิร์กโฟลว์

หลังจากส่งการเรียกใช้ข้างต้น เหตุการณ์ก่อนดำเนินการสำหรับคอลเลกชัน posts ที่เกี่ยวข้องจะถูกทริกเกอร์ครับ/ค่ะ หลังจากเวิร์กโฟลว์ที่เกี่ยวข้องประมวลผลเสร็จสิ้นแบบซิงโครนัส ข้อมูลจะถูกสร้างขึ้นตามปกติและส่งคืนกลับมา

หากเวิร์กโฟลว์ที่กำหนดค่าไว้ทำงานไปถึง "โหนดสิ้นสุด" ตรรกะจะเหมือนกับการดำเนินการผ่านอินเทอร์เฟซครับ/ค่ะ คำขอจะถูกดักจับ และจะไม่มีการสร้างข้อมูล หากสถานะในโหนดสิ้นสุดถูกกำหนดค่าเป็นล้มเหลว รหัสสถานะการตอบกลับที่ส่งคืนมาจะเป็น 400 หากสำเร็จจะเป็น 200

หากมีการกำหนดค่าโหนด "ข้อความตอบกลับ" ก่อนโหนดสิ้นสุด ข้อความที่สร้างขึ้นก็จะถูกส่งคืนในผลลัพธ์การตอบกลับด้วยครับ/ค่ะ โดยโครงสร้างสำหรับกรณีเกิดข้อผิดพลาดจะเป็นดังนี้:

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

โครงสร้างข้อความเมื่อ "โหนดสิ้นสุด" ถูกกำหนดค่าเป็นสำเร็จจะเป็นดังนี้:

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

หากเหตุการณ์ก่อนดำเนินการถูกกำหนดค่าเป็นโหมด Global เมื่อเรียกใช้ HTTP API คุณไม่จำเป็นต้องใช้พารามิเตอร์ URL triggerWorkflows เพื่อระบุเวิร์กโฟลว์ที่เกี่ยวข้องครับ/ค่ะ เพียงแค่เรียกใช้การดำเนินการของคอลเลกชันที่เกี่ยวข้องก็สามารถทริกเกอร์ได้เลย

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create"