#Referência da API

#Lado do servidor

As APIs disponíveis na estrutura do pacote do lado do servidor são mostradas no código a seguir:

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

#PluginWorkflowServer

Classe do plugin de fluxo de trabalho.

Geralmente, durante a execução do aplicativo, você pode chamar app.pm.get<PluginWorkflowServer>(PluginWorkflowServer) em qualquer lugar onde possa obter a instância do aplicativo app para acessar a instância do plugin de fluxo de trabalho (referida como plugin abaixo).

#registerTrigger()

Estende e registra um novo tipo de gatilho.

Assinatura

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

Parâmetros

Exemplo

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

Estende e registra um novo tipo de nó.

Assinatura

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

Parâmetros

Exemplo

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

Aciona um fluxo de trabalho específico. Usado principalmente em gatilhos personalizados para acionar o fluxo de trabalho correspondente quando um evento personalizado específico é detectado.

Assinatura

trigger(workflow: Workflow, context: any)

Parâmetros

Exemplo

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

Retoma a execução de um fluxo de trabalho em espera com uma tarefa de nó específica.

• Apenas fluxos de trabalho no estado de espera (EXECUTION_STATUS.STARTED) podem ser retomados.
• Apenas tarefas de nó no estado pendente (JOB_STATUS.PENDING) podem ser retomadas.

Assinatura

resume(job: JobModel)

Parâmetros

Exemplo

Veja os detalhes no código-fonte.

#Trigger

A classe base para gatilhos, usada para estender tipos de gatilhos personalizados.

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

on/off são usados para registrar/desregistrar listeners de eventos quando um fluxo de trabalho é ativado/desativado. O parâmetro passado é a instância do fluxo de trabalho correspondente ao gatilho, que pode ser processado de acordo com a configuração. Alguns tipos de gatilho que já possuem eventos escutados globalmente podem não precisar implementar esses dois métodos. Por exemplo, em um gatilho agendado, você pode registrar um temporizador em on e desregistrá-lo em off.

#Instruction

A classe base para tipos de instrução, usada para estender tipos de instrução 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, você pode consultar a implementação do nó de loop, que é usada para fornecer o conteúdo da variável local para as ramificações.

#EXECUTION_STATUS

Uma tabela de constantes para os status do plano de execução do fluxo de trabalho, usada para identificar o status atual do plano de execução correspondente.

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

Exceto pelos três primeiros, todos os outros representam um estado de falha, mas podem ser usados para descrever diferentes motivos de falha.

#JOB_STATUS

Uma tabela de constantes para os status das tarefas de nó do fluxo de trabalho, usada para identificar o status atual da tarefa de nó correspondente. O status gerado pelo nó também afeta o status de todo o plano de execução.

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

#Lado do cliente

As APIs disponíveis na estrutura do pacote do lado do cliente são mostradas no código a seguir:

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

#PluginWorkflowClientV2

Classe do plugin de fluxo de trabalho do lado do cliente. Geralmente obtida via this.app.pm.get('workflow').

#registerTrigger()

Registra o painel de configuração para um tipo de gatilho.

Assinatura

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

Parâmetros

#registerInstruction()

Registra o painel de configuração para um tipo de nó.

Assinatura

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

Parâmetros

#registerInstructionGroup()

Registra um grupo de tipos de nó. O NocoBase oferece 4 grupos de tipos de nó padrão:

• 'control': Controle
• 'collection': Operações de coleção
• 'manual': Processamento manual
• 'extended': Outras extensões

Se você precisar estender outros grupos, pode usar este método para registrá-los.

Assinatura

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

Parâmetros

Exemplo

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 se um fluxo de trabalho está no modo síncrono.

Assinatura

isWorkflowSync(workflow: object): boolean

#Trigger

A classe base para gatilhos, usada para estender tipos de gatilhos personalizados.

Tipos Relacionados

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

• Se useVariables não for definido, significa que este tipo de gatilho não fornece uma função de recuperação de valor, e os dados de contexto do gatilho não podem ser selecionados nos nós do fluxo de trabalho.

#Instruction

A classe base para instruções, usada para estender tipos de nós personalizados.

Tipos Relacionados

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

• Se useVariables não for definido, significa que este tipo de nó não fornece uma função de recuperação de valor, e os dados de resultado deste tipo de nó não podem ser selecionados nos nós do fluxo de trabalho. Se o valor do resultado for singular (não selecionável), você pode retornar um conteúdo estático que expresse a informação correspondente (consulte: código-fonte do nó de cálculo). Se for necessário que seja selecionável (por exemplo, uma propriedade de um Object), você pode personalizar a saída do componente de seleção correspondente (consulte: código-fonte do nó de consulta de dados).
• ComponentLoader é um componente de renderização personalizado para o nó. Quando a renderização padrão do nó não é suficiente, ele pode ser completamente substituído para uma renderização de visualização de nó personalizada. Por exemplo, para fornecer renderização adicional de ramificação para nós do tipo ramificação (consulte: código-fonte do nó de condição).
• isAvailable é usado principalmente para determinar se um nó pode ser usado (adicionado) no ambiente atual. O ambiente atual inclui a instância do plugin de fluxo de trabalho, o fluxo de trabalho atual, nós upstream e o índice da ramificação atual.

#Componentes de Entrada de Variáveis

O fluxo de trabalho fornece um conjunto de componentes de entrada de variáveis para permitir que os usuários selecionem variáveis do fluxo de trabalho nos formulários de configuração de nós/gatilhos.

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

#WorkflowVariableInput

Entrada de variável que suporta selecionar uma variável e continuar digitando conteúdo. Adequado para cenários de entrada de linha única que requerem uma mistura de referências de variável e texto livre.

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

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

Props

#WorkflowVariableTextArea

Área de texto de múltiplas linhas que suporta inserir referências de variável em qualquer posição do cursor. Adequado para cenários de texto livre como corpo HTTP, texto de template, etc.

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

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

Props

Herda outras Props do TextArea do antd (como autoSize, placeholder, etc.).

#WorkflowTypedVariableInput

Entrada tipada que alterna entre os modos "constante" e "referência de variável". No modo variável, você só pode selecionar uma variável; não é possível continuar digitando após a seleção. No modo constante, cinco tipos são suportados: string, number, boolean, date e object.

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

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

Props

Herda outras Props de TypedVariableInput (excluindo extraNodes, metaTree, namespaces usados internamente).

#WorkflowVariableWrapper

Wrapper genérico para substituir diferentes componentes de entrada em diferentes contextos. Por exemplo, quando o mesmo campo requer diferentes métodos de entrada na configuração do nó gatilho e na gaveta de configuração do nó, você pode usar este componente para envolver uma entrada nativa em uma entrada com alternância de modo variável.

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 a Coleções

O fluxo de trabalho também fornece um conjunto de componentes auxiliares relacionados a coleções:

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

• CollectionCascader — Seletor de coleção com reconhecimento de fonte de dados (cascata)
• AppendsSelect — Seletor de pré-carregamento de campos de associação (seleção em árvore)
• FieldsSelect — Multi-seletor de campos de coleção
• SortFieldsInput — Entrada de campo de ordenação
• PaginationFields — Itens de formulário para parâmetros de paginação