#การขยายประเภทของโหนด

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

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

#ฝั่งเซิร์ฟเวอร์

#คำสั่งโหนดที่ง่ายที่สุด

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

คำสั่งทั้งหมดจะต้องสืบทอดมาจากคลาสพื้นฐาน Instruction โดยคำสั่งที่ง่ายที่สุดเพียงแค่ต้องนำฟังก์ชัน run ไปใช้งานเท่านั้นครับ/ค่ะ

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class MyInstruction extends Instruction {
  run(node, input, processor) {
    console.log('my instruction runs!');
    return {
      status: JOB_STATUS.RESOVLED,
    };
  }
}

และลงทะเบียนคำสั่งนี้กับปลั๊กอิน เวิร์กโฟลว์ ครับ/ค่ะ

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin = this.app.getPlugin<WorkflowPlugin>(WorkflowPlugin);

    // register instruction
    workflowPlugin.registerInstruction('my-instruction', MyInstruction);
  }
}

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

#ค่าผลลัพธ์ของโหนด

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

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class RandomStringInstruction extends Instruction {
  run(node, input, processor) {
    // customized config from node
    const { digit = 1 } = node.config;
    const result = `${Math.round(10 ** digit * Math.random())}`.padStart(
      digit,
      '0',
    );
    return {
      status: JOB_STATUS.RESOVLED,
      result,
    };
  },
};

ในที่นี้ node.config คือรายการการกำหนดค่าของโหนด ซึ่งสามารถเป็นค่าใด ๆ ที่ต้องการได้ครับ/ค่ะ โดยจะถูกบันทึกเป็นฟิลด์ประเภท JSON ในบันทึกโหนดที่เกี่ยวข้องในฐานข้อมูล

#การจัดการข้อผิดพลาดของคำสั่ง

หากอาจเกิดข้อยกเว้นระหว่างการดำเนินการ คุณสามารถดักจับล่วงหน้าและส่งคืนสถานะความล้มเหลวได้ครับ/ค่ะ

import { JOB_STATUS } from '@nocobase/plugin-workflow';

export const errorInstruction = {
  run(node, input, processor) {
    try {
      throw new Error('exception');
    } catch (error) {
      return {
        status: JOB_STATUS.ERROR,
        result: error,
      };
    }
  },
};

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

#โหนดแบบอะซิงโครนัส

เมื่อจำเป็นต้องมีการควบคุมการไหลของงาน หรือการดำเนินการ I/O แบบอะซิงโครนัส (ที่ใช้เวลานาน) เมธอด run สามารถส่งคืนออบเจกต์ที่มี status เป็น JOB_STATUS.PENDING เพื่อแจ้งให้ตัวดำเนินการรอ (ระงับ) จนกว่าการดำเนินการอะซิงโครนัสภายนอกบางอย่างจะเสร็จสิ้น จากนั้นจึงแจ้งให้เอ็นจิ้น เวิร์กโฟลว์ ดำเนินการต่อครับ/ค่ะ หากมีการส่งคืนค่าสถานะที่ถูกระงับในฟังก์ชัน run คำสั่งนั้นจะต้องนำเมธอด resume ไปใช้งาน มิฉะนั้นจะไม่สามารถดำเนินการ เวิร์กโฟลว์ ต่อไปได้ครับ/ค่ะ

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class PayInstruction extends Instruction {
  async run(node, input, processor) {
    // job could be create first via processor
    const job = await processor.saveJob({
      status: JOB_STATUS.PENDING,
    });

    const { workflow } = processor;
    // do payment asynchronously
    paymentService.pay(node.config, (result) => {
      // notify processor to resume the job
      return workflow.resume(job.id, result);
    });

    // return created job instance
    return job;
  }

  resume(node, job, processor) {
    // check payment status
    job.set('status', job.result.status === 'ok' ? JOB_STATUS.RESOVLED : JOB_STATUS.REJECTED);
    return job;
  },
};

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

#สถานะผลลัพธ์ของโหนด

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

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

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

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

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

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

สำหรับสถานะการส่งคืนคำสั่งเพิ่มเติม สามารถดูได้จากส่วนอ้างอิง Workflow API ครับ/ค่ะ

#การออกก่อนกำหนด

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

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

:::warn{title=ข้อควรระวัง} การจัดกำหนดการ เวิร์กโฟลว์ สาขาด้วยโหนดที่ขยายมีความซับซ้อนบางอย่าง จึงต้องจัดการอย่างระมัดระวังและทำการทดสอบอย่างละเอียดครับ/ค่ะ :::

#เรียนรู้เพิ่มเติม

สำหรับคำจำกัดความของพารามิเตอร์ต่าง ๆ ในการกำหนดประเภทโหนด โปรดดูส่วนอ้างอิง Workflow API ครับ/ค่ะ

#ฝั่งไคลเอนต์

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

#คำสั่งโหนดที่ง่ายที่สุด

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

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

import WorkflowPlugin, { Instruction, VariableOption } from '@nocobase/workflow/client';

class MyInstruction extends Instruction {
  title = 'Random number string';
  type = 'randomString';
  group = 'extended';
  fieldset = {
    'digit': {
      type: 'number',
      title: 'Digit',
      name: 'digit',
      'x-decorator': 'FormItem',
      'x-component': 'InputNumber',
      'x-component-props': {
        min: 1,
        max: 10,
      },
      default: 6,
    },
  };
  useVariables(node, options): VariableOption {
    return {
      value: node.key,
      label: node.title,
    };
  }
}

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin = this.app.getPlugin<WorkflowPlugin>(WorkflowPlugin);

    // register instruction
    workflowPlugin.registerInstruction('randomString', MyInstruction);
  }
}

#การจัดเตรียมผลลัพธ์ของโหนดเป็นตัวแปร

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

โดยประเภท VariableOption ถูกกำหนดไว้ดังนี้ครับ/ค่ะ

export type VariableOption = {
  value?: string;
  label?: string;
  children?: VariableOption[] | null;
  [key: string]: any;
};

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

ตัวแปรที่ใช้งานได้จะถูกแสดงภายในระบบเป็นสตริงเทมเพลตพาธที่คั่นด้วย . ตัวอย่างเช่น {{jobsMapByNodeKey.2dw92cdf.abc}} ครับ/ค่ะ โดยที่ $jobsMapByNodeKey แสดงถึงชุดผลลัพธ์ของโหนดทั้งหมด (ถูกกำหนดไว้ภายใน ไม่จำเป็นต้องจัดการ) 2dw92cdf คือ key ของโหนด และ abc คือคุณสมบัติที่กำหนดเองบางอย่างในออบเจกต์ผลลัพธ์ของโหนด

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

{
  value: node.key,
  label: node.title,
}

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

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

{
  "message": "ok",
  "data": {
    "id": 1,
    "name": "test",
  }
}

จากนั้นคุณสามารถส่งคืนได้ผ่านเมธอด useVariables ดังนี้ครับ/ค่ะ

useVariables(node, options): VariableOption {
  return {
    value: node.key,
    label: node.title,
    children: [
      {
        value: 'message',
        label: 'Message',
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'id',
            label: 'ID',
          },
          {
            value: 'name',
            label: 'Name',
          },
        ],
      },
    ],
  };
}

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

#โหนดพร้อมใช้งานหรือไม่

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

// Type definition
export abstract class Instruction {
  isAvailable?(ctx: NodeAvailableContext): boolean;
}

export type NodeAvailableContext = {
  // Workflow plugin instance
  engine: WorkflowPlugin;
  // Workflow instance
  workflow: object;
  // Upstream node
  upstream: object;
  // Whether it is a branch node (branch number)
  branchIndex: number;
};

เมธอด isAvailable จะส่งคืน true หากโหนดพร้อมใช้งาน และ false หากไม่พร้อมใช้งานครับ/ค่ะ พารามิเตอร์ ctx มีข้อมูลบริบทของโหนดปัจจุบัน ซึ่งสามารถใช้เพื่อพิจารณาว่าโหนดพร้อมใช้งานหรือไม่

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

isAvailable({ engine, workflow, upstream, branchIndex }) {
  return !engine.isWorkflowSync(workflow);
}

#เรียนรู้เพิ่มเติม

สำหรับคำจำกัดความของพารามิเตอร์ต่าง ๆ ในการกำหนดประเภทโหนด โปรดดูส่วนอ้างอิง Workflow API ครับ/ค่ะ