#Справочник API

#Серверная часть

API, доступные в серверной части пакета, показаны в следующем коде:

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

#PluginWorkflowServer

Класс плагина рабочего процесса.

Обычно во время выполнения приложения в любом месте, где доступен экземпляр приложения app, можно вызвать app.pm.get<PluginWorkflowServer>(PluginWorkflowServer), чтобы получить экземпляр плагина рабочего процесса (ниже — plugin).

#registerTrigger()

Расширяет и регистрирует новый тип триггера.

Сигнатура

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

Параметры

Пример

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

Расширяет и регистрирует новый тип узла.

Сигнатура

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

Параметры

Пример

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

Запускает конкретный рабочий процесс. В основном используется в пользовательских триггерах, чтобы запускать соответствующий рабочий процесс при срабатывании определённого пользовательского события.

Сигнатура

trigger(workflow: Workflow, context: any)

Параметры

Пример

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

Возобновляет ожидающий рабочий процесс по конкретной задаче узла.

• Возобновить можно только рабочий процесс в состоянии ожидания (EXECUTION_STATUS.STARTED).
• Возобновить можно только задачу узла в состоянии ожидания (JOB_STATUS.PENDING).

Сигнатура

resume(job: JobModel)

Параметры

Пример

Подробности см. в исходном коде.

#Trigger

Базовый класс триггера, используется для расширения пользовательских типов триггеров.

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

on/off используются для регистрации и снятия обработчиков событий при включении и отключении рабочего процесса. Передаваемый параметр — экземпляр рабочего процесса, соответствующий триггеру, который можно обрабатывать в соответствии с конфигурацией. Некоторым типам триггеров с уже глобально прослушиваемыми событиями эти методы могут быть не нужны. Например, в триггере по расписанию можно зарегистрировать таймер в on и снять его в off.

#Instruction

Базовый класс типов инструкций, используется для расширения пользовательских инструкций.

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

Связанные типы

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 можно ориентироваться на реализацию узла «Цикл», которая используется для предоставления локальных переменных для ветвей.

#EXECUTION_STATUS

Таблица констант статусов плана выполнения рабочего процесса, используется для идентификации текущего состояния соответствующего плана выполнения.

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

Кроме первых трёх, все остальные представляют неуспешное состояние, но используются для описания разных причин неуспеха.

#JOB_STATUS

Таблица констант статусов задач узлов в рабочем процессе, используется для идентификации текущего состояния соответствующей задачи узла. Статус, сформированный узлом, также влияет на статус всего плана выполнения.

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

#Клиентская часть

API, доступные в клиентской части пакета, показаны в следующем коде:

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

#PluginWorkflowClientV2

Класс клиентского плагина рабочего процесса. Обычно получается через this.app.pm.get('workflow').

#registerTrigger()

Регистрирует панель настройки для типа триггера.

Сигнатура

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

Параметры

#registerInstruction()

Регистрирует панель настройки для типа узла.

Сигнатура

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

Параметры

#registerInstructionGroup()

Регистрирует группу типов узлов. В NocoBase есть 4 группы по умолчанию:

• 'control': управление
• 'collection': операции с коллекциями
• 'manual': ручная обработка
• 'extended': прочие расширения

Если нужно добавить другие группы, используйте этот метод для их регистрации.

Сигнатура

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

Параметры

Пример

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

Определяет, находится ли рабочий процесс в синхронном режиме.

Сигнатура

isWorkflowSync(workflow: object): boolean

#Trigger

Базовый класс триггера, используется для расширения пользовательских типов триггеров.

Связанные типы

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

• Если useVariables не задан, этот тип триггера не предоставляет функцию получения значений, и контекстные данные триггера нельзя выбрать в узлах рабочего процесса.

#Instruction

Базовый класс инструкций, используется для расширения пользовательских типов узлов.

Связанные типы

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

• Если useVariables не задан, этот тип узла не предоставляет функцию получения значений, и данные результата такого узла нельзя выбрать в узлах рабочего процесса. Если результат единственный (не выбирается), можно вернуть статическое содержимое с нужной информацией (см.: исходный код узла «Вычисление»). Если значение нужно выбирать (например, свойство объекта), можно настроить соответствующий компонент выбора (см.: исходный код узла «Запрос данных»).
• ComponentLoader — пользовательский компонент отображения узла. Если стандартного отображения недостаточно, его можно полностью переопределить для пользовательского рендеринга узла. Например, для узлов ветвящегося типа можно добавить дополнительный рендеринг ветвей (см.: исходный код узла «Условие»).
• isAvailable в основном определяет, можно ли использовать (добавить) узел в текущем окружении. Текущее окружение включает экземпляр плагина рабочего процесса, текущий рабочий процесс, вышестоящие узлы и индекс текущей ветви.

#Компоненты ввода переменных

Рабочий процесс предоставляет набор компонентов ввода переменных, позволяющих пользователям выбирать переменные рабочего процесса в формах настройки узлов и триггеров.

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

#WorkflowVariableInput

Поле ввода переменной с поддержкой выбора переменной и продолжения ввода текста. Подходит для однострочных сценариев, требующих сочетания ссылок на переменные и произвольного текста.

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

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

Свойства

#WorkflowVariableTextArea

Многострочное текстовое поле с поддержкой вставки ссылок на переменные в любую позицию курсора. Подходит для сценариев произвольного текста, таких как тело HTTP-запроса, шаблонный текст и т.д.

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

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

Свойства

Наследует остальные свойства от TextArea из antd (такие как autoSize, placeholder и т.д.).

#WorkflowTypedVariableInput

Типизированный ввод с переключением между режимами «константа» и «ссылка на переменную». В режиме переменной можно только выбрать переменную; продолжение ввода после выбора недоступно. В режиме константы поддерживаются пять типов: string, number, boolean, date и object.

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

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

Свойства

Наследует остальные свойства от TypedVariableInput (за исключением внутренних extraNodes, metaTree, namespaces).

#WorkflowVariableWrapper

Универсальная обёртка для подстановки различных компонентов ввода в различных контекстах. Например, когда одно и то же поле требует разных способов ввода в конфигурации триггера и в панели настройки узла, можно использовать этот компонент для оборачивания нативного элемента ввода в элемент с переключением режима переменной.

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>

Свойства

#Компоненты, связанные с коллекциями

Рабочий процесс также предоставляет набор вспомогательных компонентов, связанных с коллекциями:

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

• CollectionCascader — каскадный селектор коллекций с поддержкой источников данных
• AppendsSelect — селектор предзагрузки связанных полей (древовидный выбор)
• FieldsSelect — мультиселектор полей коллекции
• SortFieldsInput — поле ввода для сортировки
• PaginationFields — элементы формы для параметров пагинации