Modernização de Fluxos Salesforce
Os modelos padrão utilizam os padrões de Fluxo dos seus dados de treinamento: Loop + Decisão + Atribuição, DML dentro de loops, atualizações após a gravação do registro acionador, telas extras para recalcular. Esta habilidade os substitui pelos elementos atuais e fornece metadados verificados por implantação para cada um em examples/.
Estas regras determinam a maioria dos resultados:
- O elemento moderno é o padrão. Um Loop precisa de uma condição de escape declarada (abaixo). Quando o XML de um elemento não for familiar, copie a forma do seu arquivo de exemplo em vez de evitar o elemento.
- Não verificável não significa indisponível. A disponibilidade segue a versão da API da organização e a tabela abaixo. Você não precisa de acesso à web para usar um elemento cujo mínimo esteja na versão da organização ou abaixo dela. A validação de implantação é a verificação.
- Cada loop e cada fallback são explicados. Nomeie o escape na descrição do Loop e no entregável. Sem um escape nomeado, não escreva o loop.
Fluxo de Trabalho
Copie esta lista de verificação para suas notas de trabalho e marque-a:
- [ ] 1. Leia as referências/org-conventions.md; liste os slots não definidos dos quais esta tarefa depende
- [ ] 2. Estabeleça a versão da API da organização
- [ ] 3. Classifique a tarefa: construir, auditar ou migrar; tipo de fluxo, evento de acionamento, executa como quem
- [ ] 4. Mapeie cada requisito através da tabela de decisão; abra cada exemplo que você usar
- [ ] 5. Escreva os metadados (ou a especificação de construção)
- [ ] 6. Execute scripts/check-flow.mjs; corrija cada ERROR, decida cada WARNING
- [ ] 7. Valide a implantação quando uma organização estiver disponível; caso contrário, rotule o XML como não validado
- [ ] 8. Execute a lista de verificação de revisão em referências/delivery.md e entregue
Etapa 1. Convenções. Um slot preenchido em org-conventions.md substitui os padrões desta habilidade. Um slot vazio significa que o padrão se aplica e o entregável o lista em decisões abertas.
Etapa 2. Versão da API. Com uma organização, sf org display --target-org <alias> mostra "Api Version". Sem uma, use sourceApiVersion do sfdx-project.json do projeto, ou 67.0 quando isso também estiver faltando, e diga isso. Defina a apiVersion de novos fluxos para essa versão.
Etapa 3. Classifique. Fluxo existente ou nova construção. Tipo de fluxo (tela, acionado por registro antes da gravação ou após a gravação, autolançado, acionado por agendamento, acionado por evento de plataforma). Objeto acionador e evento de acionamento, respondido a partir do requisito antes de você abrir qualquer exemplo. A questão é se um registro criado já atendendo à condição conta, ou apenas um que muda para ela. Criar e atualizar com "apenas quando atualizado para atender à condição" dispara em tal criação, enquanto apenas atualizar não. Se o requisito não disser, pergunte ou declare a suposição (record-triggered.md). Quem o executa (usuário, sistema, agente). O que deve acontecer de forma síncrona. Para fluxos de tela, a superfície que o incorpora e o que ele recebe e retorna.
Etapa 4. Mapeie. Para cada operação de coleção, lista de escolhas, interação de tela, atualização de registro, necessidade de temporização e integração, pegue a linha da tabela de decisão. Leia o arquivo de exemplo para cada elemento que você escreverá e a referência de domínio para seus limites. Leia apenas as referências para os domínios que a tarefa aborda.
Etapa 5. Escreva. Os metadados vão para force-app/main/default/flows/<ApiName>.flow-meta.xml (ajuste para o diretório de pacotes do projeto). Padrões de nomenclatura: nomes de API de fluxo Objeto_Verbo_Condição, nomes de elementos Tipo_Propósito (Buscar_Casos_Abertos, Filtrar_Alta_Prioridade, Transformar_Em_Tarefas, Dec_E_Renovacao), a menos que org-conventions.md diga o contrário. Defina <status>Draft</status> a menos que o usuário peça explicitamente um fluxo ativo ou o slot de política de ativação diga isso. Os exemplos estão Ativos apenas porque foram executados. Mantenha todos os elementos de um tipo juntos no arquivo (grupos divididos falham na implantação). Sem acesso à CLI, entregue uma especificação de construção no formato em delivery.md.
Etapa 6. Verifique. Execute o verificador em cada fluxo que você escreveu ou foi solicitado a revisar. Ele precisa apenas do Node:
node <skill-dir>/scripts/check-flow.mjs --api <org-api-version> force-app/main/default/flows/<ApiName>.flow-meta.xml
ERRORs são padrões legados ou formas que a plataforma rejeita, então corrija-os. WARNINGs precisam de uma decisão, que você declara no entregável.
Etapa 7. Valide. Com uma organização autenticada, nomeie a organização explicitamente em vez de confiar na organização padrão da CLI:
sf project deploy validate --source-dir force-app/main/default/flows/<ApiName>.flow-meta.xml --target-org <alias>
Corrija contra o erro exato e execute novamente. O XML que não foi validado é rotulado como não validado no entregável, claramente.
Etapa 8. Revise e entregue. Execute a lista de verificação de revisão em delivery.md. Termine o entregável com este bloco, cada linha preenchida:
Modo: metadados | especificação de construção
Verificador: <comando> → <n> erros, <n> avisos (<decisão por aviso>)
Validação de implantação: <comando e resultado> | não executado, não validado (<motivo>)
Status: Rascunho | Ativo (<porquê>)
Contexto de execução: <runInMode ou padrão, e o que isso significa para este tipo de fluxo>
Escapes: <E-id e motivo por loop ou fallback> | nenhum
Decisões abertas: <slots de convenção não definidos dos quais este fluxo depende> | nenhum
Padrões de contexto de execução (runInMode DefaultMode): fluxos acionados por registro, acionados por agendamento e acionados por evento de plataforma são executados no contexto do sistema sem compartilhamento. Fluxos de tela e autolançados são executados no contexto do usuário quando iniciados a partir da interface do usuário ou API REST, e no contexto do chamador quando chamados a partir do Apex ou de outro fluxo. Autolançado não é "sistema por padrão".
Auditorias e Migrações
Para um fluxo existente, execute o verificador nele primeiro, depois faça um inventário dos padrões legados restantes em relação à última coluna da tabela de decisão. Entregue o relatório de auditoria definido em delivery.md antes de qualquer reescrita, classificado por impacto: limites do governor, depois contexto de segurança, depois experiência do usuário. Não modifique o fluxo a menos que solicitado. Quando solicitado, siga o plano de migração do relatório em ordem. Descreva padrões, nunca as pessoas que os construíram, porque a maioria dos padrões legados era a abordagem recomendada quando foram escritos. O mapeamento do Process Builder e regras de workflow está em legacy-migration.md.
Tabela de Decisão
"Org API" é a versão mais baixa da API da organização que possui o elemento (Flow, Metadata API Developer Guide). Os exemplos estão em examples/flows/, implantados e executados na API 67.0.
| Requisito | Use | Metadados | Org API | Exemplo | Substitui |
|---|---|---|---|---|---|
| Manter os itens de uma coleção que correspondem aos critérios | Filtro de Coleção (condições ou fórmula) | collectionProcessors, FilterCollectionProcessor | 53 | Opportunity_Create_Followup_Tasks | Loop + Decisão + Atribuição |
| Construir registros a partir de uma coleção, remodelar campos | Transformar, Mapear | transforms | 59 | Opportunity_Create_Followup_Tasks | Loop + Atribuição construindo uma coleção |
| Somar ou contar uma coleção | Transformar, Soma / Contagem. Em fluxos antes da gravação, Filtro + Atribuição AssignCount, ou um Loop para uma Soma (E3) | transforms, inputParameters | 59 (alvo primitivo 62) | Opportunity_Create_Followup_Tasks, Account_Before_Save_Count_Contacts | Contadores de loop |
| Combinar duas coleções por uma chave | Transformar, InnerJoin, com o mapeamento no mesmo Transform | transforms, JoinDefinition | 63 | Opportunity_Create_Account_Tasks_Joined | Loops aninhados, Obter Registros dentro de um loop |
| Ordenar uma coleção | Classificação de Coleção (classifica no lugar) | SortCollectionProcessor | 50 | Opportunity_Allocate_Budget_Waterfall | Classificação manual em um loop |
| Criar, atualizar ou excluir muitos registros | Um DML na coleção preparada | recordCreates inputReference | qualquer | Opportunity_Create_Followup_Tasks | DML dentro de um loop |
| Opções de registros ou uma picklist | Conjunto de escolhas de registro / picklist | dynamicChoiceSets | qualquer | Account_Order_Entry_Screen | Obter Registros + Loop construindo escolhas |
| Totais, visibilidade ou texto que seguem a entrada | Fórmula reativa, visibilityRule | formulas, campos de tela | 59 | Account_Order_Entry_Screen | Uma segunda tela para recalcular |
| Regras de entrada em uma tela | validationRule do componente | fields da tela | qualquer | Account_Order_Entry_Screen | Decisão após a tela de volta para uma tela de erro |
| Lógica do servidor sem sair da tela | Ação de tela + Botão de Ação | screens.actions, triggers | 59 | Account_Check_Pipeline_Screen | Próximo, Obter Registros, voltar novamente |
| Definir campos no registro acionador | Fluxo antes da gravação, Atribuição a $Record | triggerType RecordBeforeSave | qualquer | Opportunity_Before_Save_Set_Next_Step | Atualizar Registros após a gravação em $Record |
| Bloquear uma gravação com uma mensagem | Erro Personalizado | customErrors | 59 | Opportunity_Before_Save_Set_Next_Step | Compensação após a gravação |
| Executar apenas quando campos relevantes mudam | Condições de entrada, filterFormula com ISCHANGED, "apenas quando atualizado para atender à condição" | start | 55 (fórmula) | Opportunity_Before_Save_Set_Next_Step, Opportunity_Closed_Won_Handover | Decisão como o primeiro elemento |
| Chamadas externas, e-mails, DML não relacionado que o usuário não precisa esperar | Caminho assíncrono | scheduledPaths AsyncAfterCommit | 53 | Opportunity_Closed_Won_Handover | Tudo síncrono |
| Trabalho antes ou depois de uma data de registro | Caminho agendado | scheduledPaths RecordField | 51 | Opportunity_Closed_Won_Handover | Fluxo acionado por agendamento consultando registros vencidos |
| Reagir a um evento de plataforma | Fluxo acionado por evento de plataforma | triggerType PlatformEvent | 49 | Order_Event_Create_Task | Gatilho Apex escrito para iniciar a lógica do Fluxo |
| Pausar até que um evento chegue | Elemento de Espera com um evento de plataforma | waits | qualquer | Order_Wait_For_Confirmation | Consulta |
| Lógica de Fluxo para um agente Agentforce | Fluxo autolançado com entradas e saídas descritas | variables description | qualquer | Case_Get_Status_For_Agent | Invocable Apex wrapper |
| Ordem entre fluxos em um objeto | Ordem de Acionamento | triggerOrder | 54 | Opportunity_Closed_Won_Handover | Confiar na ordem de criação |
| Chamar uma API REST | Ação de chamada HTTP | actionCalls (gerado pelo Builder) | veja referência de integração | nenhum | Apex escrito apenas para a chamada |
Transform não é permitido em fluxos antes da gravação (erro de implantação). Antes da gravação substitui Transform, portanto, um valor no registro acionador permanece antes da gravação, e uma Soma lá é um Loop sob E3, nunca um Transform após a gravação mais uma segunda gravação. Todo o resto acima funciona em todos os tipos de fluxo que têm o conceito, e as referências de domínio listam as exceções.
Condições de Escape
Um padrão legado é correto apenas quando uma destas condições se aplica. Declare-o na <description> de um Loop como Escape: E<n> <motivo>, e no entregável.
| Id | Permite | Aplica-se apenas quando |
|---|---|---|
| E1 | Um Loop | Cada item precisa de sua própria chamada para uma ação, subfluxo ou plugin Apex que aceita apenas valores únicos. O corpo do loop contém essa chamada. |
| E2 | Um Loop | O resultado de um item depende de itens anteriores além de uma soma ou contagem: saldo corrente, alocação, número de sequência, round robin. |
| E3 | Um Loop | Um fluxo antes da gravação precisa de uma Soma (Transform não é permitido lá). Isso é intencional, porque o Loop em memória é mais barato do que uma segunda gravação após a gravação. Contagens usam Filtro + AssignCount em vez disso. |
| E4 | Trabalhar no caminho síncrono | Um elemento posterior na mesma transação lê o resultado, ou o usuário deve vê-lo antes que a gravação seja concluída. |
| E5 | Sem recursos de tela reativa ou mais recentes | A superfície de incorporação nomeada não os suporta: runtime do Salesforce Classic, Slack (conjunto limitado de componentes) ou um componente que os documentos reativos listam como não reativo. |
| E6 | Manter um padrão legado no lugar | Apenas escopo de auditoria: o fluxo está fora da alteração que você foi solicitado a fazer. Nunca se aplica a fluxos novos ou reescritos. |
Estes não contam como condições de escape:
- "Não consigo verificar se o elemento existe nesta organização" (a regra 2 se aplica, então verifique a versão da API e depois valide a implantação).
- "Não tenho certeza sobre o XML" (copie o exemplo).
- "Um loop é mais simples ou mais claro."
- "Valores condicionais por item" (use
IF()em uma fórmula Transform). - "Filtrar e mapear em uma passagem" (Filtrar, depois Transformar).
- "A superfície pode não suportar" (nomeie a superfície ou liste-a como uma decisão aberta, porque uma superfície desconhecida não é E5).
- DML ou Obter Registros dentro de um loop. Nenhum escape os permite.
Use o elemento suficiente mais simples. Isso significa apenas Filtrar quando apenas filtrando, escolhas estáticas quando a lista de opções é fixa e nenhum subfluxo para lógica com um único chamador.
Verifique antes de afirmar
- Disponibilidade: versão da API da organização em relação à tabela. Trate recursos restritos por licença (Agentforce, Einstein, Data 360, algumas edições de orquestração) como suposições até que a organização os confirme, e diga isso.
- Limites e status de GA que alteram um design ou uma descoberta de auditoria: cite a fonte oficial (help.salesforce.com, developer.salesforce.com). Não cite números de memória, porque as referências de domínio fornecem os verificados.
Tratamento de Erros
- CLI ausente ou organização inacessível: entregue metadados rotulados como não validados, ou uma especificação de construção, e diga qual.
- Validação falha: corrija contra a mensagem exata, execute novamente o verificador e a validação. As referências de domínio listam os erros de implantação vistos até agora.
- Recurso não na organização (versão da API, edição, licença): use a linha suportada mais próxima da tabela, nomeie a lacuna e o escape.
Referências
Leia as que a tarefa precisa:
- org-conventions.md: as decisões da equipe, que substituem os padrões.
- collections.md: Filtro, Classificação, Transformação (mapa, soma, contagem, junção), DML em massa, loops.
- screens.md: conjuntos de escolhas, telas reativas, validação, ações de tela, incorporação.
- record-triggered.md: opções de acionamento, contexto do sistema, fluxos antes da gravação.
- legacy-migration.md: mapeamento de Process Builder e regras de workflow.
- delivery.md: formato do entregável e lista de verificação de revisão.
- domain-limits.md: limites verificados por tipo de fluxo.
- build-spec.md: formato da especificação de construção, ao escrever sem acesso à organização.