Ações de fluxo de trabalho personalizados
Use a ferramenta de fluxos de trabalho da HubSpot para automatizar os processos de negócios e permitir que sua equipe seja mais eficiente. Você pode criar ações de fluxo de trabalho personalizadas para integrar seu serviço a fluxos de trabalho do HubSpot.
Depois de configurar sua ação personalizada, quando os usuários instalarem o aplicativo, eles poderão adicionar a ação personalizada aos seus fluxos de trabalho.
Quando esses fluxos de trabalho forem executados, as solicitações HTTPS serão enviadas à URL configurada com a payload definida. As solicitações feitas para sua ação personalizada usarão a versão v2 do X-HubSpot-Signature. Saiba mais sobre como validar solicitações do HubSpot.
Você também pode avançar para as seguintes seções:
- Antes de começar
- Definir sua ação personalizada
- Funções
- Campos de entrada
- Obter campos de dados externos
- Campos de saída
- Rótulos
- Execução
- Execução de ação personalizada assíncrona
- Adicionar mensagens de execução personalizadas com regras de execução
- Testar e publicar sua ação personalizada
- Você precisará de uma conta do desenvolvedor da HubSpot com um app da HubSpot. O logotipo do seu aplicativo será usado como o ícone da ação personalizada.
- Ao fazer solicitações para os endpoints de ação de fluxo de trabalho, você precisa incluir sua chave de conta do desenvolvedor do HubSpot na URL de solicitação. Por exemplo:
https://api.hubspot.com/automation/v4/actions/{appId}?hapikey={API_key}
Para criar uma ação de fluxo de trabalho personalizada, você precisará definir a ação usando os seguintes campos. Isso também especifica o formato das solicitações provenientes do HubSpot, bem como o tratamento das respostas pelo seu serviço.
actionUrl
: a URL para a qual uma solicitação HTTPS é enviada quando a ação é executada. O corpo da solicitação conterá informações sobre o usuário para o qual ação está sendo executada e quais valores foram inseridos para os campos de entrada.objectTypes
: em quais objetos do CRM esta ação pode ser usada.published
: por padrão, as ações personalizadas são criadas em um estado não publicado. As ações não publicadas ficam visíveis somente no portal do desenvolvedor associado ao seu aplicativo HubSpot. Para tornar uma ação personalizada visível para os usuários, atualize o sinalizador published na definição da ação para true.inputFields
: as entradas recebidas pela ação. Os campos serão preenchidos pelo usuário.inputFieldDependencies
: essas regras permitem que os campos fiquem esmaecidos até que outros campos atendam a condições específicas.outputFields
: os valores que a ação enviará e que poderão ser usados por ações posteriores no fluxo de trabalho. Uma ação personalizada pode ter zero, uma ou muitas saídas.objectRequestOptions
: propriedades do objeto inscrito incluídas na payload de actionUrl.labels
: texto que descreve o que os campos de ação representam e o que a ação faz ao usuário. Rótulos em inglês são obrigatórios, mas os rótulos podem ser especificados em qualquer um dos seguintes idiomas permitidos: francês (fr
), alemão (de
), japonês (ja
), espanhol (es
), português do Brasil (pt-br
) e holandês (nl
).executionRules
: uma lista de definições que você pode especificar para revelar erros do seu serviço ao usuário que cria o fluxo de trabalho.functions
: snippets de código que são executados para transformar a payload que está sendo enviada para uma URL e/ou transformar a resposta dessa URL.
Exemplo de definição de ação personalizada
A definição acima renderizará o seguinte na ferramenta de fluxos de trabalho:
Há dois tipos de chamadas feitas para ações de fluxo de trabalho personalizado:
- Buscas de opção de campo: preencha uma lista de opções válidas quando um usuário está configurando um campo. Saiba mais sobre como usar as buscas de opção de campo para buscar campos de dados externos.
- Solicitações de execução de ação: feitas quando uma ação está sendo executada por um fluxo de trabalho que inclui a ação personalizada.
Funções são snippets usados para modificar payloads antes de enviá-las a uma API. Você também pode usar funções para analisar os resultados de uma API. As funções do HubSpot têm o suporte do AWS Lambda. No seguinte código:
event
contém os dados que são passados para a funçãoexport.main
é o método que será chamado quando a função for executada.- A função
callback
pode ser usada para retornar um resultado.
O código deve ser formatado da seguinte forma:
Ao configurar uma função, o formato functionSource
será uma string. Verifique se os caracteres no código passaram por escape.
Geralmente, a definição de uma função seguirá o formato:
No exemplo abaixo, examine o código de entrada, a função usada e a saída produzida.
Entrada de função:
Função utilizada:
Resultado esperado
As definições do campo de entrada seguirão o seguinte formato:
name
: o nome interno do campo de entrada, separado do seu rótulo. O rótulo exibido na interface do usuário deve ser definido usando a seção de rótulos da definição de ação personalizada.type
: o tipo de valor exigido pela entrada.fieldType
: como o campo de entrada deve ser renderizado na interface do usuário. Os campos de entrada imitam as propriedades do CRM; saiba mais sobre as combinações válidas detype
efieldType
supportedValueTypes
têm dois valores válidos:OBJECT_PROPERTY
: o usuário pode selecionar uma propriedade do objeto inscrito ou uma saída de uma ação anterior para usar como o valor do campo.STATIC_VALUE
: deve ser usado em todos os outros casos. Indica que o usuário deve inserir um valor.
isRequired
: determina se o usuário deve fornecer um valor para esta entrada
As definições do campo de entrada devem ser formatadas da seguinte forma:
Você também pode embutir opções para o usuário selecionar:
A payload enviada para optionsURL
será formatada da seguinte forma:
A resposta esperada deve estar formatada da seguinte forma:
In the code above, note that there's pagination being set to limit the number of returned options. This instructs the workflow that more options can be loaded.
In addition, the list of options is made searchable by including searchable:true
.
Para gerenciar dados externos, você pode incluir dois ganchos para personalizar o ciclo de vida de busca de opção de campo:
PRE_FETCH_OPTIONS
: uma função que configura a payload enviada do HubSpot.POST_FETCH_OPTIONS
: uma função que transforma a resposta do seu serviço em um formato compreendido pelo HubSpot.
Quando incluída, esta função será aplicada a cada campo de entrada. Você pode aplicá-la a um campo de entrada específico especificando um id
na definição da função.
A payload enviada do HubSpot será formatada da seguinte forma:
A resposta deve ser formatada da seguinte forma:
Para analisar a resposta em um formato esperado, de acordo com os campos de dados externos, use a função POST_FETCH_OPTIONS
. A definição para a função POST_FETCH_OPTIONS
é a mesma que para a função PRE_FETCH_OPTIONS
. Quando opções externas de busca de dados estiverem definidas, um menu suspenso será renderizado nas opções de entrada para a ação.
A entrada da função será formatada da seguinte forma:
A saída da função será formatada da seguinte forma:
Use campos de saída para gerar valores de ação personalizada para usar em outras ações. A definição dos campos de saída é similar à definição dos campos de entrada:
- name: a forma como este campo é referenciado em outras partes da Ação personalizada. O rótulo exibido na interface do usuário deve ser definido usando a seção labels da Ação personalizada
- type: o tipo de valor exigido pela entrada.
- fieldType: é como o campo de entrada deve ser renderizado na interface do usuário. Os campos de entrada imitam as propriedades do CRM; saiba mais sobre as combinações válidas de
type
efieldType
O campo de saída deve ser formatado da seguinte forma:
Ao usar um campo de saída, os valores são analisados a partir da resposta de actionURL
. Por exemplo, você pode copiar campos de saída para uma propriedade existente no HubSpot.
Use rótulos para adicionar texto às saídas ou entradas no editor de fluxo de trabalho. Os rótulos são carregados no serviço de linguagem do HubSpot e podem levar alguns minutos para serem exibidos. Os portais definidos para regiões ou idiomas diferentes exibirão o rótulo no idioma correspondente, se disponível.
labels
: texto que descreve o que os campos de ação representam e o que a ação faz. Rótulos em inglês são obrigatórios, mas os rótulos podem ser especificados em qualquer um dos seguintes idiomas permitidos: francês (fr
), alemão (de
), japonês (ja
), espanhol (es
), português do Brasil (pt-br
) e holandês (nl
).actionName
: o nome da ação mostrado no painel Escolha uma ação no editor de fluxo de trabalho.actionDescription
: uma descrição detalhada da ação exibida quando o usuário está configurando a ação personalizada.actionCardContent
: uma descrição resumida exibida no cartão de ação.appDisplayName
: o nome da seção no painel "Escolher uma ação", em que todas as ações do aplicativo são exibidas. Se appDisplayName for definido para várias ações, a primeira ação encontrada será usada.inputFieldLabels
: um objeto que mapeia as definições de inputFields para os rótulos correspondentes que o usuário verá ao configurar a ação.outputFieldLabels
: um objeto que mapeia as definições de outputFields para os rótulos correspondentes mostrados na ferramenta de fluxos de trabalho.inputFieldDescriptions
: um objeto que mapeia as definições de inputFields para as descrições abaixo dos rótulos correspondentes.executionRules
: um objeto que mapeia as definições de executionRules às mensagens que serão mostradas para os resultados de execução das ações no histórico do fluxo de trabalho. Há uma seção separada nestes documentos para as regras de execução.
As definições de rótulo devem ser formatadas da seguinte forma:
Quando uma execução é realizada, uma solicitação https é enviada para actionUrl
.
callbackId
: um ID exclusivo para a execução específica. Se a execução da ação personalizada for bloqueio, use este ID.object
: os valores das propriedades solicitadas emobjectRequestOptions
.InputFields
: os valores para as entradas que o usuário preencheu.
A payload de execução será formatada da seguinte forma:
A resposta esperada deve estar formatada da seguinte forma:
Ao analisar a resposta de execução:
outputFields
: os valores dos campos de saída definidos anteriormente. Esses valores podem ser usados em ações posteriores.hs_execution_state
: um valor especial opcional que pode ser adicionado a outputFields. Não é possível especificar uma nova tentativa; somente os seguintes valores podem ser adicionados:- SUCCESS
- FAIL_CONTINUE
- BLOCK
- ASYNC
SUCCESS
e FAIL_CONTINUE
indicam que a ação foi concluída e o fluxo de trabalho deve passar para a próxima ação a ser executada. Se nenhum estado de execução for especificado, os códigos de status serão usados para determinar o resultado de uma ação:
- Códigos de status 2xx: a ação foi concluída com sucesso.
- Códigos de status 4xx: a ação falhou. A exceção aqui são os códigos de status de taxa limitada 429, que são retratados como novas tentativas e o cabeçalho Retry-After é respeitado.
- Códigos de status 5xx: indicam que houve um problema temporário com o serviço e uma nova tentativa será realizada para a ação mais tarde. Um sistema de retirada exponencial é usado para novas tentativas; novas tentativas serão feitas por até 3 dias antes de falhar.
Use as funções de execução para formatar os dados antes de enviá-los para actionURL
e analisar os dados de actionURL
. Há dois tipos de funções de execução:
PRE_ACTION_EXECUTION
POST_ACTION_EXECUTION
Função PRE_ACTION_EXECUTION
Use as funções PRE_ACTION_EXECUTION
para formatar os dados antes de enviá-los para actionURL
A definição da função será formatada da seguinte forma:
A entrada da função deve ser formatada da seguinte forma:
A saída da função deve ser formatada da seguinte forma:
Função POST_ACTION_EXECUTION
Depois de receber uma resposta de actionURL
, use uma função POST_ACTION_EXECUTION
para formatar os dados para o HubSpot.
A definição da função será formatada da seguinte forma:
A entrada da função deve ser formatada da seguinte forma:
The function output should be formatted as follows:
Execute ações de fluxo de trabalho personalizadas de forma assíncrona, bloqueando e, posteriormente, concluindo a ação.
Use ações personalizadas para bloquear a execução do fluxo de trabalho. Em vez de executar a próxima ação no fluxo de trabalho após a ação personalizada depois de receber uma resposta completed (2xx or 4xx status code)
do seu serviço, o fluxo de trabalho deixará de executar ("bloqueará") essa inscrição até você instruir o fluxo de trabalho para continuar.
Ao bloquear, você pode especificar um valor para o campo hs_default_expiration
, após a qual a sua ação personalizada será considerada expirada. A execução do fluxo de trabalho será retomada e a ação que se segue à ação personalizada será executada, mesmo que a ação não tenha sido concluída.
Para bloquear uma ação personalizada, sua resposta de execução de ação precisa ter o seguinte formato:
Para concluir uma execução de ação personalizada bloqueada, use o endpoint a seguir: /callbacks/{appId}/{callbackId}/complete
.
Formate o corpo da solicitação da seguinte maneira:
Especifique as regras na sua ação que determinam qual mensagem é exibida na página de histórico do fluxo de trabalho quando a ação for executada.
As regras corresponderão aos valores de saída da sua ação. Esses valores de saída devem ser fornecidos no corpo de resposta de actionURL
, no seguinte formato:
As mensagens reais podem ser especificadas na seção de rótulos da ação personalizada:
O executionRules
será testado na ordem fornecida. Se houver várias correspondências, apenas a mensagem da primeira regra que corresponde será mostrada ao usuário.
A regra corresponde quando a saída de execução corresponde a um valor especificado na regra. Por exemplo, considere esse conjunto de executionRules
:
Portanto, as seguintes correspondências ocorrerão:
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}
: isso corresponderia à primeira regra, poiserrorCode
é igual aALREADY_EXISTS
. Nesse caso, embora haja uma saídawidgetName
, ela não é usada na definição de regra, de forma que qualquer valor é permitido.{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}
: isso corresponderia à segunda regra, poisTOO_SMALL
é um dossizeError
correspondentes eerrorCode
éWIDGET_SIZE
.{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}
: isso corresponderia à terceira regra, pois, emboraerrorCode
sejaWIDGET_SIZE
, osizeError
não corresponde a nenhum dos valores especificados pela segunda regra (TOO_SMALL
ouTOO_BIG
).
Esse mecanismo de correspondência permite especificar erros de fallback, para que você possa ter erros específicos para casos de erro importantes, mas retornar a mensagens de erro mais genéricas para erros menos comuns. Este é um exemplo de como a mensagem personalizada seria exibida:
Depois de criar sua nova ação personalizada, você pode testá-la e publicá-la.
Testar ações personalizadas antes de publicar
Antes de publicar sua ação personalizada, você pode testar a execução da ação e a busca de opções apontando a URL para webhook.site. Dessa forma, você pode inspecionar a payload e retornar uma resposta específica.
Você também pode testar a ação no portal do desenvolvedor criando um fluxo de trabalho na ferramenta de fluxos de trabalho. Em seguida, adicione sua nova ação.
Publicação de ações personalizadas
Por padrão, as ações personalizadas são criadas em um estado não publicado. Ações personalizadas não publicadas ficam visíveis somente no portal do desenvolvedor associado ao aplicativo HubSpot correspondente. Para tornar uma ação personalizada visível para os usuários, atualize o sinalizador published
na definição da ação para true
. Se uma ação não for publicada, os portais que já adicionaram a ação ao fluxo de trabalho ainda poderão editá-la e executá-la. Porém, não poderão adicionar a ação novamente.
Example 1
A basic example with the following input fields, created for contact and deal workflows:
- a static input field
- a dropdown field with options
- a field whose value is a HubSpot owner
- a field whose value is pulled from a property (that the user creating the workflow selects) on the enrolled object.
Exemplo 2
A ação personalizada a seguir usa uma função sem servidor para transformar a payload que é enviada ao actionUrl configurado. Como nenhum objectTypes é especificado, essa ação estará disponível em todos os tipos de fluxos de trabalho.
Exemplo 3
A ação personalizada a seguir tem dependências de campo e opções que são buscadas de uma API. Como o tamanho do widget depende da cor do widget, o usuário não poderá inserir um valor para o tamanho do widget até que uma cor de widget seja escolhida.
O custo do widget também depende da cor do widget, mas é condicional no valor que o usuário seleciona para a cord o widget. O usuário não poderá inserir um valor para o custo do widget, a menos que Vermelho seja selecionado como a cor do widget.
Exemplo 4
O exemplo a seguir é uma ação personalizada de bloqueio. A API de retorno de chamada pode ser usada para informar a HubSpot para concluir a ação e fazer com que o objeto inscrito continue para a próxima ação no fluxo de trabalho.
Você não precisará especificar que a ação bloqueia no momento de criação da ação. Isso será determinado pela resposta do actionUrl configurado.
Agradecemos pelos seus comentários. Eles são muito importantes para nós.