Documentación: Nodo Ejecutar Acción de Objeto (Execute Object Action)¶

Descripción General¶

El Nodo Ejecutar Acción de Objeto (Execute Object Action) es un nodo de acción que permite enviar comandos específicos ("acciones") de manera directa y manual a uno o varios objetos/dispositivos a través de sus respectivos controladores (drivers).

A diferencia de los nodos de acción especializados (como el de capturar imagen o enviar un mensaje), este nodo actúa como una interfaz genérica y flexible, ideal para realizar operaciones avanzadas que no cuentan con un nodo propio en la biblioteca de automatizaciones.

¿Cuándo usar este nodo?¶

Utiliza este nodo cuando necesites:

Enviar comandos específicos del fabricante a un dispositivo (por ejemplo, mover una cámara PTZ a una posición preestablecida, activar una salida de relé, o iniciar la descarga de un videoclip).
Ejecutar la misma acción sobre múltiples objetos o canales de forma simultánea.
Controlar funciones avanzadas de hardware que solo están expuestas a través de métodos de acción del driver.
Realizar pruebas o depuración (debugging) de acciones enviando datos personalizados (payload) directamente al dispositivo.

Configuración del Nodo¶

El nodo cuenta con dos pestañas de configuración en la parte superior: Formulario (Form) y Editor de JSON (JSON Editor).

Configuración vacía del nodo Ejecutar acción de objeto

Vista Formulario¶

1. Seleccionar acción¶

Este campo permite buscar y elegir la acción que se desea enviar. Al hacer clic en la lupa o en el campo de texto, se desplegará una lista categorizada por los dominios y marcas de los drivers configurados en el sistema (por ejemplo, onvif_standard.switch, hanwha_camera.video_channel.stream, etc.).

Nota: La lista muestra el total de dominios y acciones disponibles en tu instalación actual (por ejemplo: "Total: 29 domain(s), 137 action(s)").

2. Seleccionar objeto¶

Permite buscar y seleccionar los objetos o dispositivos específicos que ejecutarán la acción. Este nodo soporta la selección múltiple, lo que te permite aplicar la acción a varios dispositivos a la vez.

En la interfaz verás etiquetas para cada objeto seleccionado que puedes eliminar fácilmente haciendo clic en la x (por ejemplo: Speaker audiooutput1, Siera Switch - relay_1, etc.).

3. Carga útil (Payload)¶

El panel de Carga útil define los parámetros o datos adicionales requeridos para que la acción se ejecute correctamente. Dependiendo de la acción seleccionada, puedes configurarla de dos formas:

Key-Value: Una lista estructurada donde agregas manualmente un campo de texto con la clave (Key) y el valor (Value) mediante el botón + Add entry.
JSON: Un cuadro de texto para ingresar directamente los datos en formato estructurado JSON.

Formulario configurado del nodo Ejecutar acción de objeto

Vista Editor de JSON¶

Si cambias a la pestaña Editor de JSON, verás la representación estructurada de los parámetros del nodo en formato JSON, donde puedes usar expresiones de plantilla para parametrizar dinámicamente los campos.

Estructura JSON (Parámetros de entrada)¶

A continuación se muestra el esquema del JSON de configuración real en la pestaña JSON Editor cuando se selecciona, por ejemplo, la acción para generar un clip de video en múltiples dispositivos:

{
  "action": "video_channel.action.videoclip",
  "domain": "hanwha.cctv.channel",
  "objects_id": [
    "onvif_standard.microphone.27.audiosource_cam1",
    "onvif_standard.speaker.27.audiooutput1",
    "onvif_standard.switch.27.relay_1",
    "onvif_standard.video_channel.27.videosource_cam1"
  ],
  "payload": "{\n  \"start_timestamp\": \"2024-06-15T14:00:00Z\",\n  \"end_timestamp\": \"2024-06-15T14:05:00Z\",\n  \"resolution\": \"1920x1080\",\n  \"timeout\": 60\n}"
}

Campos requeridos¶

Campo	Tipo	Descripción
`action`	string	Identificador único de la acción soportada por el driver (ej. `domain.action.name`).
`domain`	string	El dominio del driver del dispositivo (ej. `hanwha.cctv.channel`).
`objects_id`	array (strings)	Lista de identificadores únicos (IDs de hardware) de los objetos seleccionados para ejecutar la acción.
`payload`	string	Parámetros específicos requeridos por la acción representados como una cadena de texto (string) en formato JSON serializado.

Output: Dónde viene la data del nodo¶

Cuando el nodo finaliza la ejecución de la acción, la sección Output (Salida) del nodo contiene una propiedad llamada response. Esta propiedad guarda un arreglo con los resultados detallados de la ejecución para cada uno de los objetos seleccionados.

Resultados de la ejecución en la salida del nodo

Campos de la salida (`response`)¶

Cada elemento dentro del arreglo response contiene:

Campo	Tipo	Descripción
`id`	string	ID único de la ejecución del comando.
`executed_at`	string	Fecha y hora en la que se ejecutó la acción (formato RFC3339).
`payload`	object	La carga útil (parámetros) enviada al dispositivo.
`domain`	string	El dominio del driver del dispositivo.
`action`	string	La acción específica ejecutada.
`object_id`	array (strings)	Lista de identificadores de los objetos que ejecutaron la acción.
`result`	object	Datos de respuesta adicionales retornados por el dispositivo o driver.
`status`	integer	Código de estado HTTP de la respuesta de ejecución (por ejemplo, `200` para éxito).

Ejemplo de salida¶

{
  "response": [
    {
      "id": "6a31bd77f9990673727c570a",
      "executed_at": "2026-06-16T21:17:43Z",
      "payload": {
        "end_timestamp": "2024-06-15T14:05:00Z",
        "resolution": "1920x1080",
        "start_timestamp": "2024-06-15T14:00:00Z",
        "timeout": 60
      },
      "domain": "hanwha.cctv.channel",
      "action": "video_channel.action.videoclip",
      "object_id": [
        "onvif_standard.video_channel.27.videosource_cam1"
      ],
      "result": {},
      "status": 200
    }
  ]
}

Usar la salida en nodos posteriores¶

Puedes referenciar las respuestas de la ejecución utilizando la clave del nodo (NodeKey). Por ejemplo, para obtener el estado del primer objeto ejecutado:

{{node_key.response[0].status}}
{{node_key.response[0].id}}

(Sustituye node_key por la clave real de tu nodo en el lienzo).

Ejemplos de uso¶

Ejemplo 1: Activación manual de una salida física (Relé/Switch)¶

Caso de uso: Activar de manera directa una salida de alarma física conectada a un switch ONVIF. - Acción: onvif_standard.switch.turn_on - Objeto: Seleccionar el switch correspondiente. - Payload: No requiere parámetros adicionales (vacío).

Ejemplo 2: Generar y descargar un clip de video de múltiples cámaras¶

Caso de uso: Solicitar la extracción de un fragmento de video grabado de 5 minutos en varias cámaras simultáneamente para almacenamiento externo. - Acción: video_channel.action.videoclip - Objetos: Seleccionar las cámaras de video deseadas. - Payload (Key-Value): - start_timestamp: 2024-06-15T14:00:00Z - end_timestamp: 2024-06-15T14:05:00Z - resolution: 1920x1080 - timeout: 60

Validación y errores comunes¶

Al ejecutar este nodo, el sistema valida que los drivers involucrados estén activos y conectados.

Condición / Error	Causa / Solución habitual
Lista de acciones/objetos vacía	El driver correspondiente puede estar apagado o desconectado en el panel de control de Drivers. Asegúrate de verificar el estado de conexión del driver (por ejemplo, `driver.milestone` o `onvif_standard`).
Status 400/500 en la respuesta	Los parámetros de la carga útil (Payload) podrían ser incorrectos, incompletos o incompatibles con el comando esperado por el hardware.
Objeto no encontrado	El objeto fue eliminado de la base de datos o su identificador de hardware cambió.

Buenas prácticas¶

Verificar la conectividad de los drivers antes de desplegar flujos que utilicen este nodo, ya que las acciones dependen dinámicamente de la comunicación en tiempo real con los dispositivos.
Configurar tiempos de espera (timeout) adecuados en la carga útil si la acción requiere procesamiento prolongado en el hardware (como la generación de clips de video).
Nombrar el nodo con claridad (por ejemplo: "Generar Videoclip Cámaras") para facilitar la legibilidad del flujo y la llamada de sus variables en nodos subsiguientes.