#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.

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.

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.

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.

#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 PluginWorkflowClient, {
  Trigger,
  Instruction,
} from '@nocobase/plugin-workflow/client';

#PluginWorkflowClient

#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ụ

export default class YourPluginClient extends Plugin {
  load() {
    const pluginWorkflow = this.app.pm.get(PluginWorkflowClient);

    pluginWorkflow.registerInstructionGroup('ai', { label: `{{t("AI", { ns: "${NAMESPACE}" })}}` });
  }
}

#Trigger

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

• 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 = {
  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 thêm dữ liệu).
• Component là Component render tùy chỉnh của Node, khi việc render Node mặc định không thỏa mãn thì có thể hoàn toàn ghi đè để sử dụng, thực hiện render view tùy chỉnh cho Node. Ví dụ nếu cần cung cấp thêm các nút thao tác hoặc tương tác khác cho Node bắt đầu của loại nhánh, cần sử dụng phương thức này (tham khảo: mã nguồn nhánh song song).
• useInitializers được dùng để cung cấp phương thức initializer Block, ví dụ trong Node thủ công có thể khởi tạo Block người dùng liên quan dựa trên Node phía trên. Nếu cung cấp phương thức này, sẽ khả dụng khi initializer Block trong cấu hình giao diện Node thủ công (tham khảo: mã nguồn Node thêm dữ liệu).
• 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 Workflow hiện tại, Node phía trên và chỉ số nhánh hiện tại...