Antes de começar
- Uma configuração de provider para o serviço e um node executor que a referencie. Veja Referenciar a configuração de provider a partir de um node de workflow.
- Os nomes dos campos que o serviço espera. Quando o documento OpenAPI do serviço está no registro, Derivar o schema de uma operação devolve
inputSchema— o corpo da requisição da operação — eoutputSchema— a resposta de sucesso dela. Os dois trazem os nomes de campo que você escreve como target e como source dos seus mapeamentos. - Um workflow em estado
draft. Um workflow ativo fica bloqueado, então use Mover o workflow para draft antes de editar um node e ative-o de novo depois.
Não envie
executorId em um node que chama uma operação de um documento OpenAPI enviado. Esse node nomeia a operação com operation_path e operation_method. O Flowker preenche o executorId por você, a partir da configuração de provider para a qual o node aponta, antes de validar o workflow. Ele faz isso quando você cria o workflow e quando você o atualiza. Conectando a sua própria API percorre todo esse caminho. Os nodes desta página nomeiam http, o conector HTTP genérico, que precisa de um executorId explícito.Passo 1: Saiba o que um mapeamento pode ler
Todo mapeamento lê do contexto do workflow, um único objeto JSON que cresce conforme a execução avança:
Enderece um valor pelo caminho dele a partir de uma dessas chaves de nível superior:
O
source de um mapeamento é um caminho simples. Não o envolva em ${...}: as chaves pertencem aos campos de template do node (body, headers, query, path), e dentro de um mapeamento uma string ${...} é lida como um nome de caminho literal que não seleciona nada.Passo 2: Declare o mapeamento de entrada
Os mapeamentos de entrada ficam em um array
inputMapping dentro do objeto data do node executor. Cada entrada move um valor para o corpo da requisição de saída.
O resultado do mapeamento é o corpo da requisição. Escreva cada
target exatamente como o serviço espera recebê-lo: não existe objeto envolvente nem prefixo a acrescentar.
Exemplo — mapear o payload do trigger para uma verificação de fraude
Exemplo — mapear o payload do trigger para uma verificação de fraude
{"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}, o serviço recebe:Quando um source não seleciona nada
Um caminho de origem ausente do contexto não é um erro. O target é escrito de todo modo, com o valornull, e a requisição sai.
Use required: true quando o node não puder chamar o serviço sem um valor. O Flowker então confere cada caminho de origem daquele node antes de montar a requisição e falha o passo quando algum está ausente: a execução para com FLK-0504 e o passo informa input transformation failed.
required vale para o node, não só para a entrada que o carrega. Se alguma entrada do inputMapping de um node marca required: true, cada caminho de origem daquele array precisa resolver. Para manter alguns campos opcionais, deixe required de fora no node inteiro.target uma única entrada. Quando duas entradas escrevem o mesmo target, a última vence.
Passo 3: Decida o que monta o corpo da requisição
Um node tem três formas de produzir um corpo de requisição. O Flowker as confere em uma ordem fixa e para na primeira que estiver presente:
1
data.body
Um template de corpo explícito vence por completo. O Flowker resolve as referências
${...} dele contra o contexto do workflow e envia o resultado. Enquanto data.body está presente, inputMapping, transforms e config não contribuem nada para o corpo.Cada referência ${...} aqui precisa resolver. Uma que não resolve falha o node com FLK-0143, antes de qualquer chamada — o oposto de um source de mapeamento, que resolve como null. Use data.body quando um valor ausente precisa parar o workflow, e um mapeamento quando a requisição precisa sair de todo modo.2
inputMapping ou transforms
Caso contrário, o Flowker monta uma camada a partir de
inputMapping. Quando inputMapping está vazio, ele monta a camada a partir de transforms. Os dois são mutuamente exclusivos: um node com pelo menos uma entrada em inputMapping nunca executa os transforms dele sobre a entrada.3
Literais de config
Os valores literais de
data.config semeiam o corpo. Com uma camada presente, os literais são a base e a camada vence em qualquer chave que os dois definam, então um mesmo node pode combinar valores fixos com valores mapeados. Sem camada, os literais são o corpo por conta própria.config possa semear o corpo, o Flowker remove de lá estes nomes: method, path, url, endpointName, query, headers, auth, retry, timeout, timeout_seconds, request_format, success_status_codes, allowedHosts e allowedPrivateHosts. Por isso um node que guarda transporte em config por engano não envia nada disso ao destino, e um bloco auth colocado lá nunca pode viajar como conteúdo da requisição.
O node lê o próprio transporte no nível superior do objeto data dele: path, endpointName, method, headers, query, auth, timeout_seconds, retry, success_status_codes e request_format. As listas de hosts permitidos de saída não estão entre eles: allowedHosts e allowedPrivateHosts são definidos na configuração de provider, e cada uma vale para todos os nodes que chamam através dela.
Exemplo — valores fixos junto com valores mapeados
Exemplo — valores fixos junto com valores mapeados
Passo 4: Ajuste um valor em trânsito
Quando o serviço precisa de um valor em outro formato, acrescente uma
transformation à entrada do mapeamento. Ela se aplica ao valor depois que ele chega ao target.
Esses cinco são o conjunto completo. Um
type fora dele é recusado quando você salva o workflow, com FLK-0140.
Duas regras para escrevê-las:
- Elas atuam sobre texto. Um valor que não é texto chega ao target sem mudança.
prefixesuffixprecisam de pelo menos um caractere cada um, e um único espaço conta.charactersprecisa de pelo menos um caractere que não seja espaço, tabulação nem quebra de linha. Um valor que não atende a isso falha o passo em tempo de execução comFLK-0504.
Exemplo — normalizar um documento e marcar uma referência
Exemplo — normalizar um documento e marcar uma referência
{"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}, o node envia:Transformações sobre o documento inteiro
Para o trabalho que o mapeamento entrada por entrada não expressa — combinar dois campos, escolher o primeiro valor presente, preencher um valor padrão — declare um arraytransforms. Cada operação lê todo o contexto do workflow e escreve a camada inteira.
O Flowker aceita shift (mover ou renomear), concat (juntar valores), coalesce (primeiro valor presente), default (preencher uma chave ausente), extract (subir uma subárvore para a raiz), delete (remover uma chave), timestamp, uuid e pass. Os cinco tipos de transformação acima também estão disponíveis aqui; como operações, eles recebem o caminho de destino na spec como path.
Exemplo — um shift e um default no mesmo node
Exemplo — um shift e um default no mesmo node
require: true para exigir que exista cada caminho que a spec dela nomeia, do mesmo modo que required funciona em uma entrada de mapeamento.transforms só é executado quando o node não tem inputMapping. Use um ou outro em um mesmo node, nunca os dois.Passo 5: Leia a resposta de volta
Os mapeamentos de saída extraem campos da resposta e os guardam no contexto do workflow sob o ID do node, para que os nodes seguintes leiam nomes curtos e estáveis. Declare-os em um array
outputMapping dentro do data do node, com os mesmos quatro campos de entrada de um mapeamento de entrada.
Um source de saída é um caminho dentro do envelope de resposta, não dentro do corpo da resposta:
Por isso os campos da resposta ficam sob
body:
score-transaction, isso guarda:
${score-transaction.score} e ${score-transaction.httpStatus}.
Um node que não declara outputMapping guarda o envelope inteiro sob o ID dele, e os nodes seguintes leem o caminho do envelope diretamente: ${score-transaction.body.score}. Acrescente um mapeamento de saída quando quiser o nome curto; dispense-o quando o caminho do envelope já for claro.
Um source de saída que não seleciona nada se comporta como um de entrada: o target é guardado como null, a não ser que uma entrada daquele node marque required: true.
Passo 6: Confira o mapeamento antes de chamar o serviço
Pré-visualizar a requisição de um executor monta a requisição que um node enviaria e a devolve para você. Ela executa a mesma montagem de mapeamentos, transformações e autenticação que uma execução real executa, e nunca abre uma conexão com o serviço, então você pode iterar sobre um mapeamento sem que uma única chamada saia do seu ambiente. Nenhuma credencial aparece no que ela devolve, nem mesmo no
curl.
Envie o node, a configuração de provider que ele mira e um payload de amostra. A configuração de provider vai na própria requisição, então a pré-visualização não depende de nada além do que você envia:
sampleInput se torna o payload do trigger, então os source do mapeamento o leem como workflow.*, exatamente como farão em tempo de execução.
A resposta é a requisição montada:
1
Confira a URL
Ela é a URL base da configuração de provider mais o
path do node. Um caminho que você não esperava é um campo do node a corrigir, não um mapeamento.2
Confira o corpo contra os nomes de campo que o serviço espera
Cada
target precisa aparecer onde o serviço o quer. Um campo com null é um caminho source que não seleciona nada.3
Confira `unresolved`
Ele lista as referências
${...} dos campos de template do node que o seu payload de amostra não resolveu. Elas ficam literais na requisição montada. Um array vazio significa que cada referência encontrou um valor.config e, em mappedTargets, os caminhos de target que o seu inputMapping fornece. O Flowker os conta como satisfeitos, então um node que mapeia um campo obrigatório a partir do trigger passa na conferência.
O que pode dar errado
Veja a lista de erros do Flowker para todos os códigos.
Próximos passos
Guia de integração
Crie a configuração de provider pela qual um node chama e defina a autenticação dela.
Configurando um trigger de webhook
Escolha o contrato de payload que preenche o namespace
workflow que os seus mapeamentos leem.