Documentación: Nodo Condicional Geofence (Zonas GPS)

Descripción General

El Nodo Condicional Geofence evalúa si objetos con posición GPS están dentro o fuera de una o varias zonas (polígonos). Las zonas pueden definirse como polígonos fijos, como objetos cuya geometría define la zona, o por etiquetas que referencian zonas tipo gps_zone.

Si al menos un objeto cumple la condición (inside/outside según activation_method), la ejecución continúa por la ruta true; de lo contrario, por la ruta false.

¿Cuándo usar este nodo?

Utiliza este nodo cuando necesites:

• Activar acciones cuando un vehículo o activo entra o sale de una zona (almacén, estacionamiento, área restringida)
• Detectar si un objeto está fuera de zonas permitidas (alertas de intrusión o salida de perímetro)
• Combinar flotas o dominios con múltiples zonas definidas por objetos o etiquetas
• Integrar lógica de geolocalización en automatizaciones (rutas, cercanía, perímetros)

Rutas de salida

Este nodo tiene dos rutas:

• true: al menos un objeto cumple la condición (está inside o outside según activation_method) y se identificó objeto y zona.
• false: ningún objeto cumple la condición, o hubo error al evaluar.

Output del nodo

El resultado se expone en el output del nodo como mapa con:

Campo	Tipo	Descripción
object_id	string	ID del objeto que cumplió la condición (vacío si ninguno).
domain	string	Dominio del objeto (solo cuando se usó domains en lugar de objects_id).
type_zone	string	Origen de la zona: "object", "tag" o implícito si la zona viene de polígono.
value_zone	string	Identificador de la zona (p. ej. object_id de la zona o tag).

Si ningún objeto cumple, object_id queda vacío y el conector devuelto es false.

Configuración del Nodo

Obligatorios (al menos uno de cada grupo)

1. Qué objetos evaluar (uno de los dos):

Campo	Tipo	Descripción
objects_id	[]string	Lista de IDs de objetos a trackear. La posición se obtiene del estado de cada objeto (latitude / longitude en propiedades adicionales).
domains	[]string	Lista de dominios; se obtienen todos los objetos del dominio y se evalúan igual que con objects_id.

2. Qué zonas usar (al menos uno de los tres):

Campo	Tipo	Descripción
zones_as_polygons	[]ZoneAsPolygon	Polígonos definidos explícitamente (lista de puntos).
zones_as_objects	[]ZoneAsObject	Zonas definidas por objetos; el polígono se lee del estado del objeto (campo points en propiedades adicionales).
zones_from_tags	[]ZoneFromTag	Zonas obtenidas por etiqueta: se buscan objetos tipo gps_zone con ese tag y se usa su geometría.

3. Cómo activar:

Campo	Tipo	Descripción
activation_method	string	inside: dispara cuando el objeto está dentro de alguna zona. outside: cuando está fuera de todas. both: valor aceptado en validación (comportamiento depende de la implementación).

Warning

Si falta al menos un origen de objetos (objects_id o domains) o un origen de zonas (zones_as_polygons, zones_as_objects o zones_from_tags), o si activation_method no es válido, Validate() devuelve error.

Estructuras de zonas

ZoneAsPolygon

Polígono definido por una lista de puntos.

Campo	Tipo	Descripción
polygon	[]Point	Lista de puntos en orden (polígono cerrado).

Cada Point:

Campo	Tipo
latitude	float64
longitude	float64

ZoneAsObject

Zona dada por un objeto cuyo estado contiene la geometría.

Campo	Tipo	Descripción
object_id	string	ID del objeto que representa la zona.

El estado de ese objeto debe tener en propiedades adicionales un campo points: string JSON con array de puntos {"lat": <number>, "lng": <number>} (o latitude/longitude según implementación).

ZoneFromTag

Zonas cargadas por etiqueta (objetos tipo gps_zone con ese tag).

Campo	Tipo	Descripción
tag	string	Etiqueta para filtrar objetos tipo gps_zone; sus geometrías se usan como zonas.

Resolución de zonas

El motor resuelve las zonas en este orden:

1. Si hay zones_as_polygons, se usan tal cual.
2. Si no, y hay zones_as_objects, se obtiene el estado de cada objeto y se parsea points a polígono.
3. Si no, y hay zones_from_tags, se buscan objetos gps_zone por tag y se construyen polígonos desde su estado.
4. Si no hay ninguno de los tres, se usan todas las zonas tipo gps_zone del sistema (comportamiento por defecto de integración).

Solo se usa una de estas fuentes; no se mezclan listas.

Lógica de evaluación

• Posición del objeto: se obtiene con el estado más reciente del objeto; en las propiedades adicionales deben existir latitude y longitude (strings parseables a número).
• Dentro/fuera: se usa el algoritmo Ray Casting (point-in-polygon) sobre cada polígono. El objeto “está dentro” si está dentro de al menos una zona.
• Orden: se recorren primero los objetos (por objects_id o por cada domains). El primer objeto que cumpla la condición (inside/outside) hace que el nodo devuelva ese object_id, el índice de zona correspondiente (y por tanto type_zone / value_zone) y conector true.

Estructura JSON

Ejemplo mínimo (objetos y zonas vacíos; en uso real debes definir al menos un origen de objetos y uno de zonas):

{
  "zones_as_objects": [],
  "objects_id": [],
  "domains": [],
  "zones_from_tags": [],
  "activation_method": "inside"
}

Ejemplo: objetos + polígonos

{
  "objects_id": ["vehicle-001"],
  "zones_as_polygons": [
    {
      "polygon": [
        { "latitude": 19.4326, "longitude": -99.1332 },
        { "latitude": 19.435, "longitude": -99.1332 },
        { "latitude": 19.435, "longitude": -99.128 },
        { "latitude": 19.4326, "longitude": -99.128 }
      ]
    }
  ],
  "activation_method": "inside"
}

Ejemplo: dominios + zonas por objeto

{
  "domains": ["fleet-a"],
  "zones_as_objects": [{ "object_id": "zone-warehouse-1" }],
  "activation_method": "inside"
}

El objeto zone-warehouse-1 debe tener en estado (propiedades adicionales) un campo points con un JSON de puntos [{"lat": ..., "lng": ...}, ...].

Ejemplo: zonas por tag

{
  "objects_id": ["asset-001"],
  "zones_from_tags": [{ "tag": "restricted-area" }],
  "activation_method": "outside"
}

Se buscan objetos tipo gps_zone con tag restricted-area; si el objeto asset-001 no está dentro de ninguna de esas zonas, el nodo sale por true.

Solución de Problemas

Error de validación: falta objetos o zonas

Causa: no se definió al menos un origen de objetos (objects_id o domains) o un origen de zonas (zones_as_polygons, zones_as_objects o zones_from_tags).

Solución: configura al menos un elemento en objects_id o domains, y al menos una zona en uno de los tres arrays de zonas.

Error: activation_method inválido

Causa: activation_method no es inside, outside o both.

Solución: usa únicamente inside, outside o both.

El nodo siempre devuelve false

Causas posibles:

• Los objetos no tienen en su estado latitude y longitude (propiedades adicionales).
• Las zonas por objeto no tienen en estado el campo points con formato JSON válido.
• Con activation_method: "outside", el objeto está dentro de alguna zona (por tanto no cumple “fuera de todas”).

Solución: verifica el estado de los objetos y la geometría de las zonas en el runtime de automatización.

Mejores Prácticas

• Asegura que los objetos trackeados (p. ej. GPS Tracker) expongan latitude y longitude en el estado.
• Para zonas reutilizables, usa objetos o tags (zones_as_objects, zones_from_tags) en lugar de polígonos fijos en el JSON cuando sea posible.
• Para “alerta si sale de zona permitida”, usa activation_method: "outside" y define las zonas permitidas.
• El algoritmo es point-in-polygon (Ray Casting); no se considera radio ni curvatura terrestre.

---