#Tham chiếu API

#Phía Server

Các API có sẵn trong cấu trúc package phía server như đoạn code dưới đây:

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

#PluginWorkflowServer

Class plugin Workflow.

Thông thường khi ứng dụng đang chạy, ở bất kỳ nơi nào có thể lấy được instance ứng dụng app thì đều có thể gọi app.pm.get<PluginWorkflowServer>(PluginWorkflowServer) để lấy instance plugin Workflow (dưới đây gọi là plugin).

#registerTrigger()

Mở rộng đăng ký loại Trigger mới.

Chữ ký

registerTrigger(type: string, trigger: typeof Trigger | Trigger })

Tham số

Ví dụ

import PluginWorkflowServer, { Trigger } from '@nocobase/plugin-workflow';

function handler(this: MyTrigger, workflow: WorkflowModel, message: string) {
  // trigger workflow
  this.workflow.trigger(workflow, { data: message.data });
}

class MyTrigger extends Trigger {
  messageHandlers: Map<number, WorkflowModel> = new Map();
  on(workflow: WorkflowModel) {
    const messageHandler = handler.bind(this, workflow);
    // listen some event to trigger workflow
    process.on(
      'message',
      this.messageHandlers.set(workflow.id, messageHandler),
    );
  }

  off(workflow: WorkflowModel) {
    const messageHandler = this.messageHandlers.get(workflow.id);
    // remove listener
    process.off('message', messageHandler);
  }
}

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

    // register trigger
    workflowPlugin.registerTrigger('myTrigger', MyTrigger);
  }
}

#registerInstruction()

Mở rộng đăng ký loại Node mới.

Chữ ký

registerInstruction(type: string, instruction: typeof Instruction | Instruction })

Tham số

Ví dụ

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

class LogInstruction 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.pm.get<PluginWorkflowServer>(PluginWorkflowServer);

    // register instruction
    workflowPlugin.registerInstruction('log', LogInstruction);
  }
}

#trigger()

Kích hoạt Workflow cụ thể. Chủ yếu dùng trong Trigger tùy chỉnh, để kích hoạt Workflow tương ứng khi nghe được sự kiện tùy chỉnh nào đó.

Chữ ký

trigger(workflow: Workflow, context: any)

Tham số

Ví dụ

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

class MyTrigger extends Trigger {
  timer: NodeJS.Timeout;

  on(workflow) {
    // register event
    this.timer = setInterval(() => {
      // trigger workflow
      this.plugin.trigger(workflow, { date: new Date() });
    }, workflow.config.interval ?? 60000);
  }
}

#resume()

Khôi phục thực thi Workflow đang chờ với một Task Node cụ thể.

• Chỉ có Workflow đang ở trạng thái chờ (EXECUTION_STATUS.STARTED) mới có thể được khôi phục thực thi.
• Chỉ có Task Node đang ở trạng thái chờ (JOB_STATUS.PENDING) mới có thể được khôi phục thực thi.

Chữ ký

resume(job: JobModel)

Tham số

Ví dụ

Xem chi tiết tại mã nguồn.

#Trigger

Class cơ sở của Trigger, dùng để mở rộng loại Trigger tùy chỉnh.

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

on/off được dùng để đăng ký/hủy đăng ký lắng nghe sự kiện khi Workflow được bật/tắt, tham số được truyền vào là instance Workflow của Trigger tương ứng, có thể xử lý theo cấu hình tương ứng. Một số loại Trigger nếu đã lắng nghe sự kiện ở phạm vi toàn cục thì cũng có thể không cần triển khai hai phương thức này. Ví dụ trong Trigger định kỳ, có thể đăng ký timer trong on, hủy đăng ký timer trong off.

#Instruction

Class cơ sở của loại Instruction, dùng để mở rộng loại Instruction tùy chỉnh.

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

Kiểu liên quan

export type Job =
  | {
      status: JOB_STATUS[keyof JOB_STATUS];
      result?: unknown;
      [key: string]: unknown;
    }
  | JobModel
  | null;

export type InstructionResult = Job | Promise<Job>;

export type Runner = (
  node: FlowNodeModel,
  input: JobModel,
  processor: Processor,
) => InstructionResult;

export class Instruction {
  run: Runner;
  resume?: Runner;
}

getScope có thể tham khảo cách triển khai Node vòng lặp, được dùng để cung cấp nội dung biến cục bộ của nhánh.

#EXECUTION_STATUS

Bảng hằng số trạng thái kế hoạch thực thi Workflow, dùng để xác định trạng thái hiện tại của kế hoạch thực thi tương ứng.

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

Ngoài ba trạng thái đầu, các trạng thái còn lại đều biểu thị trạng thái thất bại nhưng có thể dùng để mô tả các nguyên nhân thất bại khác nhau.

#JOB_STATUS

Bảng hằng số trạng thái Task Node của Workflow, dùng để xác định trạng thái hiện tại của Task Node tương ứng, trạng thái sinh ra bởi Node cũng đồng thời ảnh hưởng đến trạng thái của toàn bộ kế hoạch thực thi.

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

#Phía Client

Các API có sẵn trong cấu trúc package phía client như đoạn code dưới đây:

import PluginWorkflowClientV2, {
  Trigger,
  Instruction,
} from '@nocobase/plugin-workflow/client-v2';

#PluginWorkflowClientV2

Class plugin Workflow phía client. Thường được lấy thông qua this.app.pm.get('workflow').

#registerTrigger()

Đăng ký panel cấu hình tương ứng với loại Trigger.

Chữ ký

registerTrigger(type: string, trigger: typeof Trigger | Trigger): void

Tham số

#registerInstruction()

Đăng ký panel cấu hình tương ứng với loại Node.

Chữ ký

registerInstruction(type: string, instruction: typeof Instruction | Instruction): void

Tham số

#registerInstructionGroup()

Đăng ký nhóm loại Node. NocoBase mặc định cung cấp 4 nhóm loại Node:

• 'control': nhóm điều khiển
• 'collection': nhóm thao tác bảng dữ liệu
• 'manual': nhóm xử lý thủ công
• 'extended': nhóm mở rộng khác

Nếu cần mở rộng thêm nhóm khác, có thể sử dụng phương thức này để đăng ký.

Chữ ký

registerInstructionGroup(type: string, group: { label: string }): void

Tham số

Ví dụ

import { Plugin } from '@nocobase/client-v2';

export default class YourPluginClient extends Plugin {
  async load() {
    const pluginWorkflow = this.app.pm.get('workflow');
    pluginWorkflow.registerInstructionGroup('ai', { label: `{{t("AI", { ns: "${NAMESPACE}" })}}` });
  }
}

#isWorkflowSync()

Kiểm tra Workflow có đang ở chế độ đồng bộ hay không.

Chữ ký

isWorkflowSync(workflow: object): boolean

#Trigger

Class cơ sở của Trigger, dùng để mở rộng loại Trigger tùy chỉnh.

Kiểu liên quan

export type LoaderOf<P = {}> = () => Promise<{ default: ComponentType<P> }>;

• Nếu useVariables không được thiết lập, có nghĩa loại Trigger này không cung cấp khả năng lấy giá trị, các Node trong quy trình không thể chọn dữ liệu ngữ cảnh của Trigger.

#Instruction

Class cơ sở của Instruction, dùng để mở rộng loại Node tùy chỉnh.

Kiểu liên quan

export type NodeAvailableContext = {
  engine: WorkflowPlugin;
  workflow: object;
  upstream: object;
  branchIndex: number;
};

• Nếu useVariables không được thiết lập, có nghĩa loại Node này không cung cấp khả năng lấy giá trị, các Node trong quy trình không thể chọn dữ liệu kết quả của loại Node này. Nếu giá trị kết quả là duy nhất (không thể chọn), chỉ cần trả về một nội dung tĩnh có thể biểu thị thông tin tương ứng (tham khảo: mã nguồn Node tính toán). Nếu cần có thể chọn (như một thuộc tính trong Object), có thể tự định nghĩa Component chọn tương ứng để xuất ra (tham khảo: mã nguồn Node truy vấn dữ liệu).
• ComponentLoader là Component render tùy chỉnh của Node. Khi việc render Node mặc định không đủ, có thể hoàn toàn ghi đè để render view tùy chỉnh cho Node. Ví dụ để cung cấp thêm render nhánh cho các Node loại nhánh (tham khảo: mã nguồn Node điều kiện).
• isAvailable chủ yếu được dùng để kiểm tra Node có thể được sử dụng (thêm vào) trong môi trường hiện tại hay không. Môi trường hiện tại bao gồm instance plugin Workflow, Workflow hiện tại, Node phía trên và chỉ số nhánh hiện tại.

#Component nhập biến

Workflow cung cấp một bộ component nhập biến để người dùng chọn biến Workflow trong form cấu hình Node/Trigger.

import {
  WorkflowVariableInput,
  WorkflowVariableTextArea,
  WorkflowTypedVariableInput,
  WorkflowVariableWrapper,
} from '@nocobase/plugin-workflow/client-v2';

#WorkflowVariableInput

Ô nhập biến hỗ trợ chọn biến và tiếp tục nhập nội dung. Phù hợp cho các tình huống nhập một dòng cần kết hợp tham chiếu biến và văn bản tự do.

import { WorkflowVariableInput } from '@nocobase/plugin-workflow/client-v2';

<Form.Item name={['config', 'target']} label="Target">
  <WorkflowVariableInput />
</Form.Item>

Props

#WorkflowVariableTextArea

Vùng nhập văn bản nhiều dòng hỗ trợ chèn tham chiếu biến tại bất kỳ vị trí con trỏ nào. Phù hợp cho các tình huống văn bản tự do như HTTP Body, văn bản template...

import { WorkflowVariableTextArea } from '@nocobase/plugin-workflow/client-v2';

<Form.Item name={['config', 'body']} label="Body">
  <WorkflowVariableTextArea autoSize={{ minRows: 5 }} />
</Form.Item>

Props

Kế thừa các Props khác từ antd TextArea (như autoSize, placeholder...).

#WorkflowTypedVariableInput

Ô nhập có kiểu, chuyển đổi giữa chế độ "hằng số" và "tham chiếu biến". Ở chế độ biến, chỉ có thể chọn biến, không thể tiếp tục nhập sau khi chọn. Ở chế độ hằng số, hỗ trợ năm kiểu: string, number, boolean, date và object.

import { WorkflowTypedVariableInput } from '@nocobase/plugin-workflow/client-v2';

<Form.Item name={['config', 'value']} label="Value">
  <WorkflowTypedVariableInput />
</Form.Item>

Props

Kế thừa các Props khác từ TypedVariableInput (ngoại trừ extraNodes, metaTree, namespaces được sử dụng nội bộ).

#WorkflowVariableWrapper

Component bọc tổng quát để thay thế các component nhập khác nhau trong các ngữ cảnh khác nhau. Ví dụ khi cùng một trường cần phương thức nhập khác nhau trong cấu hình Node Trigger và drawer cấu hình Node, có thể sử dụng component này để bọc ô nhập native thành ô nhập có thể chuyển đổi chế độ biến.

import { WorkflowVariableWrapper } from '@nocobase/plugin-workflow/client-v2';

<Form.Item name={['config', 'timeout']} label="Timeout">
  <WorkflowVariableWrapper
    render={({ value, onChange }) => (
      <InputNumber value={value} onChange={onChange} min={0} />
    )}
  />
</Form.Item>

Props

#Component liên quan đến bảng dữ liệu

Workflow cũng cung cấp một bộ component trợ giúp liên quan đến bảng dữ liệu:

import {
  CollectionCascader,
  AppendsSelect,
  FieldsSelect,
  SortFieldsInput,
  PaginationFields,
} from '@nocobase/plugin-workflow/client-v2';

• CollectionCascader — Bộ chọn bảng dữ liệu hỗ trợ nguồn dữ liệu (cascader)
• AppendsSelect — Bộ chọn tải trước trường liên kết (tree select)
• FieldsSelect — Bộ chọn nhiều trường của bảng dữ liệu
• SortFieldsInput — Ô nhập trường sắp xếp
• PaginationFields — Các mục form tham số phân trang