Acciones de workflow personalizadas
Utiliza la herramienta de workflows de HubSpot para automatizar los procesos empresariales y permitir que tu equipo sea más eficiente. Puedes crear acciones personalizadas de workflow para integrar tu servicio con workflows de HubSpot.
Después de configurar tu acción personalizada, cuando los usuarios instalen tu aplicación, pueden agregar la acción personalizada a sus workflows.
Cuando se ejecutan esos workflows, las solicitudes HTTPS se enviarán a la URL configurada con la carga que configuras. Las solicitudes realizadas para tu acción personalizada usarán la versión v2 del X-HubSpot-Signature. Más información sobre cómo validar solicitudes de HubSpot.
También puedes pasar a las siguientes secciones:
- Antes de comenzar
- Definir tu acción personalizada
- Funciones
- Campos de entrada
- Obtener campos de datos externos
- Campos de salida
- Etiquetas
- Ejecución
- Ejecución de acciones personalizadas asíncronas
- Agregar mensajes de ejecución personalizados con reglas de ejecución
- Probar y publicar tu acción personalizada
- Necesitarás una cuenta de desarrollador de HubSpot con una aplicación de HubSpot. El logotipo de tu aplicación se utilizará como el icono para la acción personalizada.
- Al realizar solicitudes a los puntos finales de la acción del workflow personalizada, debes incluir la clave de tu cuenta de desarrollador de HubSpot en la URL de solicitud. Por ejemplo:
https://api.hubspot.com/automation/v4/actions/{appId}?hapikey={developer_API_key}
Para crear una acción de workflow personalizada, deberás definir la acción usando los siguientes campos. Esto también especifica el formato de solicitud para solicitudes procedentes de HubSpot, así como el manejo de respuestas de tu servicio.
actionUrl
: la URL donde se envía una solicitud HTTPS cuando se ejecuta la acción. El cuerpo de la solicitud contiene información sobre a nombre de qué usuario se está ejecutando la acción y qué valores se ingresaron para los campos de entrada.objectTypes
: con qué objetos de CRM se puede utilizar esta acción.published
: por opción predeterminada, las acciones personalizadas se crean en un estado no publicado. Las acciones no publicadas solo son visibles en el portal para desarrolladores asociado a tu aplicación HubSpot. Para que tu acción personalizada sea visible para los usuarios, actualiza la bandera publicada en tu definición de acción a verdadero.inputFields
: las entradas que recibe la acción. Estas serán rellenadas por el usuario.inputFieldDependencies
: estas reglas permiten que los campos se atenúen hasta que otros campos cumplan con condiciones específicas.outputFields
: los valores que se mostrarán en la acción que se pueden usar más tarde en el workflow. Una acción personalizada puede tener cero, una o muchas salidas.objectRequestOptions
: propiedades del objeto inscrito incluidas en la carga útil de actionUrl.labels
: copia que describe al usuario lo que representa los campos de la acción y lo que hace la acción. Se requieren etiquetas en inglés, pero estas también pueden especificarse en cualquiera de los siguientes idiomas compatibles: Francés (fr
), Alemán (de
), Japonés (ja
), Español (es
), Portugués de Brasil(pt-br
) y Holandés (nl
).executionRules
: una lista de definiciones que puedes especificar para exponer errores de tu servicio al usuario que crean el workflow.functions
: fragmentos de código que se ejecutan para transformar la carga útil que se envía a una url y/o transformar la respuesta desde esa url.
Ejemplo de definición de acción personalizada
La definición anterior mostrará lo siguiente en la herramienta de workflows:
Hay dos tipos de llamadas realizadas para acciones de workflow personalizadas:
- Recuperaciones de opciones de campo: se completa una lista de opciones válidas cuando un usuario está configurando un campo. Obtén más información sobre el uso de las recuperaciones de opciones de campo para obtener campos de datos externos.
- Solicitudes de ejecución de acciones: se realizan cuando una acción se ejecuta por un workflow que incluye tu acción personalizada.
Las funciones son fragmentos de código utilizados para modificar cargas útiles antes de enviarlas a una API. También puedes usar funciones para analizar los resultados de una API. Las funciones de HubSpot están respaldadas por AWS Lambda. En el siguiente código:
event
contiene los datos que se pasan a la funciónexports.main
es el método que se llamará cuando se ejecute la función.- La función
callback
se puede utilizar para devolver un resultado.
El código debe tener el siguiente formato:
Al configurar una función, el formato functionSource
estará en cadena. Asegúrate de que los caracteres del código tengan secuencia de escape.
Generalmente, la definición de una función seguirá el formato:
En el siguiente ejemplo, examina el código de entrada, la función utilizada y la salida producida.
Entrada de función:
Función utilizada:
Salida esperada:
Las definiciones de los campos de entrada se ajustarán al siguiente formato:
name
: el nombre interno del campo de entrada, separado de su etiqueta. La etiqueta que se muestra en la interfaz de usuario debe definirse utilizando la sección de etiquetas de la definición de acción personalizada.type
: el tipo de valor requerido por la entrada.fieldType
: cómo se debe representar el campo de entrada en la interfaz de usuario. Los campos de entrada imitan las propiedades de CRM. Obtén más información sobre combinaciones válidas detype
yfieldType
supportedValueTypes
tiene dos valores válidos:OBJECT_PROPERTY
: el usuario puede seleccionar una propiedad del objeto inscrito o una salida de una acción anterior para usarla como valor del campo.STATIC_VALUE
: debe usarse en todos los demás casos. Indica que el usuario debe introducir un valor por sí mismo.
isRequired
: determina si el usuario debe dar un valor para esta entrada o no
Las definiciones de los campos de entrada deben tener el siguiente formato:
También puedes codificar opciones para que el usuario seleccione:
La carga útil enviada a optionsURL
se formateará de la siguiente manera:
La respuesta esperada debe formatearse de la siguiente manera:
En el código anterior, ten en cuenta que se está configurando la paginación para limitar el número de opciones devueltas. Esto indica al workflow que se pueden cargar más opciones.
Además, la lista de opciones se puede buscar al incluir searchable:true
.
Para gestionar los datos externos, puedes incluir dos ganchos para personalizar el ciclo de vida de la opción de búsqueda de campos:
PRE_FETCH_OPTIONS
: una función que configura la carga útil enviada desde HubSpot.Post_FETCH_OPTIONS
: una función que transforma la respuesta de tu servicio en un formato que sea entendido por HubSpot.
Cuando se incluya, esta función se aplicará a cada campo de entrada. Puedes aplicarlo a un campo de entrada específico especificando un id
en la definición de la función.
La carga útil enviada desde HubSpot se formateará de la siguiente manera:
La respuesta debe formatearse de la siguiente manera:
Para analizar la respuesta en un formato esperado, según los campos de datos externos, usa una función POST_FETCH_OPTIONS
. La definición de una función POST_FETCH_OPTIONS
es la misma que una función PRE_FETCH_OPTIONS
. Cuando se definen opciones externas de obtención de datos externos, se representará un menú desplegable en las opciones de entrada para la acción.
La entrada de función se formateará de la siguiente manera:
La salida de la función se formateará de la siguiente manera:
Utiliza campos de salida para generar valores de tu acción personalizada para usar en otras acciones. La definición de los campos de salida es similar a la definición de los campos de entrada:
- name: cómo se hace referencia a este campo en otras partes de la acción personalizada. La etiqueta que se muestra en la interfaz de usuario debe definirse utilizando la sección "etiquetas" de la acción personalizada
- type: el tipo de valor requerido por la entrada.
- fieldType: es cómo se debe representar el campo de entrada en la interfaz de usuario. Los campos de entrada imitan las propiedades de CRM. Obtén más información sobre combinaciones válidas de
type
yfieldType
El campo de salida debe formatearse de la siguiente manera:
Cuando se utiliza un campo de salida, los valores se analizan a partir de la respuesta de actionURL
. Por ejemplo, puedes copiar campos de salida en una propiedad existente en HubSpot.
Utiliza etiquetas para agregar texto a tus salidas o entradas en el editor de workflow. Las etiquetas se cargan en el servicio de idiomas de HubSpot y pueden tardar unos minutos en mostrarse. Los portales configurados para diferentes regiones o idiomas mostrarán la etiqueta en el idioma correspondiente, si está disponible.
labels
: copia que describe al usuario lo que representa los campos de la acción y lo que hace la acción. Se requieren etiquetas en inglés, pero estas también pueden especificarse en cualquiera de los siguientes idiomas compatibles: Francés (fr
), Alemán (de
), Japonés (ja
), Español (es
), Portugués de Brasil(pt-br
)y Holandés (nl
).actionName
: el nombre de la acción que aparece en el panel Elegir una acción en el editor de workflows.actionDescription
: una descripción detallada de la acción que se muestra cuando el usuario está configurando la acción personalizada.actionCardContent
: una descripción resumida que se muestra en la tarjeta de la acción.appDisplayName
: el nombre de la sección en el panel "Elegir una acción" donde se muestran todas las acciones de la aplicación. Si appDisplayName se define para múltiples acciones, se utiliza la primera que se encuentre.inputFieldLabels
: un objeto que mapea las definiciones de inputFields a las etiquetas correspondientes que el usuario verá cuando configure la acción.outputFieldLabels
: un objeto que mapea las definiciones de outputFields a las etiquetas correspondientes que se muestran en la herramienta de workflows.inputFieldDescriptions
: un objeto que mapea las definiciones de inputFields a las descripciones debajo de las etiquetas correspondientes.executionRules
: un objeto que asigna las definiciones de tus executionRules a los mensajes que se mostrarán para los resultados de la ejecución de acciones en el historial del workflow. Hay una sección separada en estos documentos para las reglas de ejecución.
Las definiciones de etiquetas deben tener el siguiente formato:
Cuando se ejecuta una ejecución, se envía una solicitud https al actionUrl
.
callbackId
: un ID único para la ejecución específica. Si la ejecución de la acción personalizada está bloqueando, utiliza este ID.object
: los valores de las propiedades solicitadas enobjectRequestOptions
.InputFields
: los valores de las entradas que el usuario ha rellenado.
La carga útil de ejecución se formateará de la siguiente manera:
La respuesta esperada debe formatearse de la siguiente manera:
Al observar la respuesta de ejecución:
outputFields
: los valores de los campos de salida definidos anteriormente. Estos valores se pueden utilizar en acciones posteriores.hs_execution_state
: un valor especial opcional que se puede agregar a outputFields. No es posible especificar un reintento, solo se pueden agregar los siguientes valores:- SUCCESS
- FAIL_CONTINUE
- BLOCK
- ASYNC
SUCCESS
y FAIL_CONTINUE
indican que la acción se ha completado y que el workflow debe pasar a la siguiente acción a ejecutar. Si no se especifica ningún estado de ejecución, se utilizarán códigos de estado para determinar el resultado de una acción:
- Códigos de estado 2xx: la acción se ha completado correctamente.
- Códigos de estado 4xx: la acción ha fallado. La excepción son los códigos de estado Tasa limitada 429, que se vuelven a tratar como reintentos y se respeta el título Reintentar después.
- Códigos de estado 5xx: hubo un problema temporal con el servicio y la acción se volverá a intentar más tarde. Se utiliza un sistema de retroceso exponencial para los reintentos. Los reintentos continuarán hasta 3 días antes de fallar.
Utiliza las funciones de ejecución para formatear los datos antes de enviarlos a actionURL
y analizar los datos de actionURL
. Hay dos tipos de funciones de ejecución:
PRE_ACTION_EXECUTION
POST_ACTION_EXECUTION
Función PRE_ACTION_EXECUTION
Utilice las funciones PRE_ACTION_EXECUTION
para formatear los datos antes de enviarlos a actionURL
La definición de la función tendrá el siguiente formato:
La entrada de función debe tener el siguiente formato:
La salida de la función debe formatearse de la siguiente manera:
Función POST_ACTION_EXECUTION
Después de recibir una respuesta de actionURL
, use una función POST_ACTION_EXECUTION
para formatear los datos para HubSpot.
La definición de la función tendrá el siguiente formato:
La entrada de función debe tener el siguiente formato:
The function output should be formatted as follows:
Ejecuta acciones de worflow personalizadas de forma asíncrona bloqueando y completando posteriormente la acción.
Utiliza acciones personalizadas para bloquear la ejecución del workflow. En lugar de ejecutar la siguiente acción en el workflow después de la acción personalizada después de recibir una respuesta completado (2xx o 4xx)
de tu servicio, el workflow dejará de ejecutarse ("bloquear") esa inscripción hasta que el workflow continúe.
Al bloquear, puedes especificar un valor para el campo hs_default_expiration
, después de que tu acción personalizada se considere vencida. La ejecución del workflow se reanudará y la acción que sigue a la acción personalizada se ejecutará, aunque no se haya completado la acción.
Para bloquear una acción personalizada, la respuesta de ejecución de tu acción debe tener el siguiente formato:
Para completar la ejecución de una acción personalizada bloqueada, usa el siguiente punto de terminación: /callbacks/{appId}/{callbackId}/complete
.
Formatea el cuerpo de la solicitud de la siguiente manera:
Especifica reglas sobre tu acción que determinen qué mensaje aparece en la página de historial del workflow cuando se ejecuta la acción.
Las reglas se emparejarán con los valores de salida de tu acción. Estos valores de salida se deben proporcionar en el cuerpo de la respuesta de actionURL
, en el siguiente formato:
Los mensajes reales se pueden especificar en la sección de etiquetas de la acción personalizada:
Las executionRules
se probarán en el orden proporcionado. Si hay varias coincidencias, solo el mensaje de la primera regla que coincide se muestra al usuario.
La regla coincide cuando la salida de ejecución corresponde a un valor especificado en la regla. Por ejemplo, considera este conjunto de executionRules
:
Con lo anterior, se producirían las siguientes coincidencias:
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}
: Esto coincidirá con la primera regla, ya queerrorCode
es igual aALREADY_EXISTS
. En este caso, aunque haya una salidawidgetName
, no se utiliza en la definición de regla, por lo que se permite cualquier valor.{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}
: Esto coincidirá con la segunda regla, ya queTOO_SMALL
es uno de los valores desizeError
que coinciden, yerrorCode
esWIDGET_SIZE
.{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}
: Esto coincidirá con la tercera regla, ya que aunque elerrorCode
esWIDGET_SIZE
, elsizeError
no coincide con ninguno de los valores especificados por la segunda regla (TOO_SMALL
oTOO_BIG
).
Este mecanismo de coincidencia te permite especificar errores de reserva, por lo que puedes tener errores específicos para casos de error importantes, pero regresa a mensajes de error genéricos para errores más comunes. Aquí tienes un ejemplo de cómo se mostraría el mensaje personalizado:
Después de crear tu nueva acción personalizada, puedes probarla y publicarla.
Probar acciones personalizadas antes de publicar
Antes de publicar su acción personalizada, puedes probar la ejecución de la acción y las opciones de obtención apuntando la URL a webhook.site. Esto te permite inspeccionar la carga útil y devolver una respuesta específica.
También puedes probar la acción en tu portal de desarrolladores creando un workflow en la herramienta de workflows. A continuación, agrega tu nueva acción.
Cuando hayas completado tus pruebas, se recomienda archivar tus acciones de prueba. Obtén más información sobre las acciones de archivado en la sección Archivar una acción personalizada en la pestaña Puntos de terminación.
Publicar acciones personalizadas
Por opción predeterminada, las acciones personalizadas se crean en un estado no publicado. Las acciones personalizadas no publicadas solo son visibles en el portal de desarrolladores asociado con la aplicación HubSpot correspondiente. Para que tu acción personalizada sea visible para los usuarios, actualiza la bandera publicado
en tu definición de acción a verdadero
. Si una acción no está publicada, los portales que ya han agregado la acción a tu workflow aún podrán editar y ejecutar acciones ya agregadas. Sin embargo, no podrán volver a agregar la acción.
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.
Ejemplo 2
La siguiente acción personalizada usa una función sin servidor para transformar la carga que se envía a la acción configurada actionUrl. Dado que no se especifican objectTypes, esta acción estará disponible en todos los tipos de workflows.
Ejemplo 3
La siguiente acción personalizada tiene dependencias y opciones de campo que se recuperan desde una API. Debido a que el tamaño del widget depende del color del widget, el usuario no podrá introducir un valor para el tamaño del widget hasta que se elige un color del widget.
El costo del widget también depende del color del widget, pero está condicionado al valor que el usuario selecciona para el color del widget; el usuario no podrá introducir un valor para el costo del widget, a menos que Red esté seleccionada como el color del widget.
Ejemplo 4
El siguiente ejemplo es una acción personalizada de bloqueo. La API de devolución de llamadas se puede usar para indicarle a HubSpot que complete la acción y hacer que el objeto inscrito pase a la siguiente acción en el workflow.
No necesitarás especificar que la acción se bloquea en el momento en que creas la acción; eso será determinado por la respuesta de tu actionUrlconfigurada.
Gracias por tus comentarios, son muy importantes para nosotros.