#Справочник 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) {
  // запуск рабочего процесса
  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);
    // подписка на событие для запуска рабочего процесса
    process.on(
      'message',
      this.messageHandlers.set(workflow.id, messageHandler),
    );
  }

  off(workflow: WorkflowModel) {
    const messageHandler = this.messageHandlers.get(workflow.id);
    // отмена подписки
    process.off('message', messageHandler);
  }
}

export default class MyPlugin extends Plugin {
  load() {
    // получение экземпляра плагина рабочего процесса
    const workflowPlugin =
      this.app.pm.get<PluginWorkflowServer>(PluginWorkflowServer);

    // регистрация триггера
    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() {
    // получение экземпляра плагина рабочего процесса
    const workflowPlugin = this.app.pm.get<PluginWorkflowServer>(PluginWorkflowServer);

    // регистрация инструкции
    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) {
    // регистрация события
    this.timer = setInterval(() => {
      // запуск рабочего процесса
      this.plugin.trigger(workflow, { date: new Date() });
    }, workflow.config.interval ?? 60000);
  }
}

#resume()

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

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

Сигнатура

resume(job: JobModel)

Параметры

Пример

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

#Trigger

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

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

#Instruction

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

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

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

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

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

#JOB_STATUS

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

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

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

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

#PluginWorkflowClient

#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

Параметры

Пример

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

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

#Trigger

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

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

#Instruction

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

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

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

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