#Referencia de la API

#Lado del servidor

Las APIs disponibles en la estructura del paquete del lado del servidor se muestran en el siguiente código:

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

#PluginWorkflowServer

Clase del plugin de flujo de trabajo.

Normalmente, durante la ejecución de la aplicación, puede obtener la instancia del plugin de flujo de trabajo (referida como plugin a continuación) llamando a app.pm.get<PluginWorkflowServer>(PluginWorkflowServer) desde cualquier lugar donde pueda acceder a la instancia de la aplicación app.

#registerTrigger()

Permite extender y registrar un nuevo tipo de disparador.

Firma

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

Parámetros

Ejemplo

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

Permite extender y registrar un nuevo tipo de nodo.

Firma

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

Parámetros

Ejemplo

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

Dispara un flujo de trabajo específico. Se utiliza principalmente en disparadores personalizados para activar el flujo de trabajo correspondiente cuando se detecta un evento personalizado específico.

Firma

trigger(workflow: Workflow, context: any)

Parámetros

Ejemplo

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

Reanuda la ejecución de un flujo de trabajo en espera con una tarea de nodo específica.

• Solo los flujos de trabajo en estado de espera (EXECUTION_STATUS.STARTED) pueden reanudarse.
• Solo las tareas de nodo en estado pendiente (JOB_STATUS.PENDING) pueden reanudarse.

Firma

resume(job: JobModel)

Parámetros

Ejemplo

Consulte el código fuente para más detalles.

#Trigger

Clase base para disparadores, utilizada para extender tipos de disparadores personalizados.

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

on/off se utilizan para registrar/desregistrar oyentes de eventos cuando un flujo de trabajo se habilita/deshabilita. El parámetro pasado es la instancia del flujo de trabajo correspondiente al disparador, que puede procesarse según la configuración. Algunos tipos de disparadores que ya tienen eventos escuchados globalmente pueden no necesitar implementar estos dos métodos. Por ejemplo, en un disparador programado, puede registrar un temporizador en on y desregistrarlo en off.

#Instruction

Clase base para tipos de instrucción, utilizada para extender tipos de instrucción personalizados.

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

Tipos relacionados

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;
}

Para getScope, puede consultar la implementación del nodo de bucle, que se utiliza para proporcionar contenido de variables locales para las ramas.

#EXECUTION_STATUS

Tabla de constantes para los estados del plan de ejecución del flujo de trabajo, utilizada para identificar el estado actual del plan de ejecución correspondiente.

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

Excepto por los tres primeros, todos los demás representan un estado de fallo, pero pueden usarse para describir diferentes motivos de fallo.

#JOB_STATUS

Tabla de constantes para los estados de las tareas de los nodos del flujo de trabajo, utilizada para identificar el estado actual de la tarea del nodo correspondiente. El estado generado por el nodo también afecta el estado de todo el plan de ejecución.

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

#Lado del cliente

Las APIs disponibles en la estructura del paquete del lado del cliente se muestran en el siguiente código:

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

#PluginWorkflowClientV2

Clase del plugin de flujo de trabajo del lado del cliente. Normalmente se obtiene mediante this.app.pm.get('workflow').

#registerTrigger()

Registra el panel de configuración correspondiente al tipo de disparador.

Firma

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

Parámetros

#registerInstruction()

Registra el panel de configuración correspondiente al tipo de nodo.

Firma

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

Parámetros

#registerInstructionGroup()

Registra un grupo de tipos de nodo. NocoBase proporciona 4 grupos de tipos de nodo por defecto:

• 'control': Control
• 'collection': Operaciones de colección
• 'manual': Procesamiento manual
• 'extended': Otras extensiones

Si necesita extender otros grupos, puede utilizar este método para registrarlos.

Firma

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

Parámetros

Ejemplo

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

Determina si un flujo de trabajo está en modo síncrono.

Firma

isWorkflowSync(workflow: object): boolean

#Trigger

Clase base para disparadores, utilizada para extender tipos de disparadores personalizados.

Tipos relacionados

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

• Si useVariables no está configurado, significa que este tipo de disparador no proporciona una función de recuperación de valores, y los datos de contexto del disparador no se pueden seleccionar en los nodos del flujo de trabajo.

#Instruction

Clase base para instrucciones, utilizada para extender tipos de nodos personalizados.

Tipos relacionados

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

• Si useVariables no está configurado, significa que este tipo de nodo no proporciona una función de recuperación de valores, y los datos de resultado de este tipo de nodo no se pueden seleccionar en los nodos del flujo de trabajo. Si el valor resultante es singular (no seleccionable), puede devolver un contenido estático que exprese la información correspondiente (consulte: código fuente del nodo de cálculo). Si necesita que sea seleccionable (por ejemplo, una propiedad de un objeto), puede personalizar la salida del componente de selección correspondiente (consulte: código fuente del nodo de consulta de datos).
• ComponentLoader es un componente de renderizado personalizado para el nodo. Cuando el renderizado predeterminado del nodo no es suficiente, puede anularlo completamente para un renderizado de vista de nodo personalizado. Por ejemplo, para proporcionar renderizado de ramas adicional para nodos de tipo rama (consulte: código fuente del nodo de condición).
• isAvailable se utiliza principalmente para determinar si un nodo puede usarse (añadirse) en el entorno actual. El entorno actual incluye la instancia del plugin de flujo de trabajo, el flujo de trabajo actual, los nodos anteriores y el índice de la rama actual.

#Componentes de entrada de variables

El flujo de trabajo proporciona un conjunto de componentes de entrada de variables para permitir a los usuarios seleccionar variables del flujo de trabajo en los formularios de configuración de nodos/disparadores.

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

#WorkflowVariableInput

Entrada de variable que permite seleccionar una variable y continuar escribiendo contenido. Adecuado para escenarios de entrada de una sola línea que requieren una combinación de referencias de variables y texto libre.

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

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

Props

#WorkflowVariableTextArea

Área de texto multilínea que permite insertar referencias de variables en cualquier posición del cursor. Adecuado para escenarios de texto libre como cuerpo HTTP, texto de plantilla, etc.

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

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

Props

Hereda otros Props de TextArea de antd (como autoSize, placeholder, etc.).

#WorkflowTypedVariableInput

Entrada con tipo que alterna entre los modos "constante" y "referencia de variable". En modo variable, solo puede seleccionar una variable; no puede continuar escribiendo después de la selección. En modo constante, se admiten cinco tipos: string, number, boolean, date y object.

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

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

Props

Hereda otros Props de TypedVariableInput (excluyendo extraNodes, metaTree, namespaces que se usan internamente).

#WorkflowVariableWrapper

Envoltorio genérico para sustituir diferentes componentes de entrada en diferentes contextos. Por ejemplo, cuando el mismo campo requiere diferentes métodos de entrada en la configuración del nodo disparador y en el cajón de configuración del nodo, puede usar este componente para envolver una entrada nativa en una entrada con modo variable intercambiable.

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

#Componentes relacionados con colecciones

El flujo de trabajo también proporciona un conjunto de componentes auxiliares relacionados con colecciones:

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

• CollectionCascader — Selector de colección con reconocimiento de fuente de datos (cascada)
• AppendsSelect — Selector de precarga de campos de asociación (selector de árbol)
• FieldsSelect — Multi-selector de campos de colección
• SortFieldsInput — Entrada de campo de ordenamiento
• PaginationFields — Elementos de formulario de parámetros de paginación