#Referensi API

#Server

API yang tersedia pada struktur paket server seperti yang ditunjukkan kode berikut:

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

#PluginWorkflowServer

Kelas plugin Workflow.

Biasanya saat runtime aplikasi, di tempat mana pun yang dapat memperoleh instance aplikasi app, panggil app.pm.get<PluginWorkflowServer>(PluginWorkflowServer) untuk mendapatkan instance plugin Workflow (di bawah ini disebut plugin).

#registerTrigger()

Memperluas pendaftaran tipe Trigger baru.

Signature

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

Parameter

Contoh

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()

Memperluas pendaftaran tipe Node baru.

Signature

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

Parameter

Contoh

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()

Memicu Workflow tertentu. Terutama digunakan dalam Trigger kustom, ketika event kustom tertentu didengarkan, memicu Workflow yang sesuai.

Signature

trigger(workflow: Workflow, context: any)

Parameter

Contoh

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()

Memulihkan eksekusi Workflow yang dijeda dengan tugas Node tertentu.

• Hanya Workflow dalam status jeda (EXECUTION_STATUS.STARTED) yang dapat dipulihkan eksekusinya.
• Hanya tugas Node dalam status jeda (JOB_STATUS.PENDING) yang dapat dipulihkan eksekusinya.

Signature

resume(job: JobModel)

Parameter

Contoh

Lihat detailnya di source code.

#Trigger

Kelas dasar Trigger, digunakan untuk memperluas tipe Trigger kustom.

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

on/off digunakan untuk pendaftaran/pencabutan listener event saat Workflow diaktifkan/dinonaktifkan, parameter yang diteruskan adalah instance Workflow dari Trigger yang sesuai, dapat ditangani sesuai konfigurasi yang sesuai. Beberapa tipe Trigger jika sudah men-listen event secara global, juga tidak perlu mengimplementasikan kedua method ini. Misalnya pada Trigger terjadwal, Anda dapat mendaftarkan timer di on, dan mencabut timer di off.

#Instruction

Kelas dasar tipe instruksi, digunakan untuk memperluas tipe instruksi kustom.

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

Tipe Terkait

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 dapat dirujuk pada implementasi Node loop, digunakan untuk menyediakan konten variabel lokal cabang.

#EXECUTION_STATUS

Tabel konstanta status rencana eksekusi Workflow, digunakan untuk mengidentifikasi status saat ini dari rencana eksekusi yang sesuai.

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

Selain tiga yang pertama, lainnya merepresentasikan status gagal, tetapi dapat digunakan untuk mengekspresikan alasan kegagalan yang berbeda.

#JOB_STATUS

Tabel konstanta status tugas Node Workflow, digunakan untuk mengidentifikasi status saat ini dari tugas Node yang sesuai. Status yang dihasilkan Node juga akan memengaruhi status seluruh rencana eksekusi.

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

#Client

API yang tersedia pada struktur paket client seperti yang ditunjukkan kode berikut:

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

#PluginWorkflowClientV2

Kelas plugin Workflow client. Biasanya diperoleh melalui this.app.pm.get('workflow').

#registerTrigger()

Mendaftarkan panel konfigurasi yang sesuai dengan tipe Trigger.

Signature

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

Parameter

#registerInstruction()

Mendaftarkan panel konfigurasi yang sesuai dengan tipe Node.

Signature

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

Parameter

#registerInstructionGroup()

Mendaftarkan grup tipe Node. NocoBase secara default menyediakan 4 grup tipe Node:

• 'control': Kontrol
• 'collection': Operasi tabel data
• 'manual': Penanganan manual
• 'extended': Ekstensi lainnya

Jika perlu memperluas grup lain, Anda dapat menggunakan method ini untuk mendaftarkan.

Signature

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

Parameter

Contoh

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()

Menentukan apakah sebuah Workflow dalam mode sinkron.

Signature

isWorkflowSync(workflow: object): boolean

#Trigger

Kelas dasar Trigger, digunakan untuk memperluas tipe Trigger kustom.

Tipe Terkait

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

• Jika useVariables tidak diatur, artinya tipe Trigger ini tidak menyediakan fungsi pengambilan nilai, dan data konteks Trigger tidak dapat dipilih di Node workflow.

#Instruction

Kelas dasar instruksi, digunakan untuk memperluas tipe Node kustom.

Tipe Terkait

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

• Jika useVariables tidak diatur, artinya tipe Node ini tidak menyediakan fungsi pengambilan nilai, dan data hasil tipe Node ini tidak dapat dipilih di Node workflow. Jika nilai hasil tunggal (tidak dapat dipilih), maka cukup mengembalikan konten statis yang dapat mengekspresikan informasi yang sesuai (lihat: source code Node komputasi). Jika perlu dapat dipilih (seperti suatu properti dalam Object), Anda dapat menyesuaikan output komponen pemilihan yang sesuai (lihat: source code Node query data).
• ComponentLoader adalah komponen rendering kustom Node. Saat rendering Node default tidak mencukupi, dapat sepenuhnya di-override untuk rendering tampilan Node kustom. Misalnya untuk menyediakan rendering cabang tambahan pada Node tipe cabang (lihat: source code Node kondisi).
• isAvailable terutama digunakan untuk menentukan apakah Node dapat digunakan (ditambahkan) di lingkungan saat ini. Lingkungan saat ini termasuk instance plugin Workflow, Workflow saat ini, Node upstream, dan indeks cabang saat ini.

#Komponen Input Variable

Plugin Workflow menyediakan sekumpulan komponen input variable untuk memungkinkan pengguna memilih variable workflow di form konfigurasi Node/Trigger.

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

#WorkflowVariableInput

Input variable yang mendukung pemilihan variable dan melanjutkan mengetik konten. Cocok untuk skenario input satu baris yang membutuhkan campuran referensi variable dan teks bebas.

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

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

Props

#WorkflowVariableTextArea

Area teks multi-baris yang mendukung penyisipan referensi variable di posisi kursor mana pun. Cocok untuk skenario teks bebas seperti HTTP Body, teks template, dll.

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

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

Props

Mewarisi Props lain dari antd TextArea (seperti autoSize, placeholder, dll.).

#WorkflowTypedVariableInput

Input bertipe yang beralih antara mode "konstanta" dan "referensi variable". Dalam mode variable, hanya dapat memilih variable; tidak dapat melanjutkan mengetik setelah pemilihan. Dalam mode konstanta, lima tipe didukung: string, number, boolean, date, dan object.

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

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

Props

Mewarisi Props lain dari TypedVariableInput (tidak termasuk extraNodes, metaTree, namespaces yang digunakan secara internal).

#WorkflowVariableWrapper

Wrapper generik untuk mengganti komponen input berbeda dalam konteks berbeda. Misalnya saat field yang sama memerlukan metode input berbeda di konfigurasi Node Trigger dan drawer konfigurasi Node, Anda dapat menggunakan komponen ini untuk membungkus input native menjadi input yang dapat beralih ke mode variable.

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

#Komponen Terkait Collection

Plugin Workflow juga menyediakan sekumpulan komponen helper terkait collection:

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

• CollectionCascader — Pemilih collection yang aware terhadap data source (cascader)
• AppendsSelect — Pemilih preloading field asosiasi (tree select)
• FieldsSelect — Pemilih multi field collection
• SortFieldsInput — Input field pengurutan
• PaginationFields — Item form parameter paginasi