Antes de começar
- Uma configuração de provedor para o serviço, e um nó executor que a referencia. Veja Referenciar a configuração de provedor a partir de um nó do workflow.
- Os nomes de campo que o serviço espera. Quando o documento OpenAPI do serviço está no registro, Derivar o schema de uma operação retorna
inputSchema(o corpo da requisição da operação) eoutputSchema(a resposta de sucesso dela). Os dois dão os nomes de campo que você escreve como destinos e origens de mapeamento. - Um workflow no status
draft. Um workflow ativo fica travado, então use Mover workflow para draft antes de editar um nó, e ative-o de novo depois.
Não envie
executorId em um nó que chama uma operação de um documento OpenAPI enviado. Esse nó nomeia a operação com operation_path e operation_method. O Flowker preenche o executorId para você, a partir da configuração de provedor para a qual o nó aponta, antes de validar o workflow. Ele faz isso quando você cria o workflow e quando você o atualiza. Conectando sua própria API percorre esse caminho inteiro. Os nós desta página nomeiam http, o conector HTTP genérico, que de fato precisa de um executorId explícito.Passo 1: Saiba o que um mapeamento pode ler
Todo mapeamento lê do contexto do workflow, um objeto JSON único que cresce conforme a execução avança:
Referencie um valor pelo caminho dele a partir de uma dessas chaves de nível superior:
Um
source de mapeamento é um caminho simples. Não o envolva em ${...}. As chaves pertencem aos campos de template do nó (body, headers, query, path), e dentro de um mapeamento o Flowker lê uma string ${...} 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 nó executor. Cada entrada move um valor para o corpo da requisição de saída.
O resultado mapeado é o corpo da requisição. Escreva cada
target exatamente como o serviço espera recebê-lo: não existe objeto invólucro nem prefixo a acrescentar.
Exemplo: mapear o payload do gatilho para uma verificação antifraude
Exemplo: mapear o payload do gatilho para uma verificação antifraude
{"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}, o serviço recebe:Quando uma origem não seleciona nada
Um caminho de origem ausente do contexto não é um erro. O Flowker escreve o destino mesmo assim, com o valornull, e a requisição sai.
Defina required: true quando o nó não deve chamar o serviço sem um valor. O Flowker então checa todos os caminhos de origem daquele nó antes de montar a requisição, e falha o passo quando algum deles está ausente. A execução para com FLK-0504 e o passo informa input transformation failed.
required vale para o nó, não para a única entrada que o carrega. Se qualquer entrada do inputMapping de um nó define required: true, todos os caminhos de origem daquele array devem resolver. Para manter alguns campos opcionais, deixe required desligado no nó inteiro.target uma entrada. Quando duas entradas escrevem o mesmo destino, a última vence.
Passo 3: Decida o que monta o corpo da requisição
Um nó tem três fontes para o corpo de uma requisição. Apenas
data.body é exclusivo: quando está presente, ele é o corpo inteiro. Sem ele, o Flowker compõe o corpo a partir das outras duas fontes, com a sobreposição do mapeamento escrita por cima dos literais de config:
1
data.body
Um template de corpo explícito vence de forma absoluta. O Flowker resolve as referências
${...} dele em relação ao contexto do workflow e envia o resultado. Enquanto data.body está presente, inputMapping, transforms e config não contribuem em nada para o corpo.Toda referência ${...} aqui deve resolver. Uma que não resolve faz o nó falhar com FLK-0143, antes de qualquer chamada sair (o oposto de uma origem de mapeamento, que resolve para null). Use data.body quando um valor ausente deve parar o workflow, e um mapeamento quando a requisição deve sair de qualquer jeito.2
inputMapping ou transforms
Caso contrário, o Flowker monta uma sobreposição a partir de
inputMapping. Quando inputMapping está vazio, ele monta a sobreposição a partir de transforms. Os dois são mutuamente exclusivos: um nó com pelo menos uma entrada de inputMapping nunca roda os transforms dele na entrada.3
literais de config
Valores literais em
data.config semeiam o corpo. Com uma sobreposição presente, os literais são a base e a sobreposição vence em qualquer chave que os dois definem. Um nó pode, assim, combinar valores fixos com valores mapeados. Sem sobreposição, os literais são o corpo sozinhos.config possa semear o corpo, o Flowker remove estes nomes dele: method, path, url, endpointName, query, headers, auth, retry, timeout, timeout_seconds, request_format, success_status_codes, allowedHosts e allowedPrivateHosts. Um nó que guarda o transporte em config por engano, portanto, não envia nada disso para o destino. Um bloco auth colocado ali nunca pode seguir como conteúdo da requisição.
O nó lê o próprio transporte no topo do objeto data dele: path, endpointName, method, headers, query, auth, timeout_seconds, retry, success_status_codes e request_format. As listas de hosts permitidos para saída não estão entre eles: você define allowedHosts e allowedPrivateHosts na configuração de provedor, onde cada uma vale para todos os nós que chamam por meio dela.
Exemplo: valores fixos mais valores mapeados
Exemplo: valores fixos mais valores mapeados
Passo 4: Remodele um valor no caminho
Quando o serviço precisa de um valor em outra forma, anexe uma
transformation à entrada de mapeamento. Ela se aplica ao valor depois que ele chega no destino.
Esses cinco são o conjunto inteiro. Um
type fora dele falha quando você salva o workflow, com FLK-0140.
Duas regras para escrevê-las:
- Elas agem sobre texto. Um valor que não é texto chega ao destino sem mudança.
- Os valores
prefixesuffixprecisam de pelo menos um caractere cada, e um único espaço conta. O valorcharactersprecisa 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 carimbar uma referência
Exemplo: normalizar um documento e carimbar uma referência
{"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}, o nó envia:Transforms de documento inteiro
Para o trabalho que o mapeamento entrada por entrada não expressa (combinar dois campos, escolher o primeiro valor presente, preencher um padrão), declare um arraytransforms no lugar. Cada operação lê o contexto do workflow inteiro e escreve a sobreposição inteira.
O Flowker aceita shift (mover ou renomear), concat (juntar valores), coalesce (primeiro valor presente), default (preencher uma chave ausente), extract (elevar 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 nó
Exemplo: um shift e um default no mesmo nó
require: true para exigir que todo caminho nomeado pelo spec dela exista, do mesmo jeito que required funciona em uma entrada de mapeamento.transforms roda apenas quando o nó não tem inputMapping. Use um ou o outro em um mesmo nó, 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 nó, para que os nós posteriores leiam nomes curtos e estáveis. Declare-os em um array
outputMapping no data do nó, com os mesmos quatro campos de entrada de um mapeamento de entrada.
Um source de saída é um caminho dentro do envelope da resposta, não dentro do corpo da resposta:
Os campos da resposta ficam, portanto, sob
body:
score-transaction, isso guarda:
${score-transaction.score} e ${score-transaction.httpStatus}.
Um nó que não declara outputMapping guarda o envelope inteiro sob o id dele, e os nós downstream leem o caminho do envelope direto: ${score-transaction.body.score}. Acrescente um mapeamento de saída quando você quiser o nome mais curto. Pule isso quando o caminho do envelope já for claro o bastante.
Uma origem de saída que não seleciona nada se comporta como uma de entrada. O Flowker guarda o destino como null, a menos que uma entrada daquele nó defina required: true.
Passo 6: Confira o mapeamento antes de chamar o serviço
Pré-visualizar uma requisição de executor usa os caminhos de mapeamento, de transformação e de montagem da requisição sem fazer uma chamada de rede ao serviço. Ela não lê o vault nem busca um token de autenticação. Ela mascara os valores secretos fornecidos e usa o catálogo do Flowker para resolver o provedor e o executor. Nenhuma credencial aparece em lugar nenhum do que ela retorna, inclusive no
curl.
Envie o nó, a configuração de provedor que ele mira e um payload de exemplo. A configuração de provedor vai na própria requisição, então a prévia não precisa de uma configuração de provedor salva nem de uma leitura do vault. O catálogo do lado do servidor ainda deve resolver o provedor e o executor:
sampleInput vira o payload do gatilho, então as origens 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 provedor mais o
path do nó. Um caminho que você não esperava é um campo do nó a corrigir, não um mapeamento.2
Confira o corpo em relação aos nomes de campo que o serviço espera
Recomenda-se que cada
target apareça onde o serviço o quer. Um campo carregando null é um caminho source que não seleciona nada.3
Confira unresolved
Ele lista as referências
${...} nos campos de template do nó que seu payload de exemplo não resolveu. O Flowker as deixa literais na requisição renderizada. Um array vazio significa que cada referência encontrou um valor.config e, em mappedTargets, os caminhos de destino que seu inputMapping fornece. O Flowker conta esses como satisfeitos, então um nó que mapeia um campo obrigatório vindo do gatilho passa na checagem.
O que dá errado
Veja a lista de erros do Flowker para todos os códigos.
O que vem a seguir
Guia de integração
Crie a configuração de provedor pela qual um nó chama, e defina a autenticação dela.
Configurando um gatilho de webhook
Escolha o contrato de payload que preenche o namespace
workflow que seus mapeamentos leem.